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

# Push Order

> Push a normalized order from any e-commerce platform

Push an order from any e-commerce platform. This is the core of the [Commerce API](/concepts/custom-commerce): one call gives you the same behavior as a native Shopify/WooCommerce order webhook.

When an order is pushed, Sequenzy:

1. **Upserts the customer** as a subscriber (with names and custom attributes)
2. **Triggers the matching event** (`ecommerce.order_placed`, `ecommerce.order_cancelled`, `ecommerce.order_fulfilled`, or `ecommerce.order_refunded`) for automations and segments
3. **Updates revenue attributes** on the subscriber: `ltv`, `totalSpent`, `ordersCount`, `aov` (placed orders only)
4. **Cancels superseded automations** (e.g. a replenishment or back-in-stock sequence for a product the customer just bought)
5. **Schedules replenishment reminders** for products with replenishment enabled

Processing is asynchronous - the endpoint returns `202 Accepted` immediately.

## Idempotency

Pushing the same `orderId` twice never double counts revenue. Retries are safe.

## Request Body

<ParamField body="orderId" type="string" required>
  Unique order identifier in your platform. Used for idempotency.
</ParamField>

<ParamField body="orderNumber" type="string">
  Human-facing order number, if different from `orderId`.
</ParamField>

<ParamField body="status" type="string" default="placed">
  Lifecycle status of this order event: `placed`, `cancelled`, `fulfilled`, or
  `refunded`.
</ParamField>

<ParamField body="totalCents" type="integer" required>
  Order total in cents.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code (e.g. `USD`).
</ParamField>

<ParamField body="orderedAt" type="string">
  ISO 8601 timestamp of when the order happened. Defaults to now.
</ParamField>

<ParamField body="customer" type="object" required>
  The customer who placed the order. Requires `email`; also accepts
  `externalId`, `firstName`, `lastName`, and `attributes` (custom subscriber
  attributes, synced for segment filtering).
</ParamField>

<ParamField body="items" type="array">
  Order line items. Each item has `productId` (required), `title` (required),
  `quantity` (required), `variantId`, `sku`, `variantTitle`, and `priceCents`.
  Use the same `productId` values as your [product catalog](/api-reference/products/upsert)
  so replenishment and product matching work.
</ParamField>

<ParamField body="refundAmountCents" type="integer">
  For `refunded` orders: refunded amount in cents.
</ParamField>

<ParamField body="customerTotals" type="object">
  Authoritative customer aggregates from your platform: `ordersCount` and
  `totalSpentCents`. When provided, these override Sequenzy's additive revenue
  bookkeeping (recommended if your platform tracks lifetime totals).
</ParamField>

<ParamField body="properties" type="object">
  Extra event properties to attach to the triggered `ecommerce.*` event.
  Available in sequence emails as `{{event.*}}` merge tags. Reserved
  normalized keys (`provider`, `orderId`, `lineItems`, `orderedAt`, etc.)
  cannot be overridden.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-1001",
    "totalCents": 8850,
    "currency": "USD",
    "orderedAt": "2026-06-01T12:00:00.000Z",
    "customer": {
      "email": "buyer@example.com",
      "firstName": "Jane",
      "attributes": { "acquisitionChannel": "tiktok" }
    },
    "items": [
      {
        "productId": "SKU-PROTEIN-1KG",
        "variantId": "SKU-PROTEIN-1KG-VANILLA",
        "title": "Protein Powder",
        "variantTitle": "Vanilla",
        "quantity": 2,
        "priceCents": 4425
      }
    ]
  }'
```

### Refund example

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-1001",
    "status": "refunded",
    "totalCents": 8850,
    "refundAmountCents": 8850,
    "currency": "USD",
    "customer": { "email": "buyer@example.com" }
  }'
```

## Responses

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "queued": true,
    "jobId": "commerce-order-1a2b3c",
    "orderId": "order-1001",
    "status": "placed"
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "orderedAt must be a valid ISO 8601 timestamp"
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```

  ```json 422 theme={null}
  {
    "success": false,
    "error": "Validation error: customer.email is required"
  }
  ```

  ```json 503 theme={null}
  {
    "success": false,
    "error": "Failed to queue order"
  }
  ```
</ResponseExample>