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.
On this page
Choose the trigger #
Match the Shopify Flow workflow to the narrowest useful trigger variant.
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 related-resource operations, 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 to inventory operations. | Related resource ID path | Related resource type and text identifier context. |
| External fulfillment event | fulfillment | The workflow belongs to fulfillment operations. | Related resource ID path | Related resource type and text identifier context. |
| External return/refund event | return_refund | The workflow belongs to return/refund operations. | Related resource ID path | Related resource type and text identifier context. |
| External company/B2B event | company_b2b | The workflow belongs to company/B2B operations. | Related resource ID path | Related resource type and text identifier context. |
Map the event #
Set the resource path, related-resource path, and payload fields the trigger needs.
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"]
}Check boundaries and proof #
Confirm data-access limits, agent behavior, and the receipt after a test event.
Data access note #
Order, Customer, and Product variants pass sender-supplied Shopify resource IDs into Shopify Flow as native references. FlowRelay does not fetch missing Order, Customer, or Product data during mapping. Use the permissions page when a buyer, reviewer, operator, or agent asks when the app requests optional Shopify read scopes.
- Permissions and data accessScope explanation and Shopify resource data boundary.
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 test event with synthetic data, 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.