Trigger variants and event mapping

# Trigger variants and event mapping

Canonical: https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/
Markdown: https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping.md

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.
1. Choose the trigger variant based on what the Shopify Flow workflow needs to receive, not based on the sender system's name.
2. Use Generic when the workflow only needs a custom external event and no Shopify resource reference.
3. Use Order, Customer, or Product when Flow needs a native Shopify resource reference and the sender can provide that object's Shopify ID or GID.
4. Use Inventory, Fulfillment, Return/refund, or Company/B2B when the workflow belongs in that operational lane and needs related-resource text context.
5. Map only existing JSON fields from the sender payload. The current Shopify Flow edition does not transform, template, filter, or compute new values.
6. Send 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: A custom external event starts the workflow.; Choose: External event; Required mapping: No resource identifier path.
- Workflow need: Shopify Flow needs a native order, customer, or product reference.; Choose: External order event, External customer event, or External product event; Required mapping: Resource ID path.
- Workflow need: The event belongs to inventory, fulfillment, return/refund, or company/B2B operations.; Choose: The matching operational trigger variant; Required mapping: 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: External event; API value: generic; Use when: The workflow only needs a custom external event.; Identifier field: None; Flow context: No Shopify resource identifier is shown.
- Operator label: External order event; API value: order; Use when: The sender event is about a specific Shopify order.; Identifier field: Resource ID path; Flow context: Native order reference.
- Operator label: External customer event; API value: customer; Use when: The sender event is about a specific Shopify customer.; Identifier field: Resource ID path; Flow context: Native customer reference.
- Operator label: External product event; API value: product; Use when: The sender event is about a specific Shopify product.; Identifier field: Resource ID path; Flow context: Native product reference.
- Operator label: External inventory event; API value: inventory; Use when: The workflow belongs in an inventory operations lane.; Identifier field: Related resource ID path; Flow context: Related resource type and text identifier context.
- Operator label: External fulfillment event; API value: fulfillment; Use when: The workflow belongs in a fulfillment operations lane.; Identifier field: Related resource ID path; Flow context: Related resource type and text identifier context.
- Operator label: External return/refund event; API value: return_refund; Use when: The workflow belongs in a return or refund operations lane.; Identifier field: Related resource ID path; Flow context: Related resource type and text identifier context.
- Operator label: External company/B2B event; API value: company_b2b; Use when: The workflow belongs in a company or B2B operations lane.; Identifier field: Related resource ID path; Flow context: 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: Default event type / defaultEventType; Required when: Always; What it controls: Fallback event type when Event type path is blank or not present in the payload.; Example: warehouse.shipment.updated
- Field: Event type path / eventTypePath; Required when: Optional; What it controls: JSON path where FlowRelay can read the sender's event type from the payload.; Example: event.type
- Field: External event ID path / externalEventIdPath; Required when: Optional, recommended when the sender has stable IDs; What it controls: JSON path for the sender's stable event ID, used for correlation and duplicate handling.; Example: event.id
- Field: Occurred-at path / occurredAtPath; Required when: Optional; What it controls: JSON path for the sender's original event timestamp.; Example: event.occurred_at
- Field: Summary path / summaryPath; Required when: Optional; What it controls: JSON path for a short human-readable summary that helps receipts and operators scan events.; Example: event.summary
- Field: Resource ID path / resourceIdPath; Required when: Order, Customer, or Product variants; What it controls: JSON path for the Shopify ID or GID of the native order, customer, or product.; Example: order.id
- Field: Related resource ID path / relatedResourceIdPath; Required when: Inventory, Fulfillment, Return/refund, or Company/B2B variants; What it controls: JSON path for the related resource identifier shown as text context in Flow.; Example: fulfillment.id
- Field: Required payload paths / requiredPayloadPaths; Required when: Optional, up to five paths; What it controls: Validation gates for fields the sender must always include before FlowRelay hands the event to Shopify Flow.; Example: 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: Object property; Example: ticket.id; Not supported: Wildcards, filters, functions, transforms, or templating.
- Supported: Array index; Example: items[0].sku; Not supported: Negative indexes, array searches, or computed paths.
- Supported: Existing JSON value; Example: order.admin_graphql_api_id; Not supported: 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.

### Generic endpoint mapping
Use when Shopify Flow only needs a custom external event.

```json
{
  "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"]
}
```

### Order endpoint mapping
Use when Shopify Flow needs a native order reference.

```json
{
  "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"]
}
```

### Fulfillment endpoint mapping
Use when Shopify Flow needs a fulfillment operations lane with related-resource context.

```json
{
  "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: Agent Operations API; What the agent should do: Use the API value in triggerVariant, send null for inactive resource path fields, and preserve idempotency keys for create or edit work.
- Surface: CLI; What the agent should do: Use flowrelay-agent create-endpoint --json endpoint.json after reading this page and the OpenAPI schema.
- Surface: MCP; What the agent should do: Use search to inspect OpenAPI, read this page for mapping semantics, then execute only allowed Agent Operations routes inside the grant.
- Surface: Any agent client; What the agent should do: 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.


## Handoff Boundary
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.

## Related
- [Event types and payloads](https://docs.flowrelay.app/setup/event-types-and-payloads.md)
- [Add the Shopify Flow trigger](https://docs.flowrelay.app/setup/shopify-flow-trigger.md)
- [API Reference](https://docs.flowrelay.app/reference/api.md)
- [CLI Reference](https://docs.flowrelay.app/reference/cli.md)
- [MCP Reference](https://docs.flowrelay.app/reference/mcp.md)

## Safety Boundary
Do not include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.