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.

## Choose what you need
- [Choose the trigger](#choose-the-trigger): Match the Shopify Flow workflow to the narrowest useful trigger variant.
- [Map the event](#map-the-event): Set the resource path, related-resource path, and payload fields the trigger needs.
- [Check boundaries and proof](#check-boundaries-and-proof): Confirm data-access limits, agent behavior, and the receipt after a test event.

## 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: 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 to inventory operations; 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 to fulfillment operations; 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 to return/refund operations; 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 to company/B2B operations; Identifier field: Related resource ID path; Flow context: 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.

![FlowRelay endpoint form showing event type, external event ID, occurred-at, summary, Shopify resource ID, and required payload path fields.](https://docs.flowrelay.app/assets/docs-trigger-mapping-desktop.png)

The endpoint form keeps the common event paths together and shows the identifier path required by the selected trigger.


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


## 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 access](https://docs.flowrelay.app/setup/permissions-and-data-access/): Scope 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: 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 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.


## 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)
- [Permissions and data access](https://docs.flowrelay.app/setup/permissions-and-data-access.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 share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.