brevo-ecommerce-openapi.yml

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.