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: Rewards
  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: Rewards
  description: Core features related to customer rewards

paths:
  /rewards:
    get:
      tags:
        - Rewards
      summary: Returns customer-specific  rewards
      parameters:
        - name: limit
          in: query
          required: false
          description: Limits the number of rewards returned per page
          schema:
            type: number
            default: 10
        - name: page
          in: query
          required: false
          description: >-
            This parameter get a specific page of the reward list if a limit has
            been set
          schema:
            type: number
            default: 0
        - name: min_price
          in: query
          required: false
          description: Lower point limit for returned eligible rewards
          schema:
            type: number
        - name: max_price
          in: query
          required: false
          description: Upper point limit for returned eligible rewards
          schema:
            type: number
        - name: customer
          in: query
          description: "The Antavo unique ID e.g., ``aabbccdeeff`` "
          schema:
            type: string
        - name: external_id
          in: query
          description: "Optional field - The customer field containing an external ID (requires [configuration](/appendix/external_id.html))"
          required: false
          schema:
            type: string 
      responses:
        "200":
          description: Eligible Rewards
          content:
            "*/*":
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Rewards"
        "404":
          description: Returned error object
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                fail7:
                  summary: Error - Rewards extension is not enabled
                  value:
                    code: 160600 
                    message: Rewards extension is not enabled
  /rewards/{reward_id}:
    get:
      tags:
        - Rewards      
      summary: Returns information regarding a specific reward
      parameters:
        - name: reward_id
          in: path
          required: true
          description: The unique id of the reward
          schema:
            type: string
      responses:
        "200":
          description: Reward data JSON object
          content:
            "*/*":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Reward"
        "404":
          description: Returned error object
          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

  /rewards/{reward_id}/claim:
    post:
      tags:
        - Rewards      
      summary: claiming a specific reward
      parameters:
        - name: reward_id
          in: path
          required: true
          description: The unique id of the reward
          schema:
            type: string
      responses:
        "200":
          description: Reward data JSON object
          content:
            "*/*":
              schema:
                oneOf:
                  - $ref: "#/components/schemas/RewardClaim"
                  - $ref: "#/components/schemas/ErrorResponse"
              examples:
                success:
                  summary: Successful submission
                  value:
                    spent: 100
                    coupon:
                      code: "ABC-DEF-GHI" 
                      type: "percentage"
                fail:
                  summary: "Error - Customer is not in the system or opted out"
                  value:
                    code: 160602 
                    message: Invalid customer ID
                fail2:
                  summary: Error - Customer is not enrolled in the loyalty program. Status is “inactive”
                  value:
                    code: 1606023
                    message: Customer is not active
                fail3:
                  summary: Error - Customer already claimed the maximum number of rewards
                  value:
                    code: 120211 
                    message: Customer can’t claim this reward more times
                fail4:
                  summary: Error - Reward stock is 0. Check reward settings
                  value:
                    code: 120212 
                    message: Reward stock ran out
                fail6:
                  summary: Error - Customer point balance is less than the price of the reward
                  value:
                    code: 120241 
                    message: Customer does not have enough points
                fail7:
                  summary: Error - Rewards 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:
                    code: 400 
                    message: Missing required parameter ‘customer’

        "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:
              type: object
              required:
                - customer
              properties:
                customer:
                  type: string
                  description: An Anatvo-recognized unique customer identifier
                external_id:
                  type: string
                  description: "Optional field - The customer field containing an external ID (requires [configuration](/appendix/external_id.html))"
                


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:    
    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
    Reward:
      type: object
      description: A reward item
      properties:
        id:
          type: string
          description: Reward ID
          example: 55e5d4dc2cf1901e688b45d3
        name:
          type: string
          description: Offer display name
          example: A 64GB pendrive with illuminating flashing logo.
        category:
          type: string
          description: "Type of reward, must correlate with the category set in Backoffice"
          example: Branded goods.
        price:
          type: number
          description: Value of reward
          example: 100
        image_url:
          type: string
          description: Picture of reward
          example: "https://example.com/image_url.png"
    Rewards:
      type: object
      description: List of Offer objects
      properties:
        id:
          type: string
          description: Reward ID
          example: 55e5d4dc2cf1901e688b45d3
        name:
          type: string
          description: Offer display name
          example: A 64GB pendrive with illuminating flashing logo.
        category:
          type: string
          description: "Type of reward, must correlate category set in Backoffice"
          example: Branded goods.
        price:
          type: number
          description: Value of reward
          example: 100
        image_url:
          type: string
          description: Picture of reward
          example: "https://example.com/image_url.png"
    RewardClaim:
      type: object
      description: A successful reward claim
      properties:
        spent:
          type: number
          description: The number of points spent by the customer
          example: 100
        coupon:
          type: object
          description: "The awarded coupon, where appropriate"
          properties:
            code:
              type: string
              description: Assigned coupon code
              example: AH356K1
            type:
              type: string
              description: Type of assigned coupon
              example: percentage
security:
  - ApiKeyAuth: []     # use the same name as under securitySchemes