Skip to main content
Send each paid order and each refund from your store’s backend with POST /api/v1/events/order-transactions. This is the order-transaction.v2 contract on the Unified Event Track. Use it when your store isn’t on Shopify or WooCommerce, or when your own backend owns orders. To connect a Shopware, Salla or other platform’s order webhooks, directly or through n8n or Make, see Connect another store platform. An accepted order is stored as an Order Transaction, the same order record Shopify and WooCommerce orders become. It counts for revenue attribution, and its products feed bestsellers and product picks once they match your catalog.
The endpoints use API Keys with events:write. Orders sent as order_transaction events through events.track keep working as before: they count for revenue but carry no products.

Send an order

source names your store, for example my-shop or salla:4821. Use the same name every time: it identifies the store for product picks, and source with orderId identifies the order.

Send it again to update it

Sending the same source and orderId again updates the stored order instead of adding a second one, so retries are safe and you can resend an order whose items or totals changed. There is no Idempotency-Key header on these endpoints. The response says what happened in outcome: An update never starts a Journey again. If the customer of an update resolves to a different Profile than the stored order, the request fails with identity_conflict and nothing changes.

Send a refund

A refund is its own transaction that names its order and the items or amount refunded. Each refund needs its own refundId; send a partial refund for every part.
Refunded items stop counting as purchased, and the refunded amount is subtracted from the order’s attributed revenue. amount defaults to the sum of the refunded items; send amount without lineItems for a refund of an amount only, such as shipping. customer is optional on a refund: without it, the refund belongs to the customer of its order, which must already be stored.

Import past orders

Set historical: true on orders and refunds from before you connected. They count for revenue, bestsellers and product picks like any other, but they never start a Journey, also not by moving a customer into a Segment that starts one. Send up to 100 at a time with POST /api/v1/events/order-transactions/batch:
Transactions are accepted one by one, in order, and the response has one result for each, with its index. A rejected transaction doesn’t stop the others. If the request fails part way, send the whole batch again: transactions already stored come back as unchanged.

Request fields

Orders need customer.email or customer.externalCustomerId. A line item matches a catalog product you sent through the API with the same product ID, or the same SKU when the product ID is missing. Items that match nothing still count in the order’s total. To find them, see order items that match no product. marketingConsent: "subscribed" subscribes the customer to marketing email unless they unsubscribed before. unsubscribed stops marketing email, unless the customer subscribed again after the order.

Errors

Validation errors return 400 VALIDATION_ERROR with the invalid field in details.issues[].path. A transaction that can’t be stored returns 400 with details.reason (in a batch, the result’s code): Matching Journeys start as for any event: an active Journey whose entry event is order_transaction can enroll the customer of a new, non-historical order. The Journey counts in the response work as in events.track.