Relay Sentry

Introduction

Relay Sentry is a Shopify app that connects a merchant's store to Fruugo, the cross-border marketplace. It keeps the product feed Fruugo requires up to date, pulls in orders Fruugo releases and creates them in Shopify, and reports tracking back to Fruugo once they ship. It's built and installed as an embedded Shopify app, with relaysentry.app as its home on the web for merchants evaluating it before they install.

Background

Merchants selling on Fruugo through Shopify were mostly stuck with generic multi-marketplace connectors, retrofitted to Fruugo's specific catalogue and order rules rather than built around them. Fruugo publishes an exacting spec: stable, never-reused SKU identifiers, an exact category path, images on a white background, VAT handled one way or the other but never both, lead times and restock dates that can't both be set at once, and an order lifecycle where a pending order has to be confirmed, cancelled, or handled within one business day. A connector that treats those as generic e-commerce fields rather than Fruugo's own rules produces rejected feeds and orders that sit unconfirmed.

The brief for Relay Sentry was to build to Fruugo's documentation first, so a merchant's feed and order handling matches what Fruugo actually validates against, and to build it as a proper multi-tenant SaaS product from the first commit rather than a single-store script — including a path for merchants migrating off an existing connector (CedCommerce) to adopt their existing Fruugo product and SKU IDs without Fruugo seeing every listing as brand new, and without double-importing orders the old connector already brought in.

What it does

Once a store installs the app, Relay Sentry provisions a tenant and a default Fruugo account, and walks the merchant through a guided setup with a checklist built from the store's real state rather than a generic onboarding form. From there it runs three flows:

• Catalogue: Shopify product and inventory changes are mapped to Fruugo's feed format and published on Fruugo's schedule, with per-SKU validation surfaced in the app instead of a single pass/fail per job.
• Orders: the app polls Fruugo's Orders API for released orders; Fruugo's asynchronous response maps marketplace SKUs to Shopify variants, creates the Shopify order idempotently, and requests Fruugo's confirmation once the order exists and inventory is reserved.
• Fulfilment: Shopify fulfilment webhooks capture carrier and tracking data and report it back to Fruugo, and the order's state in Relay Sentry only advances once Fruugo's matching callback comes back — it doesn't mark anything shipped on the strength of a label alone.

Merchants moving off CedCommerce or another connector can bring their existing Fruugo ProductId/SkuId values in on a dedicated migration screen, and set an order cutover time so orders the old connector already imported are never recreated.

The problems it was built to solve

Relay Sentry's public site names five specific problems merchants hit with Fruugo connectors, each with the feature built to close it. They're worth spelling out, because they're the actual reason several of the technical decisions above exist.

Orders that fail to import, with no explanation

A Fruugo order that never becomes a Shopify order doesn't get packed, confirmed, or shipped — and most connectors just log a raw error like "Unable to reserve inventory" with no retry button and no hint what to do. The causes are almost always one of a few things: the Fruugo SKU doesn't match a Shopify variant, there's no stock at the fulfilling location, the variant was deleted and recreated under a new ID, or Shopify/Fruugo was briefly unreachable. Meanwhile Fruugo's clock keeps running — orders left unconfirmed for seven days auto-cancel and refund the customer, and cancellations count against the retailer's performance score.

The fix: a fix queue on the Orders page that groups stuck orders by cause, then by SKU, so ten orders failing for the same reason show as one row. Each group states the cause in plain English with Shopify's or Fruugo's original message quoted underneath, mapping a SKU once fixes every order waiting on it, and "Retry all fixed" only fires for orders Relay Sentry has actually re-checked against live Shopify stock and variants.

Products that never go live, with no reason given

Fruugo only accepts a product with a valid category, barcode, brand, description, title, image and SKU — miss any one and the product is silently dropped or rejected. Categories are the worst of it: Fruugo's category list runs to thousands of entries, and mapping each product type by hand from an unsearchable dropdown can take days, during which nothing of that type sells.

The fix: every product in the Catalog carries one specific reason it isn't live (no category, invalid barcode, no image, rejected by Fruugo, and a dozen others), filterable so a merchant fixes one cause across the whole catalogue at once. The Mappings page queues unmapped product types biggest-first, with up to three suggested categories drawn from Fruugo's own list — accept one with a click, and nothing saves until you do.

Missing Fruugo's confirm and ship deadlines

Fruugo runs every order on a clock: confirm or cancel within one business day, ship by the end of the next, with tracking. Miss it and the order auto-cancels, the customer is refunded, and it dings the retailer's performance score — and each step is easy to lose when orders live in one system and get handled in another.

The fix: automatic polling every few minutes over an overlapping 24-hour window so an order is never skipped, confirmation sent back to Fruugo the moment the Shopify order exists (and resent on a schedule if Fruugo doesn't acknowledge it), and tracking sent automatically on fulfilment — a fulfilment with no tracking number is held and flagged rather than sent empty. The Orders page surfaces anything approaching the deadline before it's missed, not after.

Switching connectors without starting over

Fruugo identifies a listing by the product and SKU IDs whatever connector originally sent them, and neither the feed nor the API can delete a listing — so a new app sending its own IDs just creates duplicate listings alongside ones that never go away, on top of redoing months of category and pricing setup by hand, all while orders risk being imported twice by both apps at once.

The fix: the migration screen reads the old connector's actual feed, matches each row to a Shopify variant by SKU, barcode, or variant ID, and adopts Fruugo's existing IDs so it updates the live listing instead of duplicating it — refusing to guess when a match is ambiguous rather than risk binding the wrong product. It also infers category rules, currency, VAT, lead time and pricing from what the old feed actually sent (only when the data agrees), and an order-cutover date stops the old connector's already-imported orders from being pulled in twice.

Stock and listings drifting out of date

A connector that only sends a periodic snapshot lets Fruugo keep selling stock that's already gone, and since neither the feed nor the API can delete a listing, a product taken down in Shopify can keep quietly selling on Fruugo for weeks.

The fix: the feed regenerates within minutes of a stock, price, or product change; a merchant-configurable safety buffer holds back the last few units so they can't sell out on both channels at once; and an archived, drafted, or deleted product is explicitly marked unavailable on Fruugo rather than just dropped from the feed. Listings published through the Product API get stock pushed as it happens and reconciled against Fruugo every few minutes as a backstop.

How it was built

Relay Sentry is an embedded Shopify app on React Router and Polaris, backed by PostgreSQL through Prisma, deployed on Fly.io. A few decisions came directly out of what running against a real marketplace API requires rather than a typical CRUD app:

• A durable job queue, not a cron script. Catalogue changes coalesce into PostgreSQL-backed jobs, drained by an in-process scheduler every five minutes with atomic claims, exponential retries, stale-lock recovery, and a dead-letter state for jobs that keep failing. A scheduled GitHub Actions workflow calls the same endpoints as a backup, and fails the run instead of silently swallowing a missed tick.
• Fruugo credentials encrypted at rest. Each tenant's Fruugo API credentials are stored with AES-256-GCM rather than in plain columns.
• Privacy compliance built in, not stubbed. A public Shopify app has to implement customers/data_request, customers/redact, and shop/redact. Relay Sentry's versions actually do the work — a data export that expires after 30 days, deletion of a customer's order records, and a shop redact that cascades through every table for that tenant — with legal review as the remaining step, not the code.
• State only advances on Fruugo's word. Order confirmation and shipment status are modeled as explicit queued/processing/confirmed states rather than optimistic updates, because Fruugo, not the app, is the source of truth for what the marketplace has actually accepted.

Where to see it

The marketing site is at relaysentry.app. The app itself runs embedded inside Shopify Admin once a merchant installs it, currently in multi-store beta ahead of a full Shopify App Store listing.