openapi: 3.0.0
info:
  contact: {}
  title: Antavo Bulk Operations API
  version: 1.0.0
servers:
- url: https://api.staging.antavo.com
  description: The Antavo staging environment
paths:
  /v1/bulk-operation/coupons/{batch_id}/status/error:
    get:
      tags:
      - Coupons
      summary: Query the list of errors related to a coupon import
      description: This endpoint allows you to query information about any errors or issues encountered
        during a coupon import. It provides details about failures that may have occurred during the process.
      parameters:
      - in: path
        name: batch_id
        required: true
        example: batch001
        description: The batch ID associated with the coupon import operation.
        schema:
          type: string
      responses:
        '200':
          description: Returned after the coupon import operation has been processed. Provides information
            about errors, if any, that occurred during the operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponsStatusResponse'
              examples:
                Errors were found:
                  description: Returned if errors were found during the processing of the batch.
                  value:
                    status: success
                    metadata:
                      pagination:
                        total: 42
                        next: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status/error?offset=40&limit=20
                        previous: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status/error?offset=0&limit=20
                    payload:
                      number_of_errors: 42
                      coupons:
                      - coupon_code: CODE1
                        pool_id: 146cb226c3d47e4d6a28176b
                        error_message: Error message
                        error_code: 123456
                      - coupon_code: CODE2
                        pool_id: 146cb226c3d47e4d6a28176b
                        error_message: Error message
                        error_code: 123456
                      - '...'
                No errors were found:
                  description: Returned if no errors were found during the processing of the batch.
                  value:
                    status: success
                    metadata:
                      pagination:
                        total: 0
                    payload:
                      number_of_errors: 0
                      coupons: {}
        '404':
          description: The batch ID provided as a parameter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
              examples:
                Bulk operation request queue is not found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 320504
                      message: Bulk operation request queue is not found
  /v1/bulk-operation/coupons/{batch_id}/status:
    get:
      tags:
      - Coupons
      summary: Query the status of a coupon import
      description: This endpoint allows you to query the status of a coupon batch import. It provides
        information about the current processing status of the operation, which can be `queued`, `processing`
        or `done`.
      parameters:
      - in: path
        name: batch_id
        required: true
        example: batch001
        description: The batch ID associated with the coupon import operation.
        schema:
          type: string
      responses:
        '200':
          description: 'Returned after the batch has been successfully added to the queue.

            Provides information about the batch status, including whether it is `queued`, `processing`,
            or `done`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponsStatusResponse'
              examples:
                Batch status - queued:
                  description: Returned if the batch is queued for processing
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 0
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status
                    payload:
                      batch_status: queued
                      number_of_coupons: 0
                Batch status - processing:
                  description: Returned if the batch is currently being processed
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 0
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status
                    payload:
                      batch_status: processing
                      number_of_coupons: 0
                Batch status - done:
                  description: Returned if the batch has been processed and the results are available
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 60
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/coupons/batch001/status
                      payload:
                        batch_status: done
                        number_of_coupons: 1000
        '404':
          description: The batch ID provided as a path parameter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBatchNotFound'
              examples:
                Batch ID is not found:
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 202004
                      message: Batch ID is not found
  /v1/bulk-operation/customer-list/{batch_id}/status/errors:
    get:
      tags:
      - Customer lists
      summary: Query the erronous list operation attempts
      description: This endpoint allows you to query information about any errors or issues encountered
        during a list operation process. It provides details about errors, if any, that occurred during
        the operation.
      parameters:
      - in: path
        name: batch_id
        required: true
        example: batch001
        description: The external batch ID associated with the list operation.
        schema:
          type: string
      - name: offset
        in: query
        description: 'Offsets the starting number of errors to return. This is used in pagination in conjunction
          with the limit query.

          '
        schema:
          type: integer
          example: 10
          default: 0
      - name: limit
        in: query
        description: 'Limits the number of errors to be returned in one response. Other values are accessible
          by pagination made accessible via the offset.

          '
        schema:
          type: integer
          example: 50
          default: 100
      responses:
        '200':
          description: Returned after the list operation request has been processed. Provides information
            about errors, if any, that occurred during the operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListErrorResponse'
              examples:
                Errors listed:
                  value:
                    status: success
                    metadata:
                      pagination:
                        total: 42
                        next: https://api.{environment}.antavo.com/customer-list/batch001/status/error?offset=40&limit=20
                        previous: https://api.{environment}.antavo.com/customer-list/batch001/status/error?offset=0&limit=20
                    payload:
                      number of errors: 42
                      customers:
                        customer_01:
                          customer_list: {}
                          error message: {}
                          error code: {}
                No errors:
                  value:
                    status: success
                    metadata:
                      pagination:
                        total: 0
                    payload:
                      number_of_errors: 0
                      customers: {}
        '404':
          description: The batch ID provided as a parameter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
  /v1/bulk-operation/customer-list/{batch_id}/status:
    get:
      tags:
      - Customer lists
      summary: Query the status of a list operation process
      description: This endpoint allows you to query the status of a list operation process, such as adding
        or removing customers from a customer list. It provides information about the current processing
        status of the operation.
      parameters:
      - in: path
        name: batch_id
        required: true
        example: batch001
        description: The external batch ID associated with the list operation.
        schema:
          type: string
      responses:
        '200':
          description: 'Returned after the batch has been successfully added to the queue.

            Provides information about the batch status, including whether it is `queued`, `processing`,
            or `done`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListStatusResponse'
              examples:
                Batch status - queued:
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 0
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error
                    payload:
                      batch_status: queued
                      number_of_customers: 0
                Batch status - processing:
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 0
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error
                    payload:
                      batch_status: processing
                      number_of_customers: 0
                Batch status - done:
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 60
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error
                      payload:
                        batch_status: done
                        number_of_customers: 1000
        '404':
          description: The batch ID provided as a path parameter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBatchNotFound'
  /v1/bulk-operation/reward/claim/{batch_id}/status/error:
    get:
      tags:
      - Rewards
      summary: Query the failed reward claim attempts
      description: This endpoint returns the error occured while processing the batch.
      parameters:
      - in: path
        name: batch_id
        description: The ID of the batch.
        required: true
        schema:
          type: string
          example: batch001
      - name: offset
        in: query
        description: 'Offsets the starting number of errors to return. This is used in pagination in conjunction
          with the limit query.

          '
        schema:
          type: integer
          example: 10
          default: 0
      - name: limit
        in: query
        description: 'Limits the number of errors to be returned in one response. Other values are accessible
          by pagination made accessible via the offset.

          '
        schema:
          type: integer
          example: 50
          default: 100
      responses:
        '200':
          description: Returned after the batch claim request has been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The batch ID provided as parameter does not exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNotFound'
      deprecated: false
  /v1/bulk-operation/reward/claim/{batch_id}/status:
    get:
      tags:
      - Rewards
      summary: Query the status of the reward claim process
      description: This API endpoint allows you to query the status of a bulk reward claim process, providing
        details on the processing status, any errors encountered, and the overall completion status.
      parameters:
      - in: path
        name: batch_id
        description: The ID of the batch.
        required: true
        schema:
          type: string
          example: batch001
      responses:
        '200':
          description: Returned after the batch has been successfully added to the queue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                Batch status - queued:
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 0
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error
                      pagination:
                        total: 0
                    payload:
                      batch_status: queued
                      customers: []
                Batch status - processing:
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 0
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error
                      pagination:
                        total: 0
                    payload:
                      batch_status: processing
                      customers: []
                Batch status - done:
                  value:
                    status: success
                    metadata:
                      bulk_operation_error:
                        number_of_errors: 60
                        url: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error
                      pagination:
                        total: 60
                        next: https://api.{environment}.antavo.com}/v1/bulk-operation/reward/claim/batch001/status?offset=40&limit=20
                        previous: https://api.{environment}.antavo.com}/v1/bulk-operation/reward/claim/batch001/status?offset=0&limit=20
                    payload:
                      batch_status: done
                      customers:
                      - claimed_at: 2023-07-25T15:15:16+01:0
                        code: 318-ogj-393
                        created_at: 2023-07-25T15:15:16+01:0
                        reward_id: 6275010c75c54b7810090000
                        id: 63dcb791eb80ef351838fdfb:318-ogj-393
                        type: gift_card
                        value: 100
                        customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                        batch_id: batch001
                        status: claimed
                        custom_attributes:
                          country: DE
                          purchase_treshold: 100
                          campaign: 23F/W
        '404':
          description: The batch ID provided as parameter does not exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchNotFound'
      deprecated: false
  /v1/bulk-operation/coupons/{coupon_pool_id}/{action}:
    post:
      tags:
      - Coupons
      summary: Manage coupon codes in coupon pools
      description: 'This endpoint allows you to upload, assign, and unassign coupons in Coupon Pools in
        batches. It supports both pre-assigned and unassigned coupons. Uploaded coupon batches are processed
        asynchronously.

        Each request can process up to 50,000 coupon codes.'
      parameters:
      - name: coupon_pool_id
        in: path
        description: The ID of an existing coupon pool for which the source is set to `uploaded`.
        required: true
        schema:
          type: string
          example: 146cb226c3d47e4d6a28176b
      - name: action
        in: path
        description: The action carried on the coupons, which can be `add`, `assign`, or `unassign`.
        required: true
        schema:
          type: string
          example: add
      requestBody:
        required: true
        description: Request body to import coupons to the specified coupon pool.
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/AddCouponsRequest'
              - $ref: '#/components/schemas/AssignCouponsRequest'
              - $ref: '#/components/schemas/UnassignCouponsRequest'
            examples:
              Add coupons:
                summary: Request body for the Add action
                value:
                  coupons:
                  - CODE1
                  - CODE2
              Assign coupons:
                summary: Request body for the Assign action
                value:
                  coupons:
                  - coupon_code: CODE1
                    customer_id: 30114810-8340-4144-a193-7699f66d184d
                  - coupon_code: CODE2
                    customer_id: e9e5a706-b785-405a-bcf3-2e7859fd59d3
                  - coupon_code: CODE3
              Unassign coupons:
                summary: Request body for the Unassign action
                value:
                  coupons:
                  - coupon_code: CODE1
                    customer_id: 30114810-8340-4144-a193-7699f66d184d
                  - coupon_code: CODE2
                    customer_id: e9e5a706-b785-405a-bcf3-2e7859fd59d3
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponsResponse'
              examples:
                Success:
                  value:
                    status: success
                    metadata:
                      external_batch_id: batch_001
                    payload:
                      batch_id: batch001
        '400':
          description: 400 Bad Request Exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
              examples:
                Payload is not found or is empty:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 202002
                      message: The 'payload' field is not found or empty
                Coupon codes exceed the limit:
                  value:
                    status: error
                    error:
                      type: BadRequestException
                      code: 202003
                      message: The list of codes exceeds the size limitation of the endpoint
        '404':
          description: 404 Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
              examples:
                Coupon pool not found:
                  summary: The coupon pool ID provided in the path does not match the ID or external ID
                    of an existing coupon pool
                  value:
                    status: error
                    error:
                      type: NotFoundException
                      code: 202001
                      message: Coupon Pool not found
  /v1/bulk-operation/customer-list/add/{customer_list_id}:
    post:
      tags:
      - Customer lists
      summary: Add customers to a customer list
      description: 'This API endpoint allows you to add a group of customers to a customer list all at
        once.

        It accepts a single customer list ID and an array of customer IDs as input.


        This API endpoint operates asynchronously, so customer list updates are processed separately.

        '
      parameters:
      - in: path
        name: customer_list_id
        required: true
        description: The ID of the customer list to which customers will be added to.
        schema:
          type: string
          example: 63f2cc942d6ef241c0167e6c
      responses:
        '200':
          description: Successful response with batch details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccesfulResponse'
        '400':
          description: Bad request, indicates missing or empty payload or exceeding payload size limitations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '404':
          description: Thrown in case there is no Customer list registered in Antavo with the ID provided
            in the path as customerListId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotFoundResponseAdd'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerList'
  /v1/bulk-operation/customer-list/remove/{customer_list_id}:
    post:
      tags:
      - Customer lists
      summary: Remove customers from a customer list
      description: 'This endpoint supports the removal of customers from a customer list in batches.

        It operates asynchronously, processing customer list updates separately.'
      parameters:
      - in: path
        name: customer_list_id
        example: 63f2cc942d6ef241c0167e6c
        required: true
        description: The ID of the customer list from which customers will be removed.
        schema:
          type: string
      responses:
        '200':
          description: Success response with batch details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccesfulResponse'
        '400':
          description: Bad request, indicates missing or empty payload or exceeding payload size limitations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '404':
          description: Thrown in case there is no Customer list registered in Antavo with the ID provided
            in the path as customer_list_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotFoundResponseRemove'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerListRemove'
  /v1/bulk-operation/reward/claim/{reward_id}:
    post:
      tags:
      - Rewards
      summary: Claim a specific reward to multiple customers
      description: 'Submit reward claim requests for a batch of customers. Each request can include a
        maximum of 100,000 customers.

        Please note that only one bulk reward claim process can run at a time for one specific reward.
        If additional batches are submitted while the current one is still processing, they will be added
        to the queue and processed once the ongoing batch is completed.

        By the end of the process, the reward events get registered in each customer''s event history.'
      parameters:
      - in: path
        name: reward_id
        required: true
        description: The ID of the reward to be claimed.
        schema:
          type: string
          example: 63dcb7736123782ba6336425
      responses:
        '200':
          description: The batch claim request has been submitted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBadRequest'
        '404':
          description: Reward not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardNotFound'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRewardClaim'
components:
  securitySchemes:
    api_key:
      type: apiKey
      description: Provides API Key access to the endpoint.
      name: api_key
      in: query
  schemas:
    NotFoundErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
          description: Status of the request.
        error:
          type: object
          properties:
            type:
              type: string
              example: NotFoundException
              description: Type of the error.
            code:
              type: string
              example: 330531
              description: Error code.
            message:
              type: string
              example: Batch ID is not found
              description: Human-readable error message.
    CouponsStatusResponse:
      type: object
      properties:
        status:
          type: string
          example: success
          description: Status of the request.
        metadata:
          type: object
          description: Metadata related to the bulk operation.
          properties:
            bulk_operation_error:
              type: object
              description: Any errors encountered during the bulk operation.
              properties:
                number_of_errors:
                  type: number
                  description: The number of encountered errors.
                url:
                  type: string
                  description: URL to retrieve detailed error information.
        payload:
          type: object
          description: Details of the bulk operation payload.
          properties:
            batch_status:
              type: string
              description: The status of the current batch.
            number_of_coupons:
              type: number
              description: The number of processed coupons.
    ListBatchNotFound:
      type: object
      properties:
        status:
          type: string
          example: error
          description: Status of the request.
        error:
          type: object
          description: Error details.
          properties:
            type:
              type: string
              example: NotFoundException
              description: Type of the error.
            code:
              type: number
              example: 330521
              description: Error code.
            message:
              type: string
              example: Batch ID is not found
              description: Human-readable error message.
    ListErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: success
          description: The current status of the process.
        metadata:
          type: object
          description: Metadata related to the bulk operation.
          properties:
            pagination:
              type: object
              properties:
                total:
                  type: number
                  description: Total number of entries.
                  example: 42
                next:
                  type: string
                  description: Link to access the next series of entries.
                  example: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error?offset=40&limit=20
                previous:
                  type: string
                  description: Link to access the previous series of entries.
                  example: https://api.{environment}.antavo.com/v1/bulk-operation/customer-list/batch001/status/error?offset=0&limit=20
        payload:
          type: object
          properties:
            number_of_errors:
              type: number
              example: 42
            customers:
              type: object
              properties:
                customer_01:
                  type: object
                  properties:
                    customer list:
                      type: string
                      example: null
                    error_message:
                      type: string
                      example: null
                    error_code:
                      type: number
                      example: null
    ListStatusResponse:
      type: object
      properties:
        status:
          type: string
          example: success
          description: The current status of the bulk process.
        metadata:
          type: object
          description: Metadata related to the bulk operation.
          properties:
            bulk_operation_error:
              type: object
              description: Errors occurred.
              properties:
                number_of_errors:
                  description: The number of errors encountered during the process.
                  type: number
                url:
                  type: string
                  description: URL to retrieve detailed error information.
            pagination:
              type: object
              properties:
                total:
                  type: number
                  description: Total number of entries.
                next:
                  type: string
                  description: Link to access the next series of entries.
                previous:
                  type: string
                  description: Link to access the previous series of entries.
    BatchNotFound:
      type: object
      properties:
        status:
          type: string
          example: error
          description: The status of the error.
        error:
          type: object
          properties:
            type:
              type: string
              description: Type of the error.
              example: NotFoundException
            code:
              type: number
              description: Error code.
              example: 320510
            message:
              type: string
              description: Human-readable error message.
              example: Batch ID is not found
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: success
          description: Status of the request.
        metadata:
          type: object
          description: Metadata related to the bulk operation.
          properties:
            pagination:
              type: object
              properties:
                total:
                  description: Total number of entries.
                  type: number
                  example: 42
                next:
                  description: Link to access the next series of entries.
                  type: string
                  example: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error?offset=40&limit=20
                previous:
                  description: Link to access the previous series of entries.
                  type: string
                  example: https://api.{environment}.antavo.com/v1/bulk-operation/reward/claim/batch001/status/error?offset=0&limit=20
        payload:
          description: Details of the bulk operation payload.
          type: object
          properties:
            number_of_errors:
              description: The number of errors encountered during the process.
              type: number
              example: 42
            customers:
              description: List of customers with erroneous reward claim attempts.
              type: object
              properties:
                customer_01:
                  type: object
                  properties:
                    reward:
                      type: string
                      example: 6275010c75c54b7810090000
                    error_message:
                      type: string
                      example: Sorry, you can't claim this reward, as it's currently out of stock
                    error_code:
                      type: number
                      example: 156156
    StatusResponse:
      type: object
      properties:
        status:
          type: string
          example: success
          description: Status of the request.
        metadata:
          type: object
          description: Metadata related to the bulk operation.
          properties:
            bulk_operation_error:
              type: object
              description: Any errors encountered during the bulk operation.
              properties:
                number_of_errors:
                  type: number
                  description: The number of errors encountered.
                url:
                  type: string
                  description: URL to retrieve detailed error information.
            pagination:
              type: object
              description: Pagination details for the bulk operation status.
              properties:
                total:
                  type: number
                  description: Total number of entries.
                  example: 100
        payload:
          type: object
          description: Details of the bulk operation payload.
          properties:
            batch_status:
              type: string
              description: The status of the current batch.
            customers:
              type: object
              description: List of customer-specific reward claim statuses.
              properties:
                customer_id:
                  type: string
                  description: The ID of the customer.
                reward_id:
                  type: number
                  description: The ID of the reward.
                batch_id:
                  type: string
                  description: The ID of the batch.
                code:
                  type: string
                  description: Status code of the reward claim for the customer.
                status:
                  type: string
                  description: Status of the reward claim for the customer.
                assigned_date:
                  type: string
                  format: timestamp
                  description: .
                expired_date:
                  type: string
                  format: timestamp
                  description: .
                type:
                  type: string
                  example: percentage
                  description: Type of the coupon.
                value:
                  type: number
                  description: Value of the coupon.
                custom_attributes:
                  type: object
                  description: Custom attributes associated with the reward.
                  properties:
                    country:
                      type: string
                      example: DE
                    purchase_treshold:
                      type: number
                      example: 100
                    campaign:
                      type: string
                      example: 23F/W
                      description: You can include any context variable here which you would like to associate
                        with this batch.
    BadRequestResponse:
      type: object
      properties:
        status:
          type: string
          example: error
          description: Status of the request.
        error:
          type: object
          description: Error details.
          properties:
            type:
              type: string
              example: BadRequestException
              description: Type of the error.
            code:
              type: number
              example: 330502
              description: Error code.
            message:
              type: string
              example: The 'payload' field is not found or empty
              description: Human-readable error message.
    AddCouponsRequest:
      type: object
      properties:
        coupons:
          type: array
          description: Coupon codes to be added to the coupon pool
          items:
            type: string
    AssignCouponsRequest:
      type: object
      required:
      - coupons
      properties:
        coupons:
          type: array
          description: Coupon codes to be assigned and the customer IDs to which they are assigned. If
            `customer_id` is not provided, the coupon is handled as unassigned.
          items:
            type: object
            required:
            - coupon_code
            properties:
              coupon_code:
                description: Coupon codes, which must be unique in each batch
                type: string
              customer_id:
                description: If the `customer_id` is provided, the coupon is assigned to the specified
                  customer. If left empty, the coupon is handled as unassigned.
                type: string
    UnassignCouponsRequest:
      type: object
      required:
      - coupons
      properties:
        coupons:
          type: array
          description: Coupon codes to be unassigned and the customer IDs from which to unassign them.
          items:
            type: object
            required:
            - coupon_code
            - customer_id
            properties:
              coupon_code:
                description: Coupon codes, which must be unique in each batch.
                type: string
              customer_id:
                description: The ID of the customer from which the coupon code is unassigned.
                type: string
    CouponsResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the request.
          example: success
        metadata:
          type: object
          properties:
            external_batch_id:
              type: string
              description: The external identifier of the batch.
        payload:
          type: object
          properties:
            batch_id:
              type: string
              description: The identifier of the batch.
    SuccesfulResponse:
      type: object
      properties:
        status:
          type: string
          example: success
          description: The status of the request.
        metadata:
          $ref: '#/components/schemas/metadatalist'
          description: Metadata related to the bulk operation.
        payload:
          type: object
          description: Details of the bulk operation.
    metadatalist:
      type: object
      properties:
        external_batch_id:
          type: string
          example: batch001
        payload:
          type: object
    ListNotFoundResponseAdd:
      type: object
      properties:
        status:
          type: string
          example: error
          description: Status of the request.
        error:
          type: object
          description: Error details.
          properties:
            type:
              type: string
              description: Type of the error.
              example: NotFoundException
            code:
              type: number
              description: Error code.
              example: 330501
            message:
              type: string
              description: Human-readable error message.
              example: Customer List not found
    CustomerList:
      type: object
      required:
      - customers
      properties:
        customers:
          type: array
          description: An array of strings representing unique customer IDs. Antavo will add customers
            associated with these IDs to the customer list.
          items:
            type: string
            example:
            - 280e674c-c4ea-4a30-987a-d9267d1a5018
            - afa53d5e-72e8-443b-8ac2-eab0cbaa181a
    ListNotFoundResponseRemove:
      type: object
      properties:
        status:
          type: string
          example: error
          description: Status of the request.
        error:
          type: object
          description: Error details.
          properties:
            type:
              type: string
              example: NotFoundException
              description: Type of the error.
            code:
              type: number
              example: 330511
              description: Error code.
            message:
              type: string
              example: Customer List not found
              description: Human-readable error message.
    CustomerListRemove:
      type: object
      required:
      - customers
      properties:
        customers:
          type: array
          description: List of customers to be removed.
          items:
            type: string
            example:
            - 280e674c-c4ea-4a30-987a-d9267d1a5018
            - afa53d5e-72e8-443b-8ac2-eab0cbaa181a
    response:
      type: object
      properties:
        status:
          type: string
          example: success
          description: Status of the batch claim request.
        metadata:
          $ref: '#/components/schemas/metadata'
        payload:
          type: object
    metadata:
      type: object
      properties:
        external_batch_id:
          type: string
          example: batch001
          description: The batch ID specified in the request.
        custom_attributes:
          type: object
          description: Any context variable that is associated with this submitted batch. Custom attributes
            are recorded on the coupon entity assigned to the customer during the bulk reward claim procedure.
          properties:
            id:
              type: string
              description: ID of the custom attribute
              example: country
            value:
              type: string
              description: Value of the custom attribute.
              example: DE
    BulkRewardClaim:
      type: object
      required:
      - customers
      properties:
        customers:
          type: array
          description: An array of strings representing unique customer IDs. If any of the customer IDs
            don't exist in the database, the batch will still be processed and the unknown customer IDs
            will be provided in the payload of the `/error` endpoint.
          items:
            type: string
            example:
            - 280e674c-c4ea-4a30-987a-d9267d1a5018
            - afa53d5e-72e8-443b-8ac2-eab0cbaa181a
        callback_url:
          type: string
          example: https://webservices.yourapi.com/callback_url
          description: Antavo will attempt to call this URL once the batch processing is finished. The
            webhook message sent to this URL provides the API URL to the /status endpoint to query the
            status of the batch claim process and any custom data that has been added to the bulk reward
            claim request. The `schema://hostname` of the callback URL must be configured in the [Trusted
            sites](https://docs.antavo.com/docs/trusted-sites#adding-a-new-site) module and able to handle
            REST API calls with JSON payload.
        metadata:
          $ref: '#/components/schemas/metadata'
          description: Metadata of key-value pairs.
        force_claim:
          type: boolean
          description: When set to `true`, the reward point price is treated as zero and the reward can
            be claimed without applying validation rules, except for stock restrictions.
    RewardNotFound:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: object
          properties:
            type:
              type: string
              example: NotFoundException
              description: Type of the error.
            code:
              type: number
              example: 320501
              description: Error code.
            message:
              type: string
              example: Reward not found
              description: Human-readable error message.
    ResponseBadRequest:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: object
          properties:
            type:
              type: string
              example: BadRequestException
              description: Type of the error.
            code:
              type: number
              example: 320503
              description: Error code.
            message:
              type: string
              example: The unique batch id provided already exists
              description: Human-readable error message.
security:
- api_key: []
tags:
- name: Coupons
  description: Bulk Coupons API endpoints
- name: Customer lists
  description: Bulk Customer List API endpoints
- name: Rewards
  description: Bulk Reward Claim API endpoints