> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.brevo.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server. # Import your orders ## 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](/reference/activate-the-e-commerce-app). To use these endpoints, your account must have the Brevo eCommerce application enabled. See [Activate the eCommerce App](/reference/activate-the-e-commerce-app). --- ## Managing the status of an order Use `POST https://api.brevo.com/v3/orders/status` to create or update a single order. ```curl 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", "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" }, "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](#products-attribute). | | `storeId` | String | ID of the store where the order was placed. | | `identifiers` | Object | Identifies the contact associated with the order. See [Identifiers](#identifiers-attribute). | | `billing` | Object | Billing and delivery details. See [Billing](#billing-attribute). | | `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. | | `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 | Postcode for delivery and billing. | | `paymentMethod` | String | Payment method used (e.g. `PayPal`, `Check`). | | `region` | String | State or province for delivery and billing. | --- ## 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 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", "quantity": 100, "price": 1 } ], "coupons": ["TEST100"], "billing": { "address": "15 Somewhere Road, Brynmenyn", "city": "Basel", "phone": "01559 032133" } } ], "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](#order-attributes). 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: ```json { "batchId": 1, "count": 2 } ```