Import your orders | Brevo API Documentation

Overview

You can manage your eCommerce orders through two endpoints:

Single order — POST /orders/status — create or update one order at a time.
Batch orders — POST /orders/status/batch — create up to 1,000 orders in a single request.

Both endpoints are listed in the API reference.

To use these endpoints, your account must have the Brevo eCommerce application enabled. See Activate the eCommerce App.

Managing the status of an order

Use POST https://api.brevo.com/v3/orders/status to create or update a single order.

curl --request POST \
     --url https://api.brevo.com/v3/orders/status \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "id": "14",
  "createdAt": "2021-07-29T20:59:23.383Z",
  "updatedAt": "2021-07-30T10:59:23.383Z",
  "status": "completed",
  "amount": 308.42,
  "storeId": "ST-21",
  "identifiers": {
    "email_id": "example@brevo.com",
    "ext_id": "ext_id_1",
    "loyalty_subscription_id": "loyalty_id_1",
    "phone_id": "01559 032133"
  },
  "products": [
    {
      "productId": "P1",
      "sku": "SKU-001",
      "quantity": 10,
      "variantId": "P100",
      "price": 99.99
    }
  ],
  "billing": {
    "address": "15 Somewhere Road, Brynmenyn",
    "city": "Basel",
    "country": "Canada",
    "countryCode": "CA",
    "phone": "01559 032133",
    "postCode": "4052",
    "paymentMethod": "PayPal",
    "region": "Northwestern Switzerland"
  },
  "shipping": {
    "name": "Jane Doe",
    "address": "8 Market Street",
    "city": "Zurich",
    "country": "Switzerland",
    "countryCode": "CH",
    "phone": "01559 032134",
    "postCode": "8001",
    "region": "Zurich"
  },
  "coupons": ["EASTER15OFF"],
  "metaInfo": {
    "order_source": "Website",
    "gift_message": "Happy Birthday!",
    "customer_loyalty_tier": "Gold"
  }
}'

Order attributes

The following fields are required: id, createdAt, updatedAt, status, amount, products.

Attribute	Type	Description
`id`	String	Unique ID of the order.
`createdAt`	String	UTC date-time when the order was created (`YYYY-MM-DDTHH:mm:ssZ`). Required.
`updatedAt`	String	UTC date-time when the order status was last changed (`YYYY-MM-DDTHH:mm:ssZ`). Required.
`status`	String	State of the order (e.g. `completed`, `cancelled`). Required.
`amount`	Number	Total order amount including shipping and tax. Required.
`products`	Array of objects	Products in the order. Required. See Products.
`storeId`	String	ID of the store where the order was placed.
`identifiers`	Object	Identifies the contact associated with the order. See Identifiers.
`billing`	Object	Billing details. See Billing.
`shipping`	Object	Shipping recipient and address. See Shipping.
`coupons`	Array of strings	Coupons applied at checkout. Stored case-insensitively.
`metaInfo`	Object	Additional order metadata (string, integer, or boolean values).

Identifiers attribute

Use identifiers to link the order to a Brevo contact. At least one identifier is required.

Attribute	Type	Description
`email_id`	String	Email address of the contact.
`phone_id`	String	Phone number of the contact.
`ext_id`	String	External ID associated with the contact.
`loyalty_subscription_id`	String	Loyalty subscription ID of the contact.

Products attribute

Attribute	Type	Description
`productId`	String	ID of the product. Required.
`sku`	String	Stock Keeping Unit identifier of the line item. Stored as sent: it is not matched against the product catalog.
`price`	Number	Unit price of the product. Required.
`quantity`	Integer	Number of units (whole numbers only, e.g. `10`). Required if `quantityFloat` is not provided.
`quantityFloat`	Number	Number of units (supports decimals, e.g. `20.52`). Required if `quantity` is not provided.
`variantId`	String	ID of the product variant.

Provide either quantity or quantityFloat for each product, not both.

Billing attribute

Attribute	Type	Description
`address`	String	Full billing address.
`city`	String	City of the billing address.
`country`	String	Billing country name.
`countryCode`	String	Billing country as a 2-letter ISO code.
`phone`	String	Billing phone number. Required if no email identifier is provided.
`postCode`	String	Billing postcode.
`paymentMethod`	String	Payment method used (e.g. `PayPal`, `Check`).
`region`	String	State or province for billing.

Shipping attribute

Use shipping when the ship-to address differs from the billing address, or when your platform sends both. All fields are optional.

Attribute	Type	Description
`name`	String	Name of the shipping recipient.
`address`	String	Full shipping address.
`city`	String	City of the shipping address.
`region`	String	State or province for shipping.
`postCode`	String	Shipping postcode.
`country`	String	Shipping country name.
`countryCode`	String	Shipping country as a 2-letter ISO code.
`phone`	String	Phone number to contact for shipping questions. If invalid, it is dropped and the order is still accepted. Unlike `billing.phone`, it is never used to identify the contact.

Creating orders in batch

Use POST https://api.brevo.com/v3/orders/status/batch to create multiple orders in a single request.

You can include up to 1,000 orders per request, or a maximum payload size of 5 MB.

curl --request POST \
     --url https://api.brevo.com/v3/orders/status/batch \
     --header 'api-key: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "orders": [
    {
      "id": "order30",
      "createdAt": "2021-07-27T08:52:14.111Z",
      "updatedAt": "2021-07-27T08:52:14.948Z",
      "status": "completed",
      "amount": 1000,
      "identifiers": {
        "email_id": "test@example.com"
      },
      "products": [
        { "productId": "600", "quantity": 899, "price": 1 },
        { "productId": "100", "quantity": 500, "price": 1 },
        { "productId": "100", "variantId": "12", "sku": "SKU-100-12", "quantity": 100, "price": 1 }
      ],
      "coupons": ["TEST100"],
      "billing": {
        "address": "15 Somewhere Road, Brynmenyn",
        "city": "Basel",
        "phone": "01559 032133"
      },
      "shipping": {
        "name": "Jane Doe",
        "address": "8 Market Street",
        "city": "Zurich",
        "countryCode": "CH"
      }
    }
  ],
  "notifyUrl": "https://en.wikipedia.org/wiki/Webhook",
  "historical": true
}'

Batch-specific attributes

Each order in the orders array follows the same schema as a single order, so each order can include or omit shipping on its own. The following additional fields apply to the batch request itself.

Attribute	Type	Description
`orders`	Array of objects	Array of order objects. Required.
`notifyUrl`	String	Webhook URL called when the batch request completes, with the processing status.
`historical`	Boolean	Optional. Defaults to `true`. When set to `true`, imports past orders without triggering automation workflows. When set to `false`, processes orders as live data and may trigger workflows.

Responses

Response	Description
`204`	Single order event created successfully.
`202`	Batch request accepted. Returns `batchId` and `count`.
`400`	Bad request. Check the request body for errors.

A successful batch response returns:

{
  "batchId": 1,
  "count": 2
}