Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Ecommerce API
version: 1.0.0
servers:
- url: https://api.brevo.com/v3
description: https://api.brevo.com/v3
tags:
- name: ecommerce
paths:
/orders/status:
post:
operationId: createOrder
summary: Managing the status of the order
description: Manages the transactional status of the order
tags:
- ecommerce
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'204':
description: Order Event posted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequestBadRequestError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/order'
/orders/status/batch:
post:
operationId: createBatchOrder
summary: Create orders in batch
description: Create multiple orders at one time instead of one order at a time
tags:
- ecommerce
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'202':
description: batch id created
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_createBatchOrder_Response_202'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBatchOrderRequestBadRequestError'
requestBody:
content:
application/json:
schema:
type: object
properties:
historical:
type: boolean
default: true
description: 'Defines whether you want your orders to be considered as live data or as historical data (import of past data, synchronising data). True: orders will not trigger any automation workflows. False: orders will trigger workflows as usual.'
notifyUrl:
type: string
description: Webhook URL to receive the status of the batch request
orders:
type: array
items:
$ref: '#/components/schemas/order'
description: array of order objects
required:
- orders
/orders:
get:
operationId: getOrders
summary: Get order details
description: Get all the orders
tags:
- ecommerce
parameters:
- name: limit
in: query
description: Number of documents per page
required: false
schema:
type: integer
format: int64
default: 50
- name: offset
in: query
description: Index of the first document in the page
required: false
schema:
type: integer
format: int64
default: 0
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/OrdersGetParametersSort'
default: desc
- name: modifiedSince
in: query
description: 'Filter (urlencoded) the orders modified after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.**
'
required: false
schema:
type: string
- name: createdSince
in: query
description: 'Filter (urlencoded) the orders created after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.**
'
required: false
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: orders fetched successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_getOrders_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetOrdersRequestBadRequestError'
/products:
post:
operationId: createUpdateProduct
summary: Create/Update a product
description: 'Create a new ecommerce product or update an existing one, identified by the mandatory `id` field. When `updateEnabled` is `false` (the default), the endpoint inserts a new product and returns `201`; if the product ID already exists, a `400` error is returned. When `updateEnabled` is `true`, the endpoint performs an upsert, returning `201` for a new product or `204` for an update. The `name` field is mandatory for creation but optional for updates. Product images are downloaded, validated (max 5 MB, formats: jpeg, jpg, png, bmp, gif, webp), and re-hosted on S3. The `metaInfo` object supports up to 20 keys with a cumulative size limit of approximately 1000 KB.'
tags:
- ecommerce
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'201':
description: Product created
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_createUpdateProduct_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateProductRequestBadRequestError'
requestBody:
description: Values to create/update a product
content:
application/json:
schema:
type: object
properties:
brand:
type: string
description: Brand of the product
categories:
type: array
items:
type: string
description: Category ID-s of the product
deletedAt:
type: string
description: UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) of the product deleted from the shop's database
description:
type: string
description: Description of the product
id:
type: string
format: string
description: Product ID for which you requested the details
imageUrl:
type: string
format: string
description: Absolute URL to the cover image of the product
isDeleted:
type: boolean
description: product deleted from the shop's database
metaInfo:
type: object
additionalProperties:
$ref: '#/components/schemas/ProductsPostRequestBodyContentApplicationJsonSchemaMetaInfo'
description: Meta data of product such as description, vendor, producer, stock level. The total characters of cumulative metaInfo shall not exceed **20000 characters**.
name:
type: string
description: '**Mandatory in case of creation**. Name of the product, as displayed in the shop'
parentId:
type: string
format: string
description: Parent product id of the product
price:
type: string
title: float
description: Price of the product
alternativePrice:
type: string
title: float
description: Alternative price of the product
sku:
type: string
format: string
description: Product identifier from the shop
stock:
type: number
format: double
description: Current stock value of the product from the shop's database
updateEnabled:
type: boolean
default: false
description: Facilitate to update the existing product in the same request (updateEnabled = true)
url:
type: string
format: string
description: URL to the product
required:
- id
- name
get:
operationId: getProducts
summary: Return all your products
description: Retrieve a paginated list of all ecommerce products stored in your Brevo account. Results are sorted by creation date in descending order by default, and can be filtered by product IDs, name (minimum 3 characters), price range, category IDs, modification date, creation date, or deletion status. Use the `search` parameter to query across SKU, name, and ID simultaneously — results are prioritized as exact SKU match > SKU prefix match > name match > ID match. Pagination defaults to 50 products per page (maximum 1000), and the response includes a `count` field with the total number of matching products.
tags:
- ecommerce
parameters:
- name: limit
in: query
description: Number of documents per page
required: false
schema:
type: integer
format: int64
default: 50
- name: offset
in: query
description: Index of the first document in the page
required: false
schema:
type: integer
format: int64
default: 0
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/ProductsGetParametersSort'
default: desc
- name: ids
in: query
description: Filter by product ids
required: false
schema:
type: array
items:
type: string
- name: search
in: query
description: 'Search products simultaneously across SKU, name, and ID fields. Results are returned in the following priority order: **exact SKU match** > **SKU prefix match** > **name match** > **ID match**. For example, `?search=123` on products with `{sku: "123"}` and `{sku: "123456"}` returns the exact SKU match first.'
required: false
schema:
type: string
- name: name
in: query
description: Filter by product name, minimum 3 characters should be present for search.
required: false
schema:
type: string
- name: price[lte]
in: query
description: Price filter for products less than and equals to particular amount
required: false
schema:
type: number
format: double
- name: price[gte]
in: query
description: Price filter for products greater than and equals to particular amount
required: false
schema:
type: number
format: double
- name: price[lt]
in: query
description: Price filter for products less than particular amount
required: false
schema:
type: number
format: double
- name: price[gt]
in: query
description: Price filter for products greater than particular amount
required: false
schema:
type: number
format: double
- name: price[eq]
in: query
description: Price filter for products equals to particular amount
required: false
schema:
type: number
format: double
- name: price[ne]
in: query
description: Price filter for products not equals to particular amount
required: false
schema:
type: number
format: double
- name: alternativePrice[lte]
in: query
description: Alternative price filter for products less than and equals to particular amount
required: false
schema:
type: number
format: double
- name: alternativePrice[gte]
in: query
description: Alternative price filter for products greater than and equals to particular amount
required: false
schema:
type: number
format: double
- name: alternativePrice[lt]
in: query
description: Alternative price filter for products less than particular amount
required: false
schema:
type: number
format: double
- name: alternativePrice[gt]
in: query
description: Alternative price filter for products greater than particular amount
required: false
schema:
type: number
format: double
- name: alternativePrice[eq]
in: query
description: Alternative price filter for products equals to particular amount
required: false
schema:
type: number
format: double
- name: alternativePrice[ne]
in: query
description: Alternative price filter for products not equals to particular amount
required: false
schema:
type: number
format: double
- name: categories
in: query
description: Filter by categories ids
required: false
schema:
type: array
items:
type: string
- name: modifiedSince
in: query
description: 'Filter (urlencoded) the products modified after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.**
'
required: false
schema:
type: string
- name: createdSince
in: query
description: 'Filter (urlencoded) the products created after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.**
'
required: false
schema:
type: string
- name: sortByField
in: query
description: 'Sort the results by a specific field. Default sort field is `created_at` when not passed.
'
required: false
schema:
$ref: '#/components/schemas/ProductsGetParametersSortByField'
- name: isDeleted
in: query
description: 'Filter products by their deletion status. If `false` is passed, only products that are not deleted will be returned.
'
required: false
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: All products listed
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_getProducts_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetProductsRequestBadRequestError'
/products/{id}:
get:
operationId: getProductInfo
summary: Get a product's details
description: Retrieve the full details of a single ecommerce product by its unique ID. The response includes the product name, price, SKU, URL, image URLs (original and thumbnails), categories, stock level, meta information, creation and modification timestamps, and deletion status. Returns a `404` error if no product matches the provided ID.
tags:
- ecommerce
parameters:
- name: id
in: path
description: Product ID
required: true
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Product details
content:
application/json:
schema:
$ref: '#/components/schemas/getProductDetails'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetProductInfoRequestBadRequestError'
'404':
description: Product's id not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
/products/batch:
post:
operationId: createUpdateBatchProducts
summary: Create products in batch
description: Create or update multiple ecommerce products in a single request. The `products` array accepts up to 100 product objects for creation (or up to 1000 when `updateEnabled` is `true` and the account has an increased limit). Each product requires a unique `id` and `name` (name is mandatory for creation only). When `updateEnabled` is `false`, all products are inserted as new; if any ID already exists, a `400` error is returned. When `updateEnabled` is `true`, existing products are updated and new ones are created via upsert. Duplicate IDs within the same request payload are rejected. The response returns the count of created and updated products.
tags:
- ecommerce
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'201':
description: Products created and updated
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_createUpdateBatchProducts_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateBatchProductsRequestBadRequestError'
requestBody:
description: Values to create a batch of products
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/ProductsBatchPostRequestBodyContentApplicationJsonSchemaProductsItems'
description: array of products objects
updateEnabled:
type: boolean
description: Facilitate to update the existing products in the same request (updateEnabled = true)
required:
- products
/products/{id}/alerts/{type}:
post:
operationId: createProductAlert
summary: Create a product alert for a contact
description: Register a contact to receive an alert for a specific product event, such as `back_in_stock`. At least one contact identifier (`ext_id`, `email`, or `sms`) must be provided; when multiple are given, priority is `ext_id` > `email` > `sms`. Returns a `404` error if the product ID does not exist, and a `403` error if product alerts are not enabled for the account.
tags:
- ecommerce
parameters:
- name: id
in: path
description: Product ID
required: true
schema:
type: string
- name: type
in: path
description: Alert type
required: true
schema:
$ref: '#/components/schemas/ProductsIdAlertsTypePostParametersType'
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'204':
description: Product alert was created
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Product alert could not be created
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
'401':
description: unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
'403':
description: Product alerts is not allowed for this account
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
'404':
description: Product ID not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
requestBody:
description: Contact identifier to associate the alert with (at least one is required). Priority is given to `ext_id` > `email` > `sms`
content:
application/json:
schema:
type: object
properties:
contactIdentifiers:
$ref: '#/components/schemas/ProductsIdAlertsTypePostRequestBodyContentApplicationJsonSchemaContactIdentifiers'
/categories:
get:
operationId: getCategories
summary: Return all your categories
description: Retrieve a paginated list of all ecommerce categories stored in your Brevo account. Results are sorted by creation date in descending order by default, and can be filtered by category IDs, name, modification date, creation date, or deletion status. The response includes a `count` field with the total number of matching categories, and pagination defaults to 50 categories per page (maximum 100).
tags:
- ecommerce
parameters:
- name: limit
in: query
description: Number of documents per page
required: false
schema:
type: integer
format: int64
default: 50
- name: offset
in: query
description: Index of the first document in the page
required: false
schema:
type: integer
format: int64
default: 0
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/CategoriesGetParametersSort'
default: desc
- name: ids
in: query
description: Filter by category ids
required: false
schema:
type: array
items:
type: string
- name: name
in: query
description: Filter by category name
required: false
schema:
type: string
- name: modifiedSince
in: query
description: 'Filter (urlencoded) the categories modified after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.**
'
required: false
schema:
type: string
- name: createdSince
in: query
description: 'Filter (urlencoded) the categories created after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.**
'
required: false
schema:
type: string
- name: isDeleted
in: query
description: 'Filter categories by their deletion status. If `false` is passed, only categories that are not deleted will be returned.
'
required: false
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: All categories listed
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_getCategories_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetCategoriesRequestBadRequestError'
post:
operationId: createUpdateCategory
summary: Create/Update a category
description: Create a new ecommerce category or update an existing one, identified by the mandatory `id` field. When `updateEnabled` is set to `false` (the default), the endpoint performs an insert and returns `201`; if the category ID already exists, a `400` error is returned. When `updateEnabled` is `true`, the endpoint performs an upsert, returning `201` for a new category or `204` when an existing category is updated. The `name` field is mandatory for creation but optional for updates.
tags:
- ecommerce
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'201':
description: Category created
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_createUpdateCategory_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateCategoryRequestBadRequestError'
requestBody:
description: Values to create/update a category
content:
application/json:
schema:
type: object
properties:
deletedAt:
type: string
description: UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) of the category deleted from the shop's database
id:
type: string
description: 'Unique Category ID as saved in the shop
'
isDeleted:
type: boolean
description: category deleted from the shop's database
name:
type: string
description: '**Mandatory in case of creation**. Name of the Category, as displayed in the shop
'
updateEnabled:
type: boolean
default: false
description: Facilitate to update the existing category in the same request (updateEnabled = true)
url:
type: string
description: URL to the category
required:
- id
/categories/{id}:
get:
operationId: getCategoryInfo
summary: Get a category details
description: Retrieve the full details of a single ecommerce category by its unique ID. The response includes the category name, URL, creation and modification timestamps, and deletion status. Returns a `404` error if no category matches the provided ID.
tags:
- ecommerce
parameters:
- name: id
in: path
description: Category ID
required: true
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Category details
content:
application/json:
schema:
$ref: '#/components/schemas/getCategoryDetails'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetCategoryInfoRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetCategoryInfoRequestNotFoundError'
/categories/batch:
post:
operationId: createUpdateBatchCategory
summary: Create categories in batch
description: Create or update multiple ecommerce categories in a single request. The `categories` array accepts up to 100 category objects, each requiring a unique `id`. When `updateEnabled` is `false` (the default), all categories are inserted as new; if any ID already exists, a `400` error is returned. When `updateEnabled` is `true`, existing categories are updated and new ones are created via upsert. Duplicate IDs within the same request payload are rejected. The response returns the count of created and updated categories.
tags:
- ecommerce
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'201':
description: Category created and updated
content:
application/json:
schema:
$ref: '#/components/schemas/Ecommerce_createUpdateBatchCategory_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUpdateBatchCategoryRequestBadRequestError'
requestBody:
description: Values to create a batch of categories
content:
application/json:
schema:
type: object
properties:
categories:
type: array
items:
$ref: '#/components/schemas/CategoriesBatchPostRequestBodyContentApplicationJsonSchemaCategoriesItems'
description: array of categories objects
updateEnabled:
type: boolean
description: Facilitate to update the existing categories in the same request (updateEnabled = true)
required:
- categories
/ecommerce/attribution/metrics/{conversionSource}/{conversionSourceId}:
get:
operationId: getDetailedAttributionMetricsForASingleBrevoCampaignOrWorkflow
summary: Get detailed attribution metrics for a single Brevo campaign or workflow
description: Retrieve detailed attribution metrics for a single Brevo campaign or automation workflow, identified by its conversion source type and ID. The response includes orders count, revenue, average basket value, and the number of new customers attributed to that specific campaign or workflow.
tags:
- ecommerce
parameters:
- name: conversionSource
in: path
description: The Brevo campaign type or workflow type for which data will be retrieved
required: true
schema:
$ref: '#/components/schemas/EcommerceAttributionMetricsConversionSourceConversionSourceIdGetParametersConversionSource'
- name: conversionSourceId
in: path
description: The Brevo campaign or automation workflow id for which data will be retrieved
re
# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brevo/refs/heads/main/openapi/brevo-ecommerce-api-openapi.yml