> ## Documentation Index
> Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Order transactions

> Send your store's orders with their products, and refunds, so they count for revenue and feed product picks.

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](https://segmentflow.ai/docs/connect-other-platforms.md).

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.

> [!NOTE]
>
> The endpoints use API Keys with `events:write`. Orders sent as
> `order_transaction` events through [`events.track`](https://segmentflow.ai/docs/events) keep working as
> before: they count for revenue but carry no products.

## Send an order

```ts theme={null}
const response = await fetch(
  "https://api.segmentflow.ai/api/v1/events/order-transactions",
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.SEGMENTFLOW_API_KEY!,
    },
    body: JSON.stringify({
      type: "order",
      source: "my-shop",
      orderId: "1001",
      occurredAt: "2026-11-20T10:00:00.000Z",
      currency: "EUR",
      totals: { total: 59.9, subtotal: 55, shipping: 4.9 },
      customer: {
        email: "alex@example.com",
        externalCustomerId: "cus_123",
        marketingConsent: "subscribed",
      },
      lineItems: [
        {
          productId: "prod_42",
          variantId: "var_42_red",
          sku: "MUG-RED",
          title: "Red mug",
          quantity: 2,
          unitPrice: 27.5,
        },
      ],
    }),
  },
);

const result = await response.json();
// { eventId, profileId, outcome: "created", matchedJourneys, enrolledJourneys, skippedJourneys }
```

`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`:

| `outcome` | Meaning |
| - | - |
| `created` | The first time this order or refund was sent. |
| `updated` | It was stored before and its details changed. |
| `unchanged` | A retry with the same details. Nothing changed. |

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.

```json theme={null}
{
  "type": "refund",
  "source": "my-shop",
  "orderId": "1001",
  "refundId": "re_1",
  "occurredAt": "2026-11-22T09:00:00.000Z",
  "currency": "EUR",
  "lineItems": [
    {
      "productId": "prod_42",
      "title": "Red mug",
      "quantity": 1,
      "unitPrice": 27.5
    }
  ]
}
```

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`:

```json theme={null}
{
  "transactions": [
    {
      "type": "order",
      "source": "my-shop",
      "orderId": "980",
      "historical": true,
      "...": "..."
    },
    {
      "type": "order",
      "source": "my-shop",
      "orderId": "981",
      "historical": true,
      "...": "..."
    }
  ]
}
```

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

| Field | Purpose |
| - | - |
| `type` | `order` for a paid order, `refund` for a refund. |
| `source` | Your store's name. Letters, digits, `.`, `_`, `:` and `-`; case-sensitive. |
| `orderId` | Your order ID. On a refund, the order it refunds. |
| `refundId` | Refunds only. Your refund ID. |
| `occurredAt` | When the order was paid or the refund issued, with a time zone. |
| `currency` | ISO 4217 code, for example `EUR`. Revenue is reported per currency. |
| `totals.total` | Orders only. What the customer paid. `subtotal`, `tax`, `shipping` and `discount` are optional. |
| `amount` | Refunds only. The refunded amount; defaults to the sum of `lineItems`. |
| `customer.email` | Resolves the customer's Profile, or creates one when no Profile matches. |
| `customer.externalCustomerId` | Your customer ID. Resolves an existing Profile; a new Profile needs an email. |
| `customer.marketingConsent` | Optional `subscribed` or `unsubscribed`. |
| `lineItems[]` | Products: `productId`, `variantId`, `sku`, `title`, `quantity` and `unitPrice` (per unit). |
| `historical` | `true` for past orders. They never start a Journey. |

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](https://segmentflow.ai/docs/catalog-products.md#find-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`):

| Reason | Meaning |
| - | - |
| `profile_not_found` | No Profile matches `externalCustomerId`, and there is no email to create one. |
| `profile_erased` | The customer's Profile was erased. |
| `identity_conflict` | The email and customer ID belong to different Profiles, or the order belongs to another Profile. |
| `order_not_found` | A refund without `customer` names an order that isn't stored yet. |

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`](https://segmentflow.ai/docs/events).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.