Import your orders

Learn how to create and manage eCommerce orders via the Brevo API.

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.

1 curl --request POST \
2      --url https://api.brevo.com/v3/orders/status \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --data '{
6   "id": "14",
7   "createdAt": "2021-07-29T20:59:23.383Z",
8   "updatedAt": "2021-07-30T10:59:23.383Z",
9   "status": "completed",
10   "amount": 308.42,
11   "storeId": "ST-21",
12   "identifiers": {
13     "email_id": "example@brevo.com",
14     "ext_id": "ext_id_1",
15     "loyalty_subscription_id": "loyalty_id_1",
16     "phone_id": "01559 032133"
17   },
18   "products": [
19     {
20       "productId": "P1",
21       "quantity": 10,
22       "variantId": "P100",
23       "price": 99.99
24     }
25   ],
26   "billing": {
27     "address": "15 Somewhere Road, Brynmenyn",
28     "city": "Basel",
29     "country": "Canada",
30     "countryCode": "CA",
31     "phone": "01559 032133",
32     "postCode": "4052",
33     "paymentMethod": "PayPal",
34     "region": "Northwestern Switzerland"
35   },
36   "coupons": ["EASTER15OFF"],
37   "metaInfo": {
38     "order_source": "Website",
39     "gift_message": "Happy Birthday!",
40     "customer_loyalty_tier": "Gold"
41   }
42 }'

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 and delivery details. See Billing.
`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.

1 curl --request POST \
2      --url https://api.brevo.com/v3/orders/status/batch \
3      --header 'api-key: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'content-type: application/json' \
6      --data '{
7   "orders": [
8     {
9       "id": "order30",
10       "createdAt": "2021-07-27T08:52:14.111Z",
11       "updatedAt": "2021-07-27T08:52:14.948Z",
12       "status": "completed",
13       "amount": 1000,
14       "identifiers": {
15         "email_id": "test@example.com"
16       },
17       "products": [
18         { "productId": "600", "quantity": 899, "price": 1 },
19         { "productId": "100", "quantity": 500, "price": 1 },
20         { "productId": "100", "variantId": "12", "quantity": 100, "price": 1 }
21       ],
22       "coupons": ["TEST100"],
23       "billing": {
24         "address": "15 Somewhere Road, Brynmenyn",
25         "city": "Basel",
26         "phone": "01559 032133"
27       }
28     }
29   ],
30   "notifyUrl": "https://en.wikipedia.org/wiki/Webhook",
31   "historical": true
32 }'

Batch-specific attributes

Each order in the orders array follows the same schema as a single order. 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:

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

1	curl --request POST \
2	--url https://api.brevo.com/v3/orders/status \
3	--header 'accept: application/json' \
4	--header 'content-type: application/json' \
5	--data '{
6	"id": "14",
7	"createdAt": "2021-07-29T20:59:23.383Z",
8	"updatedAt": "2021-07-30T10:59:23.383Z",
9	"status": "completed",
10	"amount": 308.42,
11	"storeId": "ST-21",
12	"identifiers": {
13	"email_id": "example@brevo.com",
14	"ext_id": "ext_id_1",
15	"loyalty_subscription_id": "loyalty_id_1",
16	"phone_id": "01559 032133"
17	},
18	"products": [
19	{
20	"productId": "P1",
21	"quantity": 10,
22	"variantId": "P100",
23	"price": 99.99
24	}
25	],
26	"billing": {
27	"address": "15 Somewhere Road, Brynmenyn",
28	"city": "Basel",
29	"country": "Canada",
30	"countryCode": "CA",
31	"phone": "01559 032133",
32	"postCode": "4052",
33	"paymentMethod": "PayPal",
34	"region": "Northwestern Switzerland"
35	},
36	"coupons": ["EASTER15OFF"],
37	"metaInfo": {
38	"order_source": "Website",
39	"gift_message": "Happy Birthday!",
40	"customer_loyalty_tier": "Gold"
41	}
42	}'

1	curl --request POST \
2	--url https://api.brevo.com/v3/orders/status/batch \
3	--header 'api-key: YOUR_API_KEY' \
4	--header 'accept: application/json' \
5	--header 'content-type: application/json' \
6	--data '{
7	"orders": [
8	{
9	"id": "order30",
10	"createdAt": "2021-07-27T08:52:14.111Z",
11	"updatedAt": "2021-07-27T08:52:14.948Z",
12	"status": "completed",
13	"amount": 1000,
14	"identifiers": {
15	"email_id": "test@example.com"
16	},
17	"products": [
18	{ "productId": "600", "quantity": 899, "price": 1 },
19	{ "productId": "100", "quantity": 500, "price": 1 },
20	{ "productId": "100", "variantId": "12", "quantity": 100, "price": 1 }
21	],
22	"coupons": ["TEST100"],
23	"billing": {
24	"address": "15 Somewhere Road, Brynmenyn",
25	"city": "Basel",
26	"phone": "01559 032133"
27	}
28	}
29	],
30	"notifyUrl": "https://en.wikipedia.org/wiki/Webhook",
31	"historical": true
32	}'