# Orders API

> Send your shop’s orders to credit revenue to emails and build purchase profiles.

Base URL: `https://api.emailit.com/v2`. Authenticate with `Authorization: Bearer <API key>`.

## Create or update an order — POST /orders

> Send an order from your shop. Emailit credits new orders to the email the buyer last clicked or opened, updates the buyer's purchase profile and emits order.placed. Alpha: open to the Emailit team only.

# Create or update an order

Send an order from your shop's backend. The order is keyed by its `id` in your shop: send the same `id` again and the stored order is updated instead. Requires an API key with the `full` or `events` scope. With an `events` key, the response holds only `object`, `id` and `external_id`.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

When an order is stored for the first time, Emailit:

- credits it to the campaign or automation email the buyer last clicked within the click window before `placed_at`, or, without a click, last opened within the open window. The windows are in the [commerce settings](/docs/api-reference/commerce/get-settings/). See [How orders are credited to emails](/docs/commerce/#how-orders-are-credited-to-emails).
- links it to the buyer's contact, and creates the contact if needed (see `create_contact`).
- marks the cart named in `cart_id` as converted, and also the buyer's other open carts that were last updated before the order.
- marks matching coupon codes as redeemed.
- updates the contact's purchase metrics.
- emits [`order.placed`](/docs/webhooks/events/order/placed/), which webhooks and automations receive.

Sending an order that's already stored updates it and emits [`order.updated`](/docs/webhooks/events/order/updated/), with `previous_status` when the status changed. The attribution doesn't change. Only the fields you send change: `status`, `placed_at`, `currency`, the amounts, `coupon_codes`, `cart_id` and `items` keep their stored values when you leave them out, `metadata` is merged into the stored object, and `total` isn't required. Sending `items` replaces all items. To change only the status or a refund, you can also use [Update an order](/docs/api-reference/orders/update/).

To import past orders without crediting emails or starting automations, use [Import orders in bulk](/docs/api-reference/orders/batch/).

`POST /orders`

## Request Body

- `id` (string | number, required): The order ID in your shop, up to 255 characters. Numbers are stored as strings. Stored as `external_id`. You can also send it as `external_id` or `order_id`.

- `email` (string): The buyer's email address. Stored in lowercase. Emailit uses it to find the contact and to credit the order to an email sent to that address. `customer.email` is also accepted.

- `contact_id` (string): The buyer's contact (`con_...`). If no contact has this ID, Emailit looks the contact up by `email`.

- `first_name` (string): The buyer's first name, up to 191 characters. Used when Emailit creates the contact. `customer.first_name` is also accepted.

- `last_name` (string): The buyer's last name, up to 191 characters. Used when Emailit creates the contact. `customer.last_name` is also accepted.

- `status` (string): `placed` (default), `paid`, `fulfilled`, `canceled` or `refunded`. The first time an order has `paid`, `fulfilled`, `canceled` or `refunded`, Emailit sets the matching `paid_at`, `fulfilled_at`, `canceled_at` or `refunded_at` to the current time. Canceled orders don't count toward revenue.

- `currency` (string): Three-letter ISO 4217 code. Defaults to the workspace currency in the [commerce settings](/docs/api-reference/commerce/get-settings/). Amounts are never converted: reports group revenue by currency.

- `total` (number | string): Order total. Required for a new order without items. Without it, Emailit computes the sum of the item totals, minus `discount`, plus `shipping` and `tax`, and never below 0. Amounts are numbers or numeric strings, can't be negative, and are stored with up to 4 decimal places.

- `subtotal` (number | string): Amount before discount, shipping and tax. Defaults to the sum of the item totals when the order has items.

- `discount` (number | string): Discount amount, as a positive number.

- `shipping` (number | string): Shipping amount.

- `tax` (number | string): Tax amount.

- `refunded_amount` (number | string): Amount refunded. Defaults to `0`, or to `total` when `status` is `refunded`. Revenue is `total` minus `refunded_amount`.

- `coupon_codes` (string[]): Up to 20 coupon or discount codes used in the order. A code that matches a [coupon code](/docs/api-reference/coupons/list-codes/) in the workspace, ignoring case, is marked redeemed by this order. `coupon_code` and `discount_codes` are also accepted.

- `cart_id` (string): The cart or checkout ID in your shop that the order came from. The [cart](/docs/api-reference/carts/upsert/) with this ID becomes `converted`.

- `placed_at` (string | number): When the order was placed: an ISO 8601 date-time or a Unix timestamp in seconds (milliseconds also work). Defaults to the current time. Can't be more than 24 hours in the future. `created_at` is also accepted.

- `items` (object[]): Up to 250 line items. `line_items` is also accepted. Each item has: - `product_id` (string or number): the product ID in your shop. Items without a `title`, `url`, `image_url` or `categories` take them from the [catalog](/docs/api-reference/products/create/). `id` is also accepted. - `variant_id`, `sku` (string): up to 255 characters. - `title` (string): up to 500 characters. Required when the item has no `product_id` or `sku`. `name` is also accepted. - `quantity` (integer): 1 or more. Defaults to 1. - `price` (number or string): the unit price. Defaults to 0. `unit_price` is also accepted. - `total` (number or string): the line total. Defaults to `price` times `quantity`. - `categories` (string[]): up to 50 category names. - `url`, `image_url` (string): `http` or `https` URLs.

- `metadata` (object): Your own key-value data, up to 16 KB as JSON. On updates, the keys you send are merged into the stored object.

- `create_contact` (boolean): Default `true`: when no contact matches `contact_id` or `email`, Emailit creates one from `email`, `first_name` and `last_name` and emits `contact.created`. The new contact isn't subscribed to any audience, so campaigns don't reach it. Set to `false` to never create a contact: the order is then linked only to a contact that already exists.

- `accepts_marketing` (boolean): Set to `true` together with `audience_id` when the buyer agreed to receive marketing. Emailit then subscribes the contact to that audience, unless the contact is already in it. Default `false`.

- `audience_id` (string): The audience (`aud_...`) to subscribe the buyer to when `accepts_marketing` is `true`. If the audience doesn't exist or your plan's subscriber limit is reached, the order is still stored and the contact isn't subscribed.

- `email_id` (string): The campaign email (`eml_...`) the buyer came from, if your shop tracks it. Only used for new orders, and only IDs that start with `eml_` are read. The order is credited to this email when it's a campaign email of the workspace and either has a click within the click window before the order or was sent within that window. Otherwise Emailit credits the order as usual. `attribution.email_id` is also accepted.

## Returns

`201 Created` with the [order object](/docs/api-reference/orders/get/) when the order is new, or `200 OK` when an existing order was updated. Returns `422` when a field is invalid.
**Request** `POST /orders`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1042",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "status": "paid",
    "currency": "USD",
    "discount": 10.7,
    "shipping": 5,
    "tax": 0,
    "coupon_codes": ["WELCOME-7KQ2M9XA"],
    "cart_id": "c-58f1a2",
    "placed_at": "2026-10-08T14:32:10Z",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "title": "Trail running shoe", "quantity": 1, "price": 89 },
      { "product_id": "8123456790", "title": "Merino running socks", "quantity": 2, "price": 9 }
    ],
    "metadata": { "channel": "web" },
    "accepts_marketing": true,
    "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV"
  }'
```

**201**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**422**

```json
{
  "message": "Validation failed. items.1.quantity: must be a positive integer",
  "errors": {
    "items.1.quantity": [
      "must be a positive integer"
    ]
  }
}
```

---
Source: https://emailit.com/docs/api-reference/orders/create/

## Retrieve an order — GET /orders/{id}

> Retrieve an order with its items and the campaign or automation email it's credited to. Alpha: open to the Emailit team only.

# Retrieve an order

Retrieve an order by its Emailit ID or by the order ID in your shop, with its items and its attribution. Requires an API key with the `full` scope.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

`GET /orders/{id}`

## Path Parameters

- `id` (string, required): The order ID (`ord_...`) or the order ID in your shop (`external_id`). URL-encode shop IDs that contain special characters.

## The order object

- `object` (string): Always `order`.

- `id` (string): Emailit order ID (`ord_...`).

- `external_id` (string): The order ID in your shop: the `id` you sent.

- `contact_id` (string | null): The buyer's contact (`con_...`), or `null` when the order isn't linked to a contact.

- `email` (string | null): The buyer's email address, in lowercase.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` or `refunded`.

- `currency` (string): Three-letter ISO 4217 code of the amounts.

- `subtotal` (number | null): Sum of the items before discount, shipping and tax.

- `discount` (number | null): Discount amount.

- `shipping` (number | null): Shipping amount.

- `tax` (number | null): Tax amount.

- `total` (number): Order total. Revenue in reports is `total` minus `refunded_amount`, and canceled orders don't count.

- `refunded_amount` (number): Amount refunded so far. `0` when nothing was refunded.

- `coupon_codes` (string[]): Coupon or discount codes used in the order.

- `cart_id` (string | null): The cart or checkout ID in your shop that the order came from.

- `source` (string): How the order reached Emailit: `api`, `js` (the tracking script) or `import` ([bulk import](/docs/api-reference/orders/batch/)).

- `placed_at` (string): When the order was placed, in ISO 8601 UTC.

- `paid_at, fulfilled_at, canceled_at, refunded_at` (string | null): When Emailit first stored the order with that status. Set once and not cleared when the status changes again.

- `attribution` (object | null): The email the order is credited to, or `null`. Set once, when the order is first stored. See [How orders are credited to emails](/docs/commerce/#how-orders-are-credited-to-emails). - `email_id` (string): the credited email. - `campaign_id`, `campaign_name` (string or null): its campaign. - `variant_id` (string or null): the A/B test variant (`cvr_...`) the buyer received. - `automation_id`, `automation_name` (string or null): its automation. - `type` (string): `click` or `open`. - `touched_at` (string or null): when the click or open happened.

- `items` (object[]): Line items. Each has `product_id` (the product ID in your shop), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `categories`, `url` and `image_url`.

- `metadata` (object): Your own key-value data.

- `created_at, updated_at` (string): When Emailit stored the order and when it last changed, in ISO 8601 UTC.

**Request** `GET /orders/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/orders/ord_3aMEK4No62Zw8S1fcHNznAnnbfp \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

---
Source: https://emailit.com/docs/api-reference/orders/get/

## Update an order — POST /orders/{id}

> Change an order's status, record a refund, or add metadata, without sending the whole order again. Alpha: open to the Emailit team only.

# Update an order

Change the status of a stored order, record a refund, or add metadata. Everything else stays as it is, including the items and the attribution. The buyer's purchase metrics are recalculated, and Emailit emits [`order.updated`](/docs/webhooks/events/order/updated/), with the order's `previous_status` when the status changed. Requires an API key with the `full` or `events` scope. With an `events` key, the response holds only `object`, `id` and `external_id`.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

`POST /orders/{id}`

## Path Parameters

- `id` (string, required): The order ID (`ord_...`) or the order ID in your shop.

## Request Body

Send at least one of these fields.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` or `refunded`. The first time the order gets `paid`, `fulfilled`, `canceled` or `refunded`, the matching `paid_at`, `fulfilled_at`, `canceled_at` or `refunded_at` is set to the current time. Canceled orders don't count toward revenue.

- `refunded_amount` (number | string): Total amount refunded so far, not the amount of this refund. Can't be negative. Revenue is `total` minus `refunded_amount`. If you set `status` to `refunded` without `refunded_amount` and nothing was refunded before, the whole `total` counts as refunded.

- `metadata` (object): Keys to merge into the order's metadata. Up to 16 KB as JSON.

## Returns

`200 OK` with the updated [order object](/docs/api-reference/orders/get/). Returns `404` if no order matches `id` and `422` when the body is empty or a field is invalid.
**Request** `POST /orders/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/1042 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "refunded_amount": 18 }'
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 18,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-10T08:05:39.871Z"
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

**422**

```json
{
  "message": "Validation failed. status: is required",
  "errors": {
    "status": [
      "is required"
    ]
  }
}
```

---
Source: https://emailit.com/docs/api-reference/orders/update/

## List orders — GET /orders

> List orders, newest first, filtered by buyer, status, date range, or the campaign or automation they're credited to. Alpha: open to the Emailit team only.

# List orders

List orders with their items, the most recently placed first. Requires an API key with the `full` scope.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

`GET /orders`

## Query Parameters

- `page` (integer): Page number for pagination (minimum: 1, default: 1).

- `limit` (integer): Number of orders to return (minimum: 1, maximum: 100, default: 25).

- `search` (string): Case-insensitive match on the order ID in your shop or the buyer's email address.

- `contact_id` (string): Only orders of this contact (`con_...`).

- `email` (string): Only orders with this buyer email address, ignoring case.

- `status` (string): Only orders with this status: `placed`, `paid`, `fulfilled`, `canceled` or `refunded`.

- `campaign_id` (string): Only orders credited to this campaign (`cmp_...`).

- `automation_id` (string): Only orders credited to this automation (`aut_...`).

- `attributed` (boolean): `true` for orders credited to an email, `false` for orders that aren't.

- `from` (string): Only orders placed at or after this time. An ISO 8601 date or date-time; anything else returns `422`.

- `to` (string): Only orders placed at or before this time. An ISO 8601 date or date-time; anything else returns `422`.

- `match` (string): `all` (default) requires every `key.condition` filter to match. `or` matches any of them. See [Filtering](/docs/api-reference/filtering/).

- `sort` (string): Sort key: `placed_at` (default), `total` or `created_at`.

- `order` (string): Sort direction: `asc` or `desc` (default).

## Filters

Filter and sort keys: see [Filtering](https://emailit.com/docs/api-reference/filtering/).

On this endpoint, `order` only accepts `asc` or `desc`. Pass the sort key in `sort`, for example `sort=total&order=desc`.

## Returns

A page of [order objects](/docs/api-reference/orders/get/) in `data`, with `total_records`, `next_page_url` and `previous_page_url`. The page URLs carry only `page` and `limit`, so add your search and filters again when you follow them.
**Request** `GET /orders`

**cURL**

```bash
curl "https://api.emailit.com/v2/orders?campaign_id=cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN&from=2026-10-01&limit=25" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "order",
      "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
      "external_id": "1042",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "status": "paid",
      "currency": "USD",
      "subtotal": 89,
      "discount": null,
      "shipping": 5,
      "tax": 0,
      "total": 94,
      "refunded_amount": 0,
      "coupon_codes": [],
      "cart_id": null,
      "source": "api",
      "placed_at": "2026-10-08T14:32:10.000Z",
      "paid_at": "2026-10-08T14:32:11.204Z",
      "fulfilled_at": null,
      "canceled_at": null,
      "refunded_at": null,
      "attribution": {
        "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
        "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
        "campaign_name": "October newsletter",
        "variant_id": null,
        "automation_id": null,
        "automation_name": null,
        "type": "click",
        "touched_at": "2026-10-08T09:41:52.000Z"
      },
      "items": [
        {
          "product_id": "8123456789",
          "variant_id": null,
          "sku": "TRS-BLU-42",
          "title": "Trail running shoe",
          "quantity": 1,
          "unit_price": 89,
          "total": 89,
          "categories": [
            "Shoes",
            "Running"
          ],
          "url": "https://shop.example.com/products/trail-running-shoe",
          "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
        }
      ],
      "metadata": {},
      "created_at": "2026-10-08T14:32:11.204Z",
      "updated_at": "2026-10-08T14:32:11.204Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

---
Source: https://emailit.com/docs/api-reference/orders/list/

## Import orders in bulk — POST /orders/batch

> Send up to 1,000 orders in one request, for example your order history. Imports don't credit emails or emit order events by default. Alpha: open to the Emailit team only.

# Import orders in bulk

Send up to 1,000 orders in one request. Use it to import your order history, so purchase metrics, segments and product recommendations have data from day one. Each order follows the rules of [Create or update an order](/docs/api-reference/orders/create/): it's created or updated by its `id`, contacts are created unless `create_contact` is `false`, carts are converted, coupon codes are redeemed and purchase metrics are updated. Requires an API key with the `full` or `events` scope. With an `events` key, the response holds only `object`, `id` and `external_id`.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

By default the orders are historical: they aren't credited to any email, and Emailit doesn't emit `order.placed` or `order.updated`, so they don't start automations or reach webhooks. New contacts still emit `contact.created`. Orders sent with this endpoint have `source` set to `import`, with or without `historical`.

Invalid orders are skipped and listed in `rejected`; the others are stored. The request still returns `200`.

`POST /orders/batch`

## Request Body

- `orders` (object[], required): 1 to 1,000 orders, each with the fields of [Create or update an order](/docs/api-reference/orders/create/).

- `historical` (boolean): Default `true`: no attribution and no order events. Set to `false` to treat the orders like orders sent one by one: new orders are credited to emails and emit `order.placed`, updated orders emit `order.updated`.

## Returns

- `created` (integer): Number of new orders.

- `updated` (integer): Number of orders that were already stored and were updated.

- `rejected` (object[]): Orders that weren't stored. Each item has the `index` of the order in your `orders` array and `errors`, keyed by field path such as `orders.4.currency`. An order that passed validation but couldn't be saved has the error `could not be stored` under `orders.<index>`.

Returns `422` if `orders` is empty or has more than 1,000 items.
**Request** `POST /orders/batch`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/batch \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "id": "981",
        "email": "ada@example.com",
        "status": "fulfilled",
        "currency": "USD",
        "placed_at": "2026-03-14T10:12:00Z",
        "items": [{ "product_id": "8123456789", "quantity": 1, "price": 89 }]
      },
      {
        "id": "982",
        "email": "grace@example.com",
        "status": "fulfilled",
        "currency": "usd dollars",
        "total": 18,
        "placed_at": "2026-03-15T16:40:00Z"
      }
    ]
  }'
```

**200**

```json
{
  "created": 1,
  "updated": 0,
  "rejected": [
    {
      "index": 1,
      "errors": {
        "orders.1.currency": [
          "must be a three-letter ISO 4217 code, e.g. USD"
        ]
      }
    }
  ]
}
```

**422**

```json
{
  "message": "Validation failed. orders: Send 1 to 1000 orders.",
  "errors": {
    "orders": [
      "Send 1 to 1000 orders."
    ]
  }
}
```

---
Source: https://emailit.com/docs/api-reference/orders/batch/

## Delete an order — DELETE /orders/{id}

> Delete an order and its items, and recalculate the buyer's purchase metrics. Alpha: open to the Emailit team only.

# Delete an order

Delete an order and its items. The buyer's purchase metrics are recalculated without it, and its revenue no longer counts in reports. Coupon codes it redeemed stay redeemed and converted carts stay converted. No event is emitted. To keep the order but stop counting its revenue, set its status to `canceled` with [Update an order](/docs/api-reference/orders/update/) instead. Requires an API key with the `full` scope.

> **Commerce is in alpha:** Commerce is open only to the Emailit team while we test it. Other requests return `403` with `error: "commerce_alpha"`. API keys work only in workspaces owned by the Emailit team. See [Who can use Commerce](/docs/commerce/#who-can-use-commerce).

`DELETE /orders/{id}`

## Path Parameters

- `id` (string, required): The order ID (`ord_...`) or the order ID in your shop.

**Request** `DELETE /orders/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/orders/ord_3aMEK4No62Zw8S1fcHNznAnnbfp \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "deleted": true
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

---
Source: https://emailit.com/docs/api-reference/orders/delete/