# Advanced JSONata mapping

Canonical: https://docs.flowrelay.app/setup/jsonata-mapping/
Markdown: https://docs.flowrelay.app/setup/jsonata-mapping.md

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

## Steps
Complete these in order.
1. 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.
2. 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.
3. 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.
4. 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

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

### JSONata expression

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

### Expected custom data

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

```text
{"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.


## Related
- [Trigger variants and mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping.md)
- [Authenticate requests](https://docs.flowrelay.app/setup/authentication.md)
- [Send your first test event](https://docs.flowrelay.app/getting-started/first-event.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.