Manage orders | Brevo API Documentation

You can manage your orders seamlessly through the eCommerce platform. You can see all the endpoints for eCommerce order management in the API reference here.

Requirements

To create and manage your eCommerce store orders you need to have access to the Brevo eCommerce application. If you are not already integrated with the eCommerce feature you can go to eCommerce > Activate the eCommerce App.

Managing the status of the order

To manage the transactional status of the order, you have to use the endpoint https://api.brevo.com/v3/orders/status with the method POST. The cURL request to create orders is as follows:

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 {
7   "id": "14",
8   "createdAt": "2021-07-29T20:59:23.383Z",
9   "updatedAt": "2021-07-30T10:59:23.383Z",
10   "status": "completed",
11   "amount": 308.42,
12   "storeId": "ST-21",
13   "identifiers": {
14     "ext_id": "ext_id_1",
15     "loyalty_subscription_id": "loyalty_id_1",
16     "phone_id": "01559 032133",
17     "email_id": "example@brevo.com"
18   },
19   "products": [
20     {
21       "productId": "P1",
22       "quantity": 10,
23       "variantId": "P100",
24       "price": 99.99
25     }
26   ],
27   "billing": {
28     "address": "15 Somewhere Road, Brynmenyn",
29     "city": "Basel",
30     "countryCode": "CA",
31     "country": "Canada",
32     "phone": "01559 032133",
33     "postCode": "4052",
34     "paymentMethod": "PayPal",
35     "region": "Northwestern Switzerland"
36   },
37   "coupons": [
38     "EASTER15OFF"
39   ],
40   "metaInfo": {
41     "order_source": "Website",
42     "gift_message": "Happy Birthday!",
43     "customer_loyalty_tier": "Gold"
44   }
45 }

Attribute	Datatype	Value	Description
`id`	String	Order1	Unique identifier for the order.
`createdAt`	String	2021-07-29T20:59:23.383Z	UTC date-time when order was created.
`updatedAt`	String	2021-07-30T10:59:23.383Z	UTC date-time when order is changed/updated.
`status`	String	Completed	Transactional status of the order.
`amount`	Number	308	Total cost of the order including shipping and taxes etc.
`products`	Array of objects	Id of the product, quantity, price etc.	The assorted products in the order.
`email`	String	abc@example.com	Email address of the customer.
`billing`	Object	Address, city, phone, postcode etc.	Billing details of the order.
`coupons`	Array of strings	Test100	Coupons applied to order at checkout.
`metainfo`	Object	”order_source”: “Website”	Meta data of order to store additional detail such as custom message, customer type, source.

Products and billings

💡Note products and billing are different objects. Their parameters are explained below.

Products attribute
Products attribute is a sub-attribute for orders. It is an array of objects that represents all the products in an order. Its attributes are mentioned in the table below.

Attribute	Datatype	Value	Description
`productId`	String	P1	ID of the product.
`quantity`	Number	3	How many products the visitor has added to the cart.
`variantId`	String	P12	Product ID of the red colour shirts.
`price`	Number	20	The price of a unit of a product.

Billing attribute
💡Billing attribute is also a sub-attribute for orders. It is an object that includes the details of the order delivery and its region. Its attributes are mentioned below in the table.

Attribute	Datatype	Value	Description
`address`	String	15 Somewhere Road, Brynmenyn	Full billing address.
`city`	String	Basel	Exact city of the address.
`countryCode`	String	CA	Billing country 2-letter ISO code.
`phone`	String	01559 032133	Phone number to contact for further details about the order, Mandatory if “email” field is not passed.
`postCode`	String	40523	Postcode for delivery and billing.
`paymentMethod`	String	Paypal	How the visitor will pay for the item(s), e.g. Paypal, Check, etc.
`region`	String	Northwestern Switzerland	Exact region (state/province) for delivery and billing.

Managing the batch of orders

You have to use the endpoint https://api.brevo.com/v3/orders/status/batchwith the POST for calling this API. This endpoint is used to create multiple orders at one time instead of one order at a time. You can check it out at eCommerce > Maintains a batch of orders.

The cURL request is as following:

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

Limits

You can create up to ** 1000 orders in a batch or 5MB ** of orders in size.

1 {
2   "orders": [
3     {
4       "id": "order30",
5       "status": "completed",
6       "amount": 1000,
7       "email": "test@test13a.com",
8       "createdAt": "2021-07-27T08:52:14.111Z",
9       "updatedAt": "2021-07-27T08:52:14.948Z",
10       "Products": [
11         {
12           "productId": "600",
13           "quantity": 899,
14           "price": 1
15         },
16         {
17           "productId": "100",
18           "quantity": 500,
19           "price": 1
20         },
21         {
22           "productId": "100",
23           "variantId": "12",
24           "quantity": 100,
25           "price": 1
26         }
27       ],
28       "coupons": [
29         "TEST100"
30       ],
31       "billing": {
32         "address": "newAddress",
33         "city": "Noida",
34         "phone": "919860038202"
35       }
36     },
37     {
38       "Id": "order31",
39       "status": "completed",
40       "amount": 1000,
41       "email": "test@test13a.com",
42       "createdAt": "2021-07-27T08:52:14.111Z",
43       "updatedAt": "2021-07-27T08:52:14.948Z",
44       "Products": [
45         {
46           "productId": "900",
47           "quantity": 999,
48           "price": 1
49         },
50         {
51           "productId": "500",
52           "quantity": 800,
53           "price": 1
54         },
55         {
56           "productId": "800",
57           "variantId": "12",
58           "quantity": 800,
59           "price": 1
60         }
61       ],
62       "coupons": [
63         "TESTy00"
64       ],
65       "billing": {
66         "address": "newAddress",
67         "city": "Noida",
68         "phone": "919860038202"
69       }
70     }
71   ],
72   "notifyUrl": "www.testnotify.com"
73 }

The attributes and parameters of batch orders and creating orders are equal except batch orders contains multiple orders so the attributes of orders are created in batches. The only attribute that is different in batch orders is notifyUrl.

Attribute	Datatype	Value	Description
`orders`	Array of objects	Value of batch of orders	Array of order objects
`id`	String	Order1	Unique id of the order
`createdAt`	String	2021-07-29T20:59:23.383Z	Event occurrence UTC date-time, when order is actually created.
`updatedAt`	String	2021-07-30T10:59:23.383Z	Event updated UTC date-time, when the status of the order is actually changed/updated.
`status`	String	Completed	Status of the order
`amount`	Number	308.42	Total amount of the order, including all shipping expenses, tax and the price of items.
`products`	Array of objects	Id of the product, quantity and price.	Assorted products in the order.
`email`	String	example@brevo.com	Email of the contact, Mandatory if “phone” field is not passed in “billing” parameter.
`billing`	Object	Billing details like address, city, post code etc.	Billing details of an order
`coupons`	Array of strings	TEST100	Coupons applied to the order.
`notifyUrl`	String	https://en.wikipedia.org/wiki/Webhook	Notify Url provided by client to get the status of batch request

💡Products and billing are objects so their parameters will be mentioned below in another table.

Products attribute
Products attribute is a sub-attribute for orders. It is an array of objects that represents all the products in an order. Its attributes are mentioned in the table below.

Attribute	Datatype	Value	Description
`productId`	String	P1	ID of the product.
`quantity`	Number	3	How many products the visitor has added to the cart.
`variantId`	String	P12	Product ID of the red colour shirts.
`price`	Number	20	The price of a unit of a product.

Attribute	Datatype	Value	Description
`address`	String	15 Somewhere Road, Brynmenyn	Full billing address.
`city`	String	Basel	Exact city of the address.
`country code`	String	CA	Billing country 2-letter ISO code.
`phone`	String	01559 032133	Phone number to contact for further details about the order, Mandatory if “email” field is not passed.
`postCode`	String	40523	Postcode for delivery and billing.
`paymentMethod`	String	Paypal	How the visitor will pay for the item(s), e.g. Paypal, Check, etc.
`region`	String	Northwestern Switzerland	Exact region (state/province) for delivery and billing.

Responses you should expect

Response code	Message	Description
`204`	Order event posted	Order event has been created.
`202`	Batch id created	Batch id has been created and request successfully completed
`400`	Bad request	Bad request

1 {
2   "batch_id": xxxxxx
3 }