eCommerce

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.

1curl --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.

AttributeTypeDescription
idStringUnique ID of the order.
createdAtStringUTC date-time when the order was created (YYYY-MM-DDTHH:mm:ssZ). Required.
updatedAtStringUTC date-time when the order status was last changed (YYYY-MM-DDTHH:mm:ssZ). Required.
statusStringState of the order (e.g. completed, cancelled). Required.
amountNumberTotal order amount including shipping and tax. Required.
productsArray of objectsProducts in the order. Required. See Products.
storeIdStringID of the store where the order was placed.
identifiersObjectIdentifies the contact associated with the order. See Identifiers.
billingObjectBilling and delivery details. See Billing.
couponsArray of stringsCoupons applied at checkout. Stored case-insensitively.
metaInfoObjectAdditional 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.

AttributeTypeDescription
email_idStringEmail address of the contact.
phone_idStringPhone number of the contact.
ext_idStringExternal ID associated with the contact.
loyalty_subscription_idStringLoyalty subscription ID of the contact.

Products attribute

AttributeTypeDescription
productIdStringID of the product. Required.
priceNumberUnit price of the product. Required.
quantityIntegerNumber of units (whole numbers only, e.g. 10). Required if quantityFloat is not provided.
quantityFloatNumberNumber of units (supports decimals, e.g. 20.52). Required if quantity is not provided.
variantIdStringID of the product variant.

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

Billing attribute

AttributeTypeDescription
addressStringFull billing address.
cityStringCity of the billing address.
countryStringBilling country name.
countryCodeStringBilling country as a 2-letter ISO code.
phoneStringBilling phone number. Required if no email identifier is provided.
postCodeStringPostcode for delivery and billing.
paymentMethodStringPayment method used (e.g. PayPal, Check).
regionStringState 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.

1curl --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.

AttributeTypeDescription
ordersArray of objectsArray of order objects. Required.
notifyUrlStringWebhook URL called when the batch request completes, with the processing status.
historicalBooleanOptional. 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

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

A successful batch response returns:

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