Antavo Rewards API

openapi: 3.2.0
info:
  title: Antavo Rewards API
  version: '1.0'
  description: 'Operations tagged Rewards across 4 of this provider''s published API definitions: antavo-bulk-operations-openapi.yml, antavo-display-openapi.yml, antavo-entities-openapi.yml, antavo-rewards-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.staging.antavo.com
  description: The Antavo staging environment
tags:
- name: Rewards
  description: Bulk Reward Claim API endpoints
paths:
  /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
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /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
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /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'
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/{customer_id}/activities/rewards/{reward_id}:
    get:
      tags:
      - Rewards
      summary: Retrieve a specific reward available for a customer
      description: A endpoint provides detailed information about a specified reward available for a specific customer.
      parameters:
      - name: customer_id
        in: path
        required: true
        description: "Unique customer ID. This can be \n\n  * The Antavo customer ID\n  * An external ID (requires [configuration](/docs/customers#external-identifiers)): ``{external_field:external_id_value}``\n"
        schema:
          type: string
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
      - name: reward_id
        in: path
        required: true
        description: Unique indentifier of the reward.
        schema:
          type: string
          example: 668434f93d963535a513bf37
      - name: fields
        in: query
        description: 'Use the `claims` field to see the claimed rewards and associated information for each **currently** available reward.

          '
        schema:
          type: string
        example: claims
      responses:
        '200':
          description: The list of attributes of the reward. The list of information returned in the response depends on the type of the reward and its configured attribute. This example shows the attributes of claiming a **dynamic coupon** reward.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicCouponRewardActivity'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Reward is not active:
                  value:
                    type: BadRequestException
                    code: 160321
                    message: Reward is not active
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Customer not found:
                  value:
                    type: NotFoundException
                    code: 160212
                    message: Customer not found
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/{customer_id}/activities/rewards:
    get:
      tags:
      - Rewards
      summary: List all available rewards for a customer
      description: This endpoints provides the list of all available rewards for a specific customer.
      parameters:
      - name: customer_id
        in: path
        required: true
        description: "Unique customer ID. This can be \n\n   * The Antavo customer ID\n   * An external ID (requires [configuration](/docs/customers#external-identifiers)): ``{external_field:external_id_value}``\n"
        schema:
          type: string
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
      - name: fields
        in: query
        description: "Comma separated list of non-standard fields to be included in the response. Accepted values: \n\n* `claims`: See the claimed rewards and associated information for each **currently** available reward.\n\n* `custom_data`: Access this field set in the reward configuration.\n\n* `gallery`: Provides, where available, image links specified in the reward configuration.\n\n* `instructions`: Access redeem instructions set in the reward configuration.\n\n* `terms`: Access terms and conditions set in the reward configuration.\n\n* Any custom attributes configued in the [Entities module](https://docs.antavo.com/docs/custom-entities#adding-custom-entity-attributes) with `cf_` prefix.\n"
        schema:
          type: string
          enum:
          - claims
          - custom_data
          - events
          - gallery
          - instructions
          - terms
      - name: limit
        in: query
        description: 'Limits the number of rewards to be returned in one response. Other values are accessible by pagination made accessible via the offset.

          '
        schema:
          type: integer
          default: 100
      - name: offset
        in: query
        description: 'Offsets the starting number of rewards to return. This is used in pagination in conjunction with the limit query.

          '
        schema:
          type: integer
          default: 0
      - name: sort
        in: query
        description: 'Sorts the results by the selected value, which can be `starts_at`, `ends_at`, or `order`. This query can be used in conjunction with the order query.

          '
        schema:
          type: string
          example: starts_at
      - name: order
        in: query
        description: 'Used in conjunction with the sort query to list the results in ascending or descending order. The value can be `asc` for an ascending order or `desc` for a descending order.

          '
        schema:
          type: string
          example: desc
      responses:
        '200':
          description: List of rewards <br> The list of information returned in the response depends on the type of the reward and its configured attributes. This example shows the attributes of a **coupon** reward.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CouponPoolRewardActivity'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Customer not found:
                  value:
                    type: NotFoundException
                    code: 160212
                    message: Customer not found
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/{customer_id}/rewards:
    get:
      tags:
      - Rewards
      summary: List a customer's claimed rewards
      description: This endpoint provides the detailed list a customer's claimed rewards.
      parameters:
      - name: customer_id
        in: path
        required: true
        description: "Unique customer ID. This can be \n\n* The Antavo customer ID\n* An external ID (requires [configuration](/docs/customers#external-identifiers)): ``{external_field:external_id_value}``\n"
        schema:
          type: string
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
      - name: limit
        in: query
        description: "Limits the number of claimed rewards to be returned in one response. Additional claimed rewards can be accessed through pagination using the offset. \n"
        schema:
          type: integer
          default: 100
      - name: offset
        in: query
        description: "Specifies the starting number of claimed rewards to return. Used for pagination in combination with the limit query. \n"
        schema:
          type: integer
          default: 0
      - name: sort
        in: query
        description: 'Used in conjunction with the order query to sort the results in the selected order (ascending order by defualt).

          '
        schema:
          type: string
      - name: order
        in: query
        description: 'Used in conjunction with the sort query to list the results in ascending or descending order. The value can be `asc` for an ascending order or `desc` for a descending order.

          '
        schema:
          type: string
          example: desc
      - name: fields
        in: query
        description: "Comma separated list of non-standard fields to be included in the response. Accepted values: \n\n* `category`: Displays the reward's category, if assigned.\n\n* `custom_data`: Access fields set in the reward configuration under [Wehbook data](https://docs.antavo.com/docs/rewards#custom-fields).\n\n* `stock`: Access this field set in the reward configuration.\n\n* `gallery`: Provides, where available, image links specified in the reward configuration.\n\n* `instructions`: Access redeem instructions set in the reward configuration.\n\n* `terms`: Access terms and conditions set in the reward configuration.\n\n* `passes`: Access details for passes assigned to the customer through a reward claim.\n\n* Any custom attributes configued in the [Entities module](https://docs.antavo.com/docs/custom-entities#adding-custom-entity-attributes) with `cf_` prefix.\n"
        schema:
          type: string
          enum:
          - category
          - custom_data
          - stock
          - gallery
          - instructions
          - terms
          - passes
      responses:
        '200':
          description: List of reward claims
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardClaimA'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Customer not found:
                  value:
                    type: NotFoundException
                    message: Customer not found
                    code: 160212
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/{customer_id}/activities/rewards/{reward_id}/bid:
    post:
      tags:
      - Rewards
      summary: Submit a bid for the customer on a specified bidding reward
      description: 'The endpoint automatically calculates and submits a bid for a specified customer on the specific bidding reward. The bid amount is based on the current highest bid and the [bid step](https://docs.antavo.com/docs/rewards#bidding-rewards), which is set in the Antavo Management UI.


        Manually set value for bids is possible by submitting an amount in the request body.

        '
      parameters:
      - name: customer_id
        in: path
        schema:
          type: string
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
        required: true
        description: "Unique customer ID. This can be \n\n  * The Antavo customer ID\n  * An external ID (requires [configuration](/docs/customers#external-identifiers)): ``{external_field:external_id_value}``\n"
      - name: reward_id
        in: path
        schema:
          type: string
          example: 668477027cad34756c6cf005
        required: true
        description: Unique indentifier of the reward.
      requestBody:
        required: false
        description: 'A specific bidding amount has to be added to the request.  If no bid is submitted, the new bid amount will be the current bid + step size defined in the Management UI. '
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  description: A specific value for a bid. If empty, the automatic bid with a value <code>current value</code> + <code>bid step</code> will be submitted.
            example:
              amount: 160
      responses:
        '200':
          description: Bid successfully submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BidResponse'
        '400':
          description: Reward is not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Reward is not active:
                  value:
                    type: BadRequestException
                    message: Reward is not active
                    code: 160321
        '404':
          description: Customer or reward not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Customer not found:
                  value:
                    type: NotFoundException
                    code: 160212
                    message: Customer not found
                Reward not found:
                  value:
                    type: NotFoundException
                    message: Not Found
                    code: 0
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/{customer_id}/activities/rewards/{reward_id}/claim:
    post:
      tags:
      - Rewards
      summary: Claim a reward for a specific customer
      description: This endpoint allows for claiming a reward for a customer.
      parameters:
      - name: customer_id
        in: path
        required: true
        description: "Unique customer ID. This can be \n\n  * The Antavo customer ID\n  * An external ID (requires [configuration](/docs/customers#external-identifiers)): ``{external_field:external_id_value}``\n"
        schema:
          type: string
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
      - name: reward_id
        in: path
        required: true
        description: Unique reward ID.
        schema:
          type: string
          example: 63dcb7736123782ba6336425
      - name: fields
        in: query
        schema:
          type: string
          enum:
          - customer
          - reward
        description: "Returns additional objects in the response, using a comma separated list. Options: \n\n- **customer**: The complete customer response object with all customer attributes.\n- **reward**: The complete reward object with all reward attributes.\n"
      requestBody:
        required: false
        description: "A request body is **only** required for specific scenarios. \n\n1. Dynamic rewards: The stated points are used to calculate the value of the generated dynamic coupon.  \n\n2. Making multiple claims in a single API request: Repeated identical reward claims can be combined into an single request, reducing API traffic.\n"
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                points:
                  type: integer
                  description: Points to be used when claiming a dynamic type of reward.
                  example: 700
                count:
                  type: integer
                  description: The number of times that the reward is claimed in a single API request. This is only needed for multiple claims.
                  example: 2
      responses:
        '200':
          description: Claim result. A coupon object is returned only for coupon rewards.
          content:
            application/json:
              schema:
                type: object
                required:
                - spent
                properties:
                  spent:
                    type: integer
                    description: The number or points spent to claim the reward.
                    example: 700
                  id:
                    type: string
                    description: ID of the reward claim event
                  last_claimed_at:
                    type: string
                    format: date-type
                    description: The last time the customer claimed the reward.
                    example: '2021-11-23T08:34:59.000Z'
                  coupon:
                    $ref: '#/components/schemas/CouponClaim'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              example:
                Reward is not active:
                  value:
                    type: BadRequestException
                    message: Reward is not active
                    code: 160321
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Customer not found:
                  value:
                    type: NotFoundException
                    code: 160212
                    message: Customer not found
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/{customer_id}/activities/rewards/{reward_id}/revoke:
    post:
      tags:
      - Rewards
      summary: Revoke a previously claimed reward
      description: This endpoint revokes a specific reward claim.
      parameters:
      - name: customer_id
        in: path
        schema:
          type: string
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
        required: true
        description: "Unique customer ID. This can be \n\n  * The Antavo customer ID\n  * An external ID (requires [configuration](/docs/customers#external-identifiers)): ``{external_field:external_id_value}``\n"
      - name: reward_id
        in: path
        schema:
          type: string
          example: 668434f93d963535a513bf37
        required: true
        description: Unique indentifier of the reward.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                event:
                  type: string
                  description: The unique indentifier of the reward claim event.
                  example: 66676986c688963c28608f0c
      responses:
        '200':
          description: Successful revoke
          content:
            application/json:
              schema:
                type: object
                example: {}
        '400':
          description: Claim cannot be revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Claim already revoked:
                  value:
                    type: BadRequestException
                    code: 160344
                    message: Claim event already revoked
                Event not found:
                  value:
                    type: BadRequestException
                    code: 160340
                    message: Event not found
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                Customer not found:
                  value:
                    type: NotFoundException
                    code: 160212
                    message: Customer not found
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /entities/rewards/reward/{entity_id}:
    delete:
      tags:
      - Rewards
      summary: Archive an inactive reward
      description: This endpoint archives a specific deactivated reward, effectively removing it from the system. The reward will be completely non-visible and inaccessible for members and Management UI users as well.
      operationId: Rewarddelete
      parameters:
      - name: entity_id
        in: path
        required: true
        description: The unique ID of the reward.
        schema:
          type: string
      responses:
        '200':
          description: Reward archived
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: OK
        '400':
          description: Reward not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_3'
              examples:
                Failure:
                  value:
                    type: BadRequestException
                    code: 0
                    message: Entity not found
      deprecated: false
      security:
      - api_key: []
    post:
      tags:
      - Rewards
      summary: Update specific reward attributes
      description: An attribute of a reward can be updated via this endpoint.
      operationId: Rewardupdate
      parameters:
      - name: entity_id
        in: path
        description: The unique identifier of the reward.
        example: 63dcb7736123782ba6336425
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: The attributes of the reward to be updated. These must match attributes available in the Management UI.
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
              example:
                name: Reward name
                description: This is the description field
                price: 100
                type: coupon
        required: true
      responses:
        '200':
          description: Successful update - updated reward
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRewardResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_3'
              examples:
                Error:
                  value:
                    type: BadRequestException
                    message: '''<attribute>'' property is required'
                    code: 0
      security:
      - api_key: []
    get:
      tags:
      - Rewards
      summary: Returns all information regarding a specific reward
      description: A detailed breakdown of all parameters for the specific reward is returned.
      operationId: Rewardget
      parameters:
      - name: entity_id
        in: path
        required: true
        description: The unique ID of the reward.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRewardResponse'
        '400':
          description: Reward not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_3'
              examples:
                Failure:
                  value:
                    type: BadRequestException
                    code: 0
                    message: Entity not found
      deprecated: false
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /entities/rewards/reward:
    get:
      tags:
      - Rewards
      summary: List all available rewards
      description: This endpoint lists all available rewards.<br>It allows filtering by stores configured in the Stores module.
      parameters:
      - name: stores
        in: query
        required: false
        description: Filters the return rewards by stores, using a store ID.
        schema:
          type: string
          example: 667f3f88527d2e6c00319373
      responses:
        '200':
          description: List of all rewards - this example includes translations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRewardResponse'
      deprecated: false
      security:
      - api_key: []
    put:
      tags:
      - Rewards
      summary: Create a new reward
      description: This endpoint facilitates the creation of rewards.
      operationId: Rewardcreate
      parameters: []
      requestBody:
        description: The attributes of the reward to be created. These must match attributes available in the Management UI.
        content:
          application/json:
            schema:
              type: object
              example:
                name: 20% Off on Winter Collection
                description: Enjoy a 20% discount on our Winter Collection items.
                price: 100
                type: coupon
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardPut'
        '400':
          description: Bad request - a required attribute is not provided
          content:
            appl

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antavo/refs/heads/main/openapi/antavo-rewards-api-openapi.yml