openapi: 3.0.3
info:
  description: >-
    The Customer API provides another complementary access point to assist programs and integrations access the full potential of the Antavo Loyalty Management Platform. All Customer API requests should be made with a signed API. 

    In order to be compliant with GDPR standards, any searches for opted out customers will results in an empty search criteria as the  Antavo Loyalty Management Platform does not retain any customer identifiers upon un-enrollment.

  version: 1.0.0-oas3
  title: Offers
  termsOfService: "https://antavo.com/legals/terms"
  contact:
    email: support@antavo.com

servers:
  - url: https://api.academy.antavo.com
    description: The Antavo Academy
  - url: https://api.rc.antavo.com
    description: The Antavo rc test environment
  - url: https://api.salesdemo.antavo.com
    description: The Antavo Sales demonstration environment
  - url: https://api.staging.antavo.com
    description: The Antavo staging environment

 
tags:
  - name: Offers
    description: Core features related to customer rewards

paths:
  /offers/:
    post:
      tags:
        - Offers      
      summary: Returns customer-specific  offers
      description: |
        This API endpoint is used to submit the contents of a cart and return any available offers on the products within. This module is configured in the Antavo backoffice and has a dedicated documentation [here](https://antavo.atlassian.net/wiki/spaces/AUM/pages/451936284/Offers).
        The offers API  Request body consists of 4 components


        1. customer - The Antavo ID of the customer.
        
        2. eligible_only - Restricts the returned offers only to those available to the customer
      
        3. store - The  Antavo ID of the store. This may result in store-specific offers, if configured. 

        4. cart. The intended purchase items, recorded in the same format as an Antavo [checkout event](/api/events.html#checkout)
      responses:
        "200":
          description: A successful offer API submission
          content:
            "*/*":
              schema:
                 $ref: "#/components/schemas/response"
              examples:
                success:
                  summary: Successful submission
                  value:
                    data:
                    - id: 6319fb8c79cdb944fc746710
                      name: Documentation TEST
                      type: cart
                      weight: 5
                      min_total: 10
                      max_total: 100
                      required_match: any
                      required_items:
                      - type: list
                        min_quantity: '1'
                        id:
                        - aa
                        - bb
                        - cc
                        - dd
                      eligible_match: all
                      eligible_items: []
                      discount:
                        type: percent_discount
                        value: 10
                      is_exclusive: false
                      is_eligible: true
                      card_title: ''
                      card_description: ''
                    eligible_only: false
                    customer:
                      id: '001'
                    cart:
                      total: 22.5
                      items:
                      - product_id: aa
                        quantity: 2
                        price: 13.6
                        discount: 2.2
                        subtotal: 25
                      discount: 2.5
                      shipping: 0                   
                fail:
                  summary: "Error - Customer is not in the system or opted out"
                  value:
                    code: 160602 
                    message: Invalid customer ID
                fail7:
                  summary: Error - offer extension is not enabled
                  value:
                    code: 160600 
                    message: Rewards extension is not enabled
        "400":
          description: Missing required parameter - customer
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                fail:
                  summary: "Error - Customer property is not filled in correctly"
                  value:
                    type: BadRequestException
                    code: 0 
                    message: Missing required parameter ‘customer’
                fail2:
                  summary: Error - An invalid Cart structure
                  value:
                    type: BadRequestException
                    code: 0 
                    message: Cart structure validation Error
                fail3:
                  summary: Error - Cart items errors
                  value:
                    type: BadRequestException
                    code: 0
                    message: cart.items.1.quantity should be greater than or equal to 1
        "404":
          description: Not Found
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                fail:
                  summary: "Error - Wrong endpoint is called, possibly a non-existent reward id"
                  value:
                    code: 404
                    message: Not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OfferListRequest"
          
components:
  securitySchemes:
    ApiKeyAuth:        # arbitrary name for the security scheme
      type: apiKey
      in: query       # can be "header", "query" or "cookie"
      name: api_key  # name of the header, query parameter or cookie
  schemas: 
    response:
      type: object
      properties:
        data: 
          type: array
          items:
            $ref: "#/components/schemas/data"
        eligible_only:
          type: boolean
          description: Describes if the customer is eligible for returned offers 
          example: true
        customer: 
          type: object
          properties:
            id:
              type: string
              description: The Antavo Customer IDs
              example: OB1
        cart:
          type: object
          description: Contains information about the current cart contents of the customer.
          properties:
            schema:
              $ref: "#/components/schemas/Cart"     
    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: aabbccddeeffgghhiijjllkk
        name:
          type: string
          description: Displays name of the offer
          example: "20% off on KID items only"
        type: 
          type: string
          enum: [cart, item, combined]
          description: >
            Type of offers:
             * `cart` - Cart discount if  specific cart items are present
             * `item` - Item discount if present in cart 
             * `combined` - Discount for alternative item if a specified item is in the cart
        weight:
          type: number
          description: Value from 1-10 with a lower number resulting in higher priority.
          example: 3
        min_total:
          type: number
          description: Minimum cart total (Cart Offers)
          example: 10
        max_total:
          type: number
          description: Maximum cart total (Cart Offers)
          example: 99.9
        required_match:
          type: string
          enum: 
            - any 
            - all  
          description: >
            Matching eligible objects (Cart and Combined Offers):
              - `any`
              - `all` 
        required_items:
          type: array
          description: >
            List of required Items  for eligibility. (Cart and Combined Offers).
          items:
            $ref: "#/components/schemas/Item"
        eligible_match:
          type: string
          enum: 
            - any 
            - all  
          description: >
            Matching eligible objects (Cart and Combined Offers):
              - `any`
              - `all` 
        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
              enum: [“fixed_price”,“fixed_discount”,“percent_discount”]
              description: >
                Discount type:
                  - `Fixed price` -  set price for targeted eligible items (item or combined)
                  - `Fixed discount` - currency amount to be subtracted from target (eligible items or cart)
                - `Percent discount` - percentage to be subtracted from target (eligible items or cart)'   
              # example: "percent_discount"
            value: 
              type: number
              description: 'Value interpreted according to discount type.
                        Fixed price/discount: currency amount
                        Percent discount: percentage value (0-100)'
              example: 20
        is_exclusive:
          type: boolean
          description: Determines if this offer be used with others offers.
          example: false,
        is_eligible: 
          type: boolean
          description: Determines if this offer is eligible
          example: false,
        card_title:
          type: string
          description: The title of the offer to be displayed in a card.
          example: Test offer
        card_description:
          type: string
          description: The description of the offer to be displayed in a card.
          example:  A demonstration offer
    Item: 
      type: object     
      description: >
        items define the scope of the offer. An item can be either a Product or a Product Category.

      properties:
        type: 
          type: string
          enum: [product, category, list]
          description: >
            Type of item:
             - `product`
             - `category`
             - `list`
        id:
          type: string
          description: Category ID or Product SKU. An array of Product IDs or SKUs can also be returned.
        name:
          type: string
          description: Category/product name for displaying purposes. Not set for arrays
        min_quantity:
          type: number
          description: Default value is 1 unless specified
      required:
        - type
        - id
    OfferListRequest:
      type: object
      required:
        - cart
      properties:
        cart:
            $ref: "#/components/schemas/Cart"
        customer:
          type: string
          example: "9f3c82d6-288e-4361-aec0-039eb066a334"
          description: "An Anatvo-recognized unique customer identifier. Used to determine customer eligibility. A valid attribute will result in the return of possible loyalty/non-loyalty offers. Omitting this attribute results in only non-loyalty offers."
        store:
          type: string
          example: "3044"
          description: "An Antavo identifier of the current store.  Used to determine if there are any applicable offers. **See also**:  [Store Management in the User guide.](https://antavo.atlassian.net/wiki/spaces/AUM/pages/451969052/Store+Management)"
        eligible_only:
          type: boolean
          default: false
          example: True
          description: "This filter out non-eligible offers for 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
        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
        items:            
            $ref: "#/components/schemas/CartItems"
    CartItems:
      type: array
      description: Cart content to check against available offers.
      items:
        $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: "568433"
        quantity:
          type: number
          description: number of items
          example: 2
        price:
          type: number
          description: Unit prices
          example: 13.6
        discount:
          type: number
          description: Cart line discount value for given quantity
          example: 2.2
        subtotal:
          type: number
          description: "Cart line subtotal: price × quantity - discount"
          example: 25   
    ErrorResponse:
      type: object
      description: occurred
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            code:
              type: number
              description: >-
                A 6-digit number to uniquely identify the place the error
                occurred
              example: 404
            message:
              type: string
              description: Wrong endpoint is called, possibly a non-existent reward id
security:
  - ApiKeyAuth: []     # use the same name as under securitySchemes