openapi: 3.2.0
info:
  title: Ecommerce Coupons API
  version: 1.0.0
servers:
- url: https://api.brevo.com/v3
  description: https://api.brevo.com/v3
tags:
- name: coupons
paths:
  /couponCollections:
    get:
      operationId: getCouponCollections
      summary: Get all your coupon collections
      description: Retrieve a paginated list of all coupon collections in your Brevo account. Results can be sorted by creation date, remaining coupons count, or expiration date, in ascending or descending order. Pagination defaults to 50 collections per page (maximum 100).
      tags:
      - coupons
      parameters:
      - name: limit
        in: query
        description: Number of documents returned per page
        required: false
        schema:
          type: integer
          format: int64
          default: 50
      - name: offset
        in: query
        description: Index of the first document on the page
        required: false
        schema:
          type: integer
          format: int64
          default: 0
      - name: sort
        in: query
        description: Sort the results by creation time in ascending/descending order
        required: false
        schema:
          $ref: '#/components/schemas/CouponCollectionsGetParametersSort'
          default: desc
      - name: sortBy
        in: query
        description: The field used to sort coupon collections
        required: false
        schema:
          $ref: '#/components/schemas/CouponCollectionsGetParametersSortBy'
          default: createdAt
      - 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: Coupon collections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getCouponCollection'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCouponCollectionsRequestBadRequestError'
        '401':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCouponCollectionsRequestUnauthorizedError'
    post:
      operationId: createCouponCollection
      summary: Create а coupon collection
      description: Create a new coupon collection with a name and a default coupon value. You can optionally set an expiration date in RFC3339 format and configure alert thresholds to receive email notifications when remaining coupons or remaining days before expiration fall below a specified number. The collection ID is auto-generated as a UUID and returned in the response.
      tags:
      - coupons
      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: Coupon collection created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupons_createCouponCollection_Response_201'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCouponCollectionRequestBadRequestError'
        '401':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCouponCollectionRequestUnauthorizedError'
      requestBody:
        description: Values to create a coupon collection
        content:
          application/json:
            schema:
              type: object
              properties:
                defaultCoupon:
                  type: string
                  description: Default coupons collection name
                expirationDate:
                  type: string
                  format: date-time
                  description: Specify an expiration date for the coupon collection in RFC3339 format. Use null to remove the expiration date.
                name:
                  type: string
                  description: Name of the coupons collection
                remainingCouponsAlert:
                  type: integer
                  description: Send a notification alert (email) when the remaining coupons count is equal or fall bellow this number. Use null to disable alerts.
                remainingDaysAlert:
                  type: integer
                  description: Send a notification alert (email) when the remaining days until the expiration date are equal or fall bellow this number. Use null to disable alerts.
              required:
              - defaultCoupon
              - name
  /couponCollections/{id}:
    get:
      operationId: getCouponCollection
      summary: Get a coupon collection by id
      description: Retrieve the details of a single coupon collection by its UUID. The response includes the collection name, default coupon value, total and remaining coupon counts, and creation timestamp. Returns a `404` error if no collection matches the provided ID.
      tags:
      - coupons
      parameters:
      - name: id
        in: path
        description: Id of the collection to return
        required: true
        schema:
          type: string
          format: uuidv4
      - 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: Coupon collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getCouponCollection'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCouponCollectionRequestBadRequestError'
        '401':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCouponCollectionRequestUnauthorizedError'
        '404':
          description: Coupon collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
    patch:
      operationId: updateCouponCollection
      summary: Update a coupon collection by id
      description: Update an existing coupon collection by its UUID. You can modify the default coupon value, set or remove the expiration date (pass `null` to remove), and configure or disable alert thresholds for remaining coupons or remaining days. Only the fields included in the request body are updated; omitted fields remain unchanged.
      tags:
      - coupons
      parameters:
      - name: id
        in: path
        description: Id of the collection to update
        required: true
        schema:
          type: string
          format: uuidv4
      - 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: Coupon collection updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupons_updateCouponCollection_Response_200'
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCouponCollectionRequestBadRequestError'
        '401':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCouponCollectionRequestUnauthorizedError'
      requestBody:
        description: Values to update the coupon collection
        content:
          application/json:
            schema:
              type: object
              properties:
                defaultCoupon:
                  type: string
                  description: A default coupon to be used in case there are no coupons left
                expirationDate:
                  type: string
                  format: date-time
                  description: Specify an expiration date for the coupon collection in RFC3339 format. Use null to remove the expiration date.
                remainingCouponsAlert:
                  type: integer
                  description: Send a notification alert (email) when the remaining coupons count is equal or fall bellow this number. Use null to disable alerts.
                remainingDaysAlert:
                  type: integer
                  description: Send a notification alert (email) when the remaining days until the expiration date are equal or fall bellow this number. Use null to disable alerts.
  /coupons:
    post:
      operationId: createCoupons
      summary: Create coupons for a coupon collection
      description: Add coupons to an existing coupon collection. The `coupons` array must contain between 1 and 10,000 unique coupon code strings, all associated with the specified `collectionId`. Coupon creation is processed asynchronously and a `204` status is returned immediately upon acceptance. Returns a `404` error if the specified coupon collection does not exist.
      tags:
      - coupons
      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: Coupons creation in progress
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCouponsRequestBadRequestError'
        '401':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCouponsRequestUnauthorizedError'
        '404':
          description: Coupon collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorModel'
      requestBody:
        description: Values to create coupons
        content:
          application/json:
            schema:
              type: object
              properties:
                collectionId:
                  type: string
                  format: uuidv4
                  description: The id of the coupon collection for which the coupons will be created
                coupons:
                  type: array
                  items:
                    type: string
              required:
              - collectionId
              - coupons
components:
  schemas:
    CreateCouponsRequestUnauthorizedError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponsPostResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: CreateCouponsRequestUnauthorizedError
    CouponCollectionsGetParametersSort:
      type: string
      enum:
      - asc
      - desc
      default: desc
      title: CouponCollectionsGetParametersSort
    UpdateCouponCollectionRequestUnauthorizedError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsIdPatchResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: UpdateCouponCollectionRequestUnauthorizedError
    GetCouponCollectionsRequestBadRequestError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsGetResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: GetCouponCollectionsRequestBadRequestError
    Coupons_updateCouponCollection_Response_200:
      type: object
      properties:
        defaultCoupon:
          type: string
          description: The default coupon of the collection
        id:
          type: string
          format: uuidv4
          description: The id of the collection
        name:
          type: string
          description: The name of the collection
      required:
      - defaultCoupon
      - id
      - name
      title: Coupons_updateCouponCollection_Response_200
    CouponsPostResponsesContentApplicationJsonSchemaCode:
      type: string
      enum:
      - invalid_parameter
      - missing_parameter
      - out_of_range
      - campaign_processing
      - campaign_sent
      - document_not_found
      - not_enough_credits
      - permission_denied
      - duplicate_parameter
      - duplicate_request
      - method_not_allowed
      - unauthorized
      - account_under_validation
      - not_acceptable
      - bad_request
      - unprocessable_entity
      - Domain does not exist
      - Contact email not found
      - Attribute not found
      - Category id not found
      - Invalid parameters passed
      - Record(s) for identifier not found
      - Returned when query params are invalid
      - Returned when invalid data posted
      - Feed not found
      - Campaign ID not found
      - api-key not found
      - DMARC policy requires domain authentication
      - DNS records not properly configured
      - Invalid OTP code provided
      - OTP code has expired
      - Domain already exists in your account
      - The sum of all IP weights must equal 100
      - Authentication failed
      - Insufficient credits
      - Request already processed
      description: Error code displayed in case of a failure
      title: CouponsPostResponsesContentApplicationJsonSchemaCode
    UpdateCouponCollectionRequestBadRequestError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsIdPatchResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: UpdateCouponCollectionRequestBadRequestError
    CreateCouponCollectionRequestUnauthorizedError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsPostResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: CreateCouponCollectionRequestUnauthorizedError
    CouponCollectionsIdGetResponsesContentApplicationJsonSchemaCode:
      type: string
      enum:
      - invalid_parameter
      - missing_parameter
      - out_of_range
      - campaign_processing
      - campaign_sent
      - document_not_found
      - not_enough_credits
      - permission_denied
      - duplicate_parameter
      - duplicate_request
      - method_not_allowed
      - unauthorized
      - account_under_validation
      - not_acceptable
      - bad_request
      - unprocessable_entity
      - Domain does not exist
      - Contact email not found
      - Attribute not found
      - Category id not found
      - Invalid parameters passed
      - Record(s) for identifier not found
      - Returned when query params are invalid
      - Returned when invalid data posted
      - Feed not found
      - Campaign ID not found
      - api-key not found
      - DMARC policy requires domain authentication
      - DNS records not properly configured
      - Invalid OTP code provided
      - OTP code has expired
      - Domain already exists in your account
      - The sum of all IP weights must equal 100
      - Authentication failed
      - Insufficient credits
      - Request already processed
      description: Error code displayed in case of a failure
      title: CouponCollectionsIdGetResponsesContentApplicationJsonSchemaCode
    CreateCouponsRequestBadRequestError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponsPostResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: CreateCouponsRequestBadRequestError
    CouponCollectionsGetResponsesContentApplicationJsonSchemaCode:
      type: string
      enum:
      - invalid_parameter
      - missing_parameter
      - out_of_range
      - campaign_processing
      - campaign_sent
      - document_not_found
      - not_enough_credits
      - permission_denied
      - duplicate_parameter
      - duplicate_request
      - method_not_allowed
      - unauthorized
      - account_under_validation
      - not_acceptable
      - bad_request
      - unprocessable_entity
      - Domain does not exist
      - Contact email not found
      - Attribute not found
      - Category id not found
      - Invalid parameters passed
      - Record(s) for identifier not found
      - Returned when query params are invalid
      - Returned when invalid data posted
      - Feed not found
      - Campaign ID not found
      - api-key not found
      - DMARC policy requires domain authentication
      - DNS records not properly configured
      - Invalid OTP code provided
      - OTP code has expired
      - Domain already exists in your account
      - The sum of all IP weights must equal 100
      - Authentication failed
      - Insufficient credits
      - Request already processed
      description: Error code displayed in case of a failure
      title: CouponCollectionsGetResponsesContentApplicationJsonSchemaCode
    errorModel:
      type: object
      properties:
        code:
          type: string
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - message
      title: errorModel
    CouponCollectionsIdPatchResponsesContentApplicationJsonSchemaCode:
      type: string
      enum:
      - invalid_parameter
      - missing_parameter
      - out_of_range
      - campaign_processing
      - campaign_sent
      - document_not_found
      - not_enough_credits
      - permission_denied
      - duplicate_parameter
      - duplicate_request
      - method_not_allowed
      - unauthorized
      - account_under_validation
      - not_acceptable
      - bad_request
      - unprocessable_entity
      - Domain does not exist
      - Contact email not found
      - Attribute not found
      - Category id not found
      - Invalid parameters passed
      - Record(s) for identifier not found
      - Returned when query params are invalid
      - Returned when invalid data posted
      - Feed not found
      - Campaign ID not found
      - api-key not found
      - DMARC policy requires domain authentication
      - DNS records not properly configured
      - Invalid OTP code provided
      - OTP code has expired
      - Domain already exists in your account
      - The sum of all IP weights must equal 100
      - Authentication failed
      - Insufficient credits
      - Request already processed
      description: Error code displayed in case of a failure
      title: CouponCollectionsIdPatchResponsesContentApplicationJsonSchemaCode
    GetCouponCollectionRequestBadRequestError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsIdGetResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: GetCouponCollectionRequestBadRequestError
    CreateCouponCollectionRequestBadRequestError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsPostResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: CreateCouponCollectionRequestBadRequestError
    CouponCollectionsGetParametersSortBy:
      type: string
      enum:
      - createdAt
      - remainingCoupons
      - expirationDate
      default: createdAt
      title: CouponCollectionsGetParametersSortBy
    GetCouponCollectionsRequestUnauthorizedError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsGetResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: GetCouponCollectionsRequestUnauthorizedError
    GetCouponCollectionRequestUnauthorizedError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/CouponCollectionsIdGetResponsesContentApplicationJsonSchemaCode'
          description: Error code displayed in case of a failure
        message:
          type: string
          description: Readable message associated to the failure
      required:
      - code
      - message
      title: GetCouponCollectionRequestUnauthorizedError
    getCouponCollection:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: Datetime on which the collection was created.
        defaultCoupon:
          type: string
          description: The default coupon of the collection.
        expirationDate:
          type: string
          format: date-time
          description: Expiration date for the coupon collection in RFC3339 format.
        id:
          type: string
          format: uuidv4
          description: The id of the collection.
        name:
          type: string
          description: The name of the collection.
        remainingCoupons:
          type: integer
          format: int64
          description: Number of coupons that have not been sent yet.
        remainingCouponsAlert:
          type: integer
          description: If present, an email notification is going to be sent when the total number of available coupons falls below the defined threshold.
        remainingDaysAlert:
          type: integer
          description: If present, an email notification is going to be sent the defined amount of days before to the expiration date.
        totalCoupons:
          type: integer
          format: int64
          description: Total number of coupons in the collection.
      required:
      - createdAt
      - defaultCoupon
      - id
      - name
      - remainingCoupons
      - totalCoupons
      title: getCouponCollection
    CouponCollectionsPostResponsesContentApplicationJsonSchemaCode:
      type: string
      enum:
      - invalid_parameter
      - missing_parameter
      - out_of_range
      - campaign_processing
      - campaign_sent
      - document_not_found
      - not_enough_credits
      - permission_denied
      - duplicate_parameter
      - duplicate_request
      - method_not_allowed
      - unauthorized
      - account_under_validation
      - not_acceptable
      - bad_request
      - unprocessable_entity
      - Domain does not exist
      - Contact email not found
      - Attribute not found
      - Category id not found
      - Invalid parameters passed
      - Record(s) for identifier not found
      - Returned when query params are invalid
      - Returned when invalid data posted
      - Feed not found
      - Campaign ID not found
      - api-key not found
      - DMARC policy requires domain authentication
      - DNS records not properly configured
      - Invalid OTP code provided
      - OTP code has expired
      - Domain already exists in your account
      - The sum of all IP weights must equal 100
      - Authentication failed
      - Insufficient credits
      - Request already processed
      description: Error code displayed in case of a failure
      title: CouponCollectionsPostResponsesContentApplicationJsonSchemaCode
    Coupons_createCouponCollection_Response_201:
      type: object
      properties:
        id:
          type: string
          format: uuidv4
          description: The id of the created collection
      required:
      - id
      title: Coupons_createCouponCollection_Response_201
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key
      description: The API key should be passed in the request headers as `api-key` for authentication.