FlowRelay
Setup
Trigger variants and event mapping
Use this reference when an operator or authorized agent needs to choose the right Shopify Flow trigger variant and map sender payload fields without guessing.
Steps
Complete these in order.
- 01Choose the trigger variant based on what the Shopify Flow workflow needs to receive, not based on the sender system's name.
- 02Use Generic when the workflow only needs a custom external event and no Shopify resource reference.
- 03Use Order, Customer, or Product when Flow needs a native Shopify resource reference and the sender can provide that object's Shopify ID or GID.
- 04Use Inventory, Fulfillment, Return/refund, or Company/B2B when the workflow belongs in that operational lane and needs related-resource text context.
- 05Map only existing JSON fields from the sender payload. The current Shopify Flow edition does not transform, template, filter, or compute new values.
- 06Send a synthetic test event and confirm the receipt mapping result before enabling production traffic.
Decision rule #
Pick the narrowest variant that matches what Shopify Flow needs. If the workflow only needs a custom event, start with Generic. If it needs a native Shopify object, use the native resource variant. If it needs one of FlowRelay's operational lanes, use the related-resource variant.
| Workflow need | Choose | Required mapping |
|---|---|---|
| A custom external event starts the workflow. | External event | No resource identifier path. |
| Shopify Flow needs a native order, customer, or product reference. | External order event, External customer event, or External product event | Resource ID path. |
| The event belongs to inventory, fulfillment, return/refund, or company/B2B operations. | The matching operational trigger variant | Related resource ID path. |
Trigger variants #
These are the only Shopify Flow trigger variants in the current edition. Agents should use the API value when calling Agent Operations. Operators see the label in the embedded app and in Shopify Flow setup.
| Operator label | API value | Use when | Identifier field | Flow context |
|---|---|---|---|---|
| External event | generic | The workflow only needs a custom external event. | None | No Shopify resource identifier is shown. |
| External order event | order | The sender event is about a specific Shopify order. | Resource ID path | Native order reference. |
| External customer event | customer | The sender event is about a specific Shopify customer. | Resource ID path | Native customer reference. |
| External product event | product | The sender event is about a specific Shopify product. | Resource ID path | Native product reference. |
| External inventory event | inventory | The workflow belongs in an inventory operations lane. | Related resource ID path | Related resource type and text identifier context. |
| External fulfillment event | fulfillment | The workflow belongs in a fulfillment operations lane. | Related resource ID path | Related resource type and text identifier context. |
| External return/refund event | return_refund | The workflow belongs in a return or refund operations lane. | Related resource ID path | Related resource type and text identifier context. |
| External company/B2B event | company_b2b | The workflow belongs in a company or B2B operations lane. | Related resource ID path | Related resource type and text identifier context. |
Mapping fields #
Event mapping tells FlowRelay how to read the sender payload before the Shopify Flow handoff. It does not rewrite the payload, fetch missing data, or transform values.
| Field | Required when | What it controls | Example |
|---|---|---|---|
| Default event type / defaultEventType | Always | Fallback event type when Event type path is blank or not present in the payload. | warehouse.shipment.updated |
| Event type path / eventTypePath | Optional | JSON path where FlowRelay can read the sender's event type from the payload. | event.type |
| External event ID path / externalEventIdPath | Optional, recommended when the sender has stable IDs | JSON path for the sender's stable event ID, used for correlation and duplicate handling. | event.id |
| Occurred-at path / occurredAtPath | Optional | JSON path for the sender's original event timestamp. | event.occurred_at |
| Summary path / summaryPath | Optional | JSON path for a short human-readable summary that helps receipts and operators scan events. | event.summary |
| Resource ID path / resourceIdPath | Order, Customer, or Product variants | JSON path for the Shopify ID or GID of the native order, customer, or product. | order.id |
| Related resource ID path / relatedResourceIdPath | Inventory, Fulfillment, Return/refund, or Company/B2B variants | JSON path for the related resource identifier shown as text context in Flow. | fulfillment.id |
| Required payload paths / requiredPayloadPaths | Optional, up to five paths | Validation gates for fields the sender must always include before FlowRelay hands the event to Shopify Flow. | items[0].sku |
Path syntax #
Use simple dot notation with optional zero-based array indexes. Paths must point to fields that already exist in the incoming JSON payload.
| Supported | Example | Not supported |
|---|---|---|
| Object property | ticket.id | Wildcards, filters, functions, transforms, or templating. |
| Array index | items[0].sku | Negative indexes, array searches, or computed paths. |
| Existing JSON value | order.admin_graphql_api_id | Fetching values from Shopify or another system during mapping. |
Synthetic examples #
Keep examples synthetic and redacted. Do not paste production event bodies, customer data, endpoint secrets, authentication headers, signatures, Shopify tokens, or copied merchant incidents into docs, prompts, tickets, or screenshots.
{
"triggerVariant": "generic",
"defaultEventType": "warehouse.shipment.updated",
"eventTypePath": "event.type",
"externalEventIdPath": "event.id",
"occurredAtPath": "event.occurred_at",
"summaryPath": "event.summary",
"resourceIdPath": null,
"relatedResourceIdPath": null,
"requiredPayloadPaths": ["event.id", "event.type"]
}{
"triggerVariant": "order",
"defaultEventType": "warehouse.order.ready",
"eventTypePath": "event.type",
"externalEventIdPath": "event.id",
"occurredAtPath": "event.occurred_at",
"summaryPath": "event.summary",
"resourceIdPath": "order.id",
"relatedResourceIdPath": null,
"requiredPayloadPaths": ["order.id"]
}{
"triggerVariant": "fulfillment",
"defaultEventType": "carrier.fulfillment.exception",
"eventTypePath": "event.type",
"externalEventIdPath": "event.id",
"occurredAtPath": "event.occurred_at",
"summaryPath": "event.summary",
"resourceIdPath": null,
"relatedResourceIdPath": "fulfillment.id",
"requiredPayloadPaths": ["fulfillment.id", "event.type"]
}Agent usage #
Authorized agents should read this page before creating or editing endpoints through API, CLI, or MCP. The OpenAPI schema gives exact request shapes; this page gives the product meaning needed to choose the correct variant and identifier path.
| Surface | What the agent should do |
|---|---|
| Agent Operations API | Use the API value in triggerVariant, send null for inactive resource path fields, and preserve idempotency keys for create or edit work. |
| CLI | Use flowrelay-agent create-endpoint --json endpoint.json after reading this page and the OpenAPI schema. |
| MCP | Use search to inspect OpenAPI, read this page for mapping semantics, then execute only allowed Agent Operations routes inside the grant. |
| Any agent client | If the correct variant is unclear, ask the operator instead of inventing a native or related-resource mapping. |
Receipt check #
After a synthetic test, the receipt should show the selected trigger variant, resolved event type, any required identifier, required-path validation result, and Shopify Flow readiness. Fix mapping before production traffic if the receipt shows a missing path or unexpected identifier.
Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.