openapi: 3.0.0
info:
  contact:
    email: support@antavo.com
  title: Antavo Offers API
  version: 1.0.0-oas3
servers:
- url: https://api.staging.antavo.com
  description: The Antavo staging environment
paths:
  /offers/:
    post:
      tags:
      - Offers
      summary: List customer-specific offers
      description: 'This API endpoint is used to submit the contents of a cart and receive any available
        offers on the products within.

        The Offers API request body consists of 4 components:


        - `cart`: The intended purchase items, recorded in the same format as an Antavo checkout event.

        - `customer`: The Antavo ID of the customer.

        - `store`: The Antavo ID of the store. This may result in store-specific offers if configured.

        - `eligible_only`: Restricts the returned offers to those available to the customer.

        '
      responses:
        '200':
          description: Successful cart submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
              examples:
                success:
                  summary: Successful submission
                  value:
                    data:
                    - id: offer_12345
                      name: 10% off
                      type: cart
                      weight: 1
                      min_total: 20
                      max_total: 100
                      required_match: any
                      required_items:
                      - type: product
                        id: prd_987654
                        name: Vintage Leather Jacket
                        min_quantity: '1'
                      eligible_match: all
                      eligible_items:
                      - type: product
                        id: prd_987654
                        name: Classic Denim Jeans
                        min_quantity: '1'
                      discount:
                        type: percent_discount
                        value: 10
                      is_exclusive: true
                      is_eligible: true
                      card_title: 10% Discount
                      card_description: Get 10% off on your purchase
                    eligible_only: false
                    customer:
                      id: 9f3c82d6-288e-4361-aec0-039eb066a334
                    cart:
                      total: 22.22
                      items:
                      - product_id: prd_987654
                        quantity: 2
                        price: 13.6
                        discount: 1
                        subtotal: 18
                      discount: 2.5
                      shipping: 0
                fail:
                  summary: Error - Customer is not in the system or opted out
                  value:
                    code: 160602
                    message: Invalid customer ID
        '400':
          description: Missing required parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                fail:
                  summary: Error - Customer parameter is missing
                  value:
                    type: BadRequestException
                    code: 0
                    message: Missing required parameter ‘customer’
                fail2:
                  summary: Error - invalid Cart structure
                  value:
                    type: BadRequestException
                    code: 0
                    message: Cart structure validation Error
                fail3:
                  summary: Error - Cart item errors
                  value:
                    type: BadRequestException
                    code: 0
                    message: cart.items.1.quantity should be greater than or equal to 1
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                fail:
                  summary: Error - Not found
                  value:
                    code: 0
                    message: Not Found
                    type: NotFoundException
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferListRequest'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
  schemas:
    response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/data'
        eligible_only:
          type: boolean
          description: Indicates if the response includes offers that the customer is eligible for.
          example: false
        customer:
          type: object
          description: Information about the customer.
          properties:
            id:
              type: string
              description: The Antavo Customer ID.
              example: 9f3c82d6-288e-4361-aec0-039eb066a334
        cart:
          type: object
          description: Contains information about the content of the customer's cart.
          properties:
            total:
              type: string
              description: The total value of the customer's cart including all items.
              example: 22.22
            items:
              $ref: '#/components/schemas/CartItems'
    data:
      type: array
      description: An array of Offer objects
      items:
        $ref: '#/components/schemas/offer'
    offer:
      type: object
      properties:
        id:
          type: string
          description: The Antavo ID for the specific offer.
          example: offer_12345
        name:
          type: string
          description: The name of the offer.
          example: 10% off
        type:
          type: string
          description: "The type of the offer:\n * `cart`\n * `item`\n * `combined`\n"
        weight:
          type: number
          description: Value from 1-10 with a lower number resulting in higher priority.
          example: 1
        min_total:
          type: number
          description: Minimum cart total eligible for the offer.
          example: 20
        max_total:
          type: number
          description: Maximum cart total eligible for the offer.
          example: 100
        required_match:
          type: string
          description: "Defines if all or at least one of the required items should be added to the cart\
            \ (`cart` and `combined` offers):\n  - `any`\n  - `all` \n"
        required_items:
          type: array
          description: 'List of required items for eligibility (`cart` and `combined` offers).

            '
          items:
            $ref: '#/components/schemas/Item'
        eligible_match:
          type: string
          description: "Defines if all or at least one of the required items should be added to the cart\
            \ (`cart` and `combined` offers).\n  - `any`\n  - `all` \n"
        eligible_items:
          type: array
          description: 'List of eligible items (`cart` and `combined` offers).

            '
          items:
            $ref: '#/components/schemas/Item'
        discount:
          type: object
          description: List of Offer objects.
          required:
          - type
          - value
          - target
          properties:
            type:
              type: string
              description: "Discount type:\n  - `fixed_price` -  Set price for targeted eligible items\
                \ (`item` or `combined`).\n  - `fixed_discount` - Currency amount to be subtracted from\
                \ target (`item` or `cart`)\n  - `percent_discount` - Percentage to be subtracted from\
                \ target (`items` or `cart`)  \n"
              example: percent_discount
            value:
              type: number
              description: "Value of the offer depending on to discount type:\n  - `fixed_price` and `fixed_discount`\
                \ - currency amount\n  - `percent_discount` - percentage value (0-100)\n"
              example: 10
        is_exclusive:
          type: boolean
          description: Incidates if this offer can be used with other offers.
          example: true
        is_eligible:
          type: boolean
          description: Indicates if the customer is eligible to redeem the offer.
          example: true
        card_title:
          type: string
          description: The title of the offer.
          example: 10% Discount
        card_description:
          type: string
          description: The description of the offer.
          example: Get 10% off on your purchase.
    Item:
      type: object
      properties:
        type:
          type: string
          enum:
          - product
          - category
          - list
          description: "Type of item:\n - `product`\n - `category`\n - `list`\n"
          example: product
        id:
          type: string
          description: Category ID or Product SKU. An array of Product IDs or SKUs can also be returned.
          example: prd_987654
        name:
          type: string
          description: Name of the category or product.
          example: Classic Denim Jeans
        min_quantity:
          type: number
          description: Minimum quantity required to qualify for the offer. Defaults to 1 if not specified.
          example: 1
      required:
      - type
      - id
    OfferListRequest:
      type: object
      required:
      - cart
      - customer
      properties:
        cart:
          $ref: '#/components/schemas/Cart'
        customer:
          type: string
          example: 9f3c82d6-288e-4361-aec0-039eb066a334
          description: An Antavo-recognized unique customer identifier. This is used to determine customer
            eligibility. Providing a valid attribute will result in the return of possible loyalty and
            non-loyalty offers.
        store:
          type: string
          example: '3044'
          description: An Antavo identifier of the store where the purchase is made. Used to determine
            if there are any applicable offers.
        eligible_only:
          type: boolean
          default: true
          example: true
          description: Filters out non-eligible offers based on the current context (cart, customer, date,
            etc.)
    Cart:
      type: object
      description: Cart content to check against available offers.
      required:
      - total
      - items
      properties:
        total:
          type: number
          description: The total value of the customer's cart including all items.
          example: 22.22
        items:
          $ref: '#/components/schemas/CartItems'
        discount:
          type: number
          description: Cart discount, already subtracted from total.
          example: 2.22
        shipping:
          type: number
          description: Shipping fee, already subtracted from total.
          example: 4.44
    CartItems:
      type: array
      description: Cart content to check against available offers.
      items:
        description: Cart content to check against available offers.
        $ref: '#/components/schemas/CartItem'
    CartItem:
      type: object
      description: Cart content to check against available offers.
      required:
      - product_id
      - quantity
      properties:
        product_id:
          type: string
          description: Product ID or SKU.
          example: prd_987654
        quantity:
          type: number
          description: Number of items purchased.
          example: 2
        price:
          type: number
          description: Unit price of the product.
          example: 10
        discount:
          type: number
          description: Product discount value for given quantity.
          example: 1
        subtotal:
          type: number
          description: 'Product subtotal: price × quantity - discount'
          example: 18
    ErrorResponse:
      type: object
      description: occurred
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          properties:
            type:
              type: string
              description: Type of the message.
              example: BadRequestException
            code:
              type: number
              description: "Error code.\t"
              example: 404
            message:
              type: string
              description: Human-readable error message.
              example: cart.total should be numeric
security:
- ApiKeyAuth: []
tags:
- name: Offers