Setup

Advanced JSONata mapping

Use an expression when selecting fields is not enough: rename values, calculate totals, and reshape nested JSON before Shopify Flow receives it.

Next step Read Send your first test event.

Steps

Complete these in order.

Start with the output

Open Endpoint setup and enable custom business data. Declare the output names and types your Flow needs. Use Select incoming fields for direct copies; choose Advanced: JSONata expression for calculations or restructuring.
Write one object expression

Return an object whose keys match the declared fields. Use JSONata for defaults and conversion in advanced mode; the simple-mode controls do not apply to the expression.
Preview difficult cases

Test a synthetic normal message, an empty list, a one-item list, a missing field, and explicit null. Correct the expression or declaration until output is valid. Preview does not execute your workflow.
Save and connect Flow

Review and confirm the configuration change. Copy the generated Run code recipe into the matching Shopify workflow and send a real authenticated synthetic event to prove the complete path.

Calculate and rename #

For the example below, declare buyerEmail as Text, total as Number, and status as Text. Arithmetic uses the supplied input; FlowRelay does not fetch other customer or order data.

Synthetic input

{"customer":{"email":"buyer@example.com"},"paid":true,"items":[{"price":12.5,"quantity":2},{"price":4,"quantity":1}]}

JSONata expression

{"buyerEmail": customer.email, "total": $sum(items.(price * quantity)), "status": paid ? "paid" : "pending"}

Expected custom data

{"buyerEmail":"buyer@example.com","total":29,"status":"paid"}

Keep a one-item list a list #

JSONata can reduce a one-item sequence to one value. Wrap a projection in brackets when the declared output must always be an array.

Always return an array of item objects

{"items": [items.{"sku": sku, "quantity": quantity}]}

Bounded execution #

The pinned evaluator is JSONata 2.2.2 with FlowRelay's flr-1 restrictions. Expressions are limited to 4,000 characters. No network, files, secrets, imported functions, dynamic evaluation, regular expressions, time, or random functions are available. The evaluator also limits expression depth, execution steps, intermediate sequence growth, and output size.

Unsupported or expensive expressions fail with a support code. Simplify the expression or prepare the data in your sender. A timeout does not make a preview a successful delivery. See Validation and limits for the exact input/output budgets.

Editing and retry behavior #

Saving creates a new configuration version. Automatic retries retain the settings accepted with the event. Manual replay uses a preview of the current settings and requires fresh confirmation if those settings change. Keep the generated Shopify parser in sync with the declared outputs.

START

USE CASES

SET UP

OPERATE

RECOVER

AGENT ACCESS

REFERENCE