The Brevo eCommerce API allows developers to sync product catalogs, categories, and order data with the Brevo platform. It provides endpoints for importing and managing products, organizing them into categories, and tracking customer purchase history. This data integration enables merchants to attribute revenue to marketing campaigns, trigger automated workflows based on purchase behavior, and build product recommendation segments for targeted messaging.
openapi: 3.1.0
info:
title: Brevo eCommerce API
description: >-
The Brevo eCommerce API allows developers to sync product catalogs,
categories, and order data with the Brevo platform. It provides endpoints
for importing and managing products, organizing them into categories, and
tracking customer purchase history. This data integration enables
merchants to attribute revenue to marketing campaigns, trigger automated
workflows based on purchase behavior, and build product recommendation
segments for targeted messaging.
version: '3.0'
contact:
name: Brevo Support
url: https://help.brevo.com
termsOfService: https://www.brevo.com/legal/termsofuse/
externalDocs:
description: Brevo eCommerce Documentation
url: https://developers.brevo.com/docs/import-your-products
servers:
- url: https://api.brevo.com/v3
description: Brevo Production API Server
tags:
- name: Categories
description: >-
Manage product categories for organizing the catalog.
- name: Orders
description: >-
Create and manage eCommerce order data for revenue attribution
and purchase tracking.
- name: Products
description: >-
Import, manage, and retrieve eCommerce product data.
security:
- apiKeyAuth: []
paths:
/products:
get:
operationId: listProducts
summary: Return all products
description: >-
Retrieves a paginated list of all products synced to the Brevo
platform. Returns product details including name, price, URL,
and category assignments.
tags:
- Products
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: ids
in: query
description: >-
Comma-separated list of product IDs to filter by.
schema:
type: string
responses:
'200':
description: Products retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createUpdateProduct
summary: Create or update a product
description: >-
Creates a new product or updates an existing product in the Brevo
eCommerce catalog. If a product with the same ID already exists,
it will be updated with the provided data.
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateProduct'
responses:
'201':
description: Product created or updated successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/products/batch:
post:
operationId: batchCreateUpdateProducts
summary: Create or update products in batch
description: >-
Creates or updates up to 100 products in a single API call.
Products with existing IDs will be updated, and new products
will be created.
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- products
properties:
products:
type: array
description: >-
List of products to create or update.
items:
$ref: '#/components/schemas/CreateUpdateProduct'
maxItems: 100
responses:
'201':
description: Products batch processed successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/products/{productId}:
get:
operationId: getProduct
summary: Get a product
description: >-
Retrieves the details of a specific product by its unique
identifier.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productIdParam'
responses:
'200':
description: Product retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Product not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/categories:
get:
operationId: listCategories
summary: Return all categories
description: >-
Retrieves all product categories in the eCommerce catalog.
tags:
- Categories
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: ids
in: query
description: >-
Comma-separated list of category IDs to filter by.
schema:
type: string
responses:
'200':
description: Categories retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryList'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createUpdateCategory
summary: Create or update a category
description: >-
Creates a new product category or updates an existing one. If a
category with the same ID exists, it will be updated.
tags:
- Categories
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateCategory'
responses:
'201':
description: Category created or updated successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/categories/batch:
post:
operationId: batchCreateUpdateCategories
summary: Create or update categories in batch
description: >-
Creates or updates multiple product categories in a single API
call.
tags:
- Categories
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- categories
properties:
categories:
type: array
description: >-
List of categories to create or update.
items:
$ref: '#/components/schemas/CreateUpdateCategory'
maxItems: 100
responses:
'201':
description: Categories batch processed successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/orders/status:
post:
operationId: createUpdateOrder
summary: Create or update an order
description: >-
Creates a new order or updates the status of an existing order
in the Brevo eCommerce system. Orders are used for revenue
attribution and purchase behavior tracking.
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateOrder'
responses:
'201':
description: Order created or updated successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/orders/status/batch:
post:
operationId: batchCreateUpdateOrders
summary: Create or update orders in batch
description: >-
Creates or updates multiple orders in a single API call for
efficient bulk processing of order data.
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- orders
properties:
orders:
type: array
description: >-
List of orders to create or update.
items:
$ref: '#/components/schemas/CreateUpdateOrder'
responses:
'201':
description: Orders batch processed successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/orders:
get:
operationId: listOrders
summary: Get order details
description: >-
Retrieves order details from the Brevo eCommerce system. Supports
filtering by date range and pagination.
tags:
- Orders
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: startDate
in: query
description: >-
Start date for filtering orders in YYYY-MM-DD format.
schema:
type: string
format: date
- name: endDate
in: query
description: >-
End date for filtering orders in YYYY-MM-DD format.
schema:
type: string
format: date
responses:
'200':
description: Orders retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderList'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: api-key
description: >-
Brevo API key passed in the api-key request header for
authentication.
parameters:
limitParam:
name: limit
in: query
description: >-
Maximum number of results to return per request.
schema:
type: integer
format: int64
default: 50
offsetParam:
name: offset
in: query
description: >-
Number of results to skip for pagination.
schema:
type: integer
format: int64
default: 0
productIdParam:
name: productId
in: path
required: true
description: >-
Unique identifier of the product.
schema:
type: string
schemas:
ProductList:
type: object
properties:
count:
type: integer
format: int64
description: >-
Total number of products.
products:
type: array
description: >-
List of product records.
items:
$ref: '#/components/schemas/Product'
Product:
type: object
properties:
id:
type: string
description: >-
Unique identifier of the product.
name:
type: string
description: >-
Name of the product.
url:
type: string
format: uri
description: >-
URL of the product page.
imageUrl:
type: string
format: uri
description: >-
URL of the product image.
sku:
type: string
description: >-
Stock keeping unit identifier.
price:
type: number
format: float
description: >-
Price of the product.
categories:
type: array
description: >-
IDs of categories the product belongs to.
items:
type: string
metaInfo:
type: object
description: >-
Additional metadata for the product as key-value pairs.
additionalProperties: true
createdAt:
type: string
format: date-time
description: >-
UTC date-time when the product was created.
modifiedAt:
type: string
format: date-time
description: >-
UTC date-time when the product was last modified.
CreateUpdateProduct:
type: object
required:
- id
- name
- url
properties:
id:
type: string
description: >-
Unique identifier for the product.
name:
type: string
description: >-
Name of the product.
url:
type: string
format: uri
description: >-
URL of the product page.
imageUrl:
type: string
format: uri
description: >-
URL of the product image.
sku:
type: string
description: >-
Stock keeping unit identifier.
price:
type: number
format: float
description: >-
Price of the product.
categories:
type: array
description: >-
IDs of categories to assign the product to.
items:
type: string
metaInfo:
type: object
description: >-
Additional metadata as key-value pairs.
additionalProperties: true
CategoryList:
type: object
properties:
count:
type: integer
format: int64
description: >-
Total number of categories.
categories:
type: array
description: >-
List of category records.
items:
$ref: '#/components/schemas/Category'
Category:
type: object
properties:
id:
type: string
description: >-
Unique identifier of the category.
name:
type: string
description: >-
Name of the category.
url:
type: string
format: uri
description: >-
URL of the category page.
createdAt:
type: string
format: date-time
description: >-
UTC date-time when the category was created.
modifiedAt:
type: string
format: date-time
description: >-
UTC date-time when the category was last modified.
CreateUpdateCategory:
type: object
required:
- id
- name
properties:
id:
type: string
description: >-
Unique identifier for the category.
name:
type: string
description: >-
Name of the category.
url:
type: string
format: uri
description: >-
URL of the category page.
OrderList:
type: object
properties:
orders:
type: array
description: >-
List of order records.
items:
$ref: '#/components/schemas/Order'
Order:
type: object
properties:
id:
type: string
description: >-
Unique identifier of the order.
email:
type: string
format: email
description: >-
Email address of the customer.
amount:
type: number
format: float
description: >-
Total order amount.
status:
type: string
description: >-
Current status of the order.
products:
type: array
description: >-
Products included in the order.
items:
$ref: '#/components/schemas/OrderProduct'
createdAt:
type: string
format: date-time
description: >-
UTC date-time when the order was created.
CreateUpdateOrder:
type: object
required:
- id
- email
- status
- amount
- products
- createdAt
properties:
id:
type: string
description: >-
Unique identifier for the order.
email:
type: string
format: email
description: >-
Email address of the customer who placed the order.
status:
type: string
description: >-
Status of the order such as completed, pending, or cancelled.
amount:
type: number
format: float
description: >-
Total order amount including shipping, tax, and item prices.
products:
type: array
description: >-
Products included in the order.
items:
$ref: '#/components/schemas/OrderProduct'
createdAt:
type: string
format: date-time
description: >-
UTC date-time when the order was created.
updatedAt:
type: string
format: date-time
description: >-
UTC date-time when the order was last updated.
coupons:
type: array
description: >-
Coupon codes applied to the order.
items:
type: string
OrderProduct:
type: object
required:
- productId
- quantity
- price
properties:
productId:
type: string
description: >-
Unique identifier of the product.
quantity:
type: integer
description: >-
Quantity of the product ordered.
minimum: 1
price:
type: number
format: float
description: >-
Price of the product at the time of order.
variantId:
type: string
description: >-
Variant identifier if the product has variants.
ErrorResponse:
type: object
properties:
code:
type: string
description: >-
Error code identifying the type of error.
message:
type: string
description: >-
Human-readable description of the error.