Trigger variants and event mapping

Pass custom business data to Flow #

Open Endpoint setup, enable custom business data, and select incoming fields. Give each output a name and a declared type. For example, map customer.email to buyerEmail (Text) and order.total to orderTotal (Number). Dotted paths and numeric array indexes are supported. Types are explicit: a string containing digits becomes a number only when you enable scalar conversion.

Missing output values fail unless you provide a default. A default applies to a missing value, not to an explicit null; accepting null requires a nullable declaration. Lists and nested objects use a declared JSON type; undeclared output keys are rejected. Keep at most 20 top-level outputs and three nested type levels. Integers must fit a signed 32-bit value for Shopify's output schema.

Paste a synthetic JSON sample and choose Preview output. This shows validation, mapped output, and the final serialized Flow payload size without saving the sample, creating an event, or running a workflow. Choose Review settings change, inspect the exact change, then confirm to save.

Expand Build the Shopify Flow workflow. Select the matching trigger and filter FlowRelay endpoint ID to this endpoint's ID. Add Run code, use Shopify's variable picker to select Custom data JSON (customDataJson) without a query alias, and copy the generated JavaScript and output schema. Use its typed outputs in conditions and actions. The endpoint ID stays stable when the display name changes. Manual instructions are complete; the optional Sidekick prompt is a convenience, not proof that a workflow was created.

After saving and configuring Flow, use Send test event on the endpoint. Paste the same synthetic JSON into its optional sample field. This creates a real event and can execute your enabled workflow; unlike preview, normal live-test accounting and retention apply. For native-reference triggers, supply a real development-store resource ID. FlowRelay replaces event identity, time, and the native test ID so repeated test clicks remain distinct.

Custom data is a JSON string in the trigger, not dynamically registered Shopify trigger fields. Native order/customer/product references continue to use their existing mapping and optional permissions. The original trigger fields remain available.

{"event":{"id":"sample-001","type":"order.review"},"customer":{"email":"buyer@example.com"},"order":{"total":42.5}}

{"type":"array","items":{"type":"string"}}

{"type":"object","properties":[{"name":"email","schema":{"type":"string"}},{"name":"total","schema":{"type":"number"}}]}

• Advanced JSONata mapping
• Validation and limits

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.

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.

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.

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.

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"]
}

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.

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.