openapi: 3.1.0
info:
  title: Thanx Loyalty API
  description: >-
    The Thanx Loyalty API supports integrations with digital ordering and kiosk
    providers, exposing account lookup and basket lifecycle operations so
    external ordering systems can connect to a brand's Thanx loyalty program,
    apply rewards and points products, and track loyalty progress. All
    endpoints are authorized via end-user access tokens and a merchant key.
  version: v1
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
  license:
    name: Proprietary
servers:
- url: https://loyalty.thanx.com
  description: Production
- url: https://loyalty.thanxsandbox.com
  description: Sandbox
security:
- bearerAuth: []
  merchantKey: []
tags:
- name: Account
  description: Retrieve a user's loyalty account, rewards, and points balances.
- name: Baskets
  description: Create and update ordering baskets and redeem rewards or points products.
paths:
  /api/account:
    get:
      operationId: getAccount
      summary: Get Account
      description: >-
        Retrieves the authenticated user's loyalty account, including available
        rewards, points products for redemption, loyalty progress, and points
        balances across configured experiences.
      tags:
      - Account
      parameters:
      - name: location_id
        in: query
        description: Thanx Location UID.
        schema:
          type: string
        example: 92b7b0dac4
      - name: redemption_venue
        in: query
        description: Venue where the redemption occurs.
        schema:
          type: string
          enum:
          - instore
          - online
          default: online
        example: instore
      - name: reward_states[]
        in: query
        description: Filter rewards by state.
        schema:
          type: array
          items:
            type: string
            enum:
            - delivered
            - active
          default:
          - delivered
      responses:
        '200':
          description: The loyalty account.
          content:
            application/vnd.thanx-v1+json:
              schema:
                $ref: '#/components/schemas/Account'
              examples:
                GetAccount200Example:
                  summary: Default getAccount 200 response
                  x-microcks-default: true
                  value:
                    id: 92b7b0dac4
                    email: jane.smith@example.com
                    rewards:
                    - id: 92b7b0dac4
                      value: 1.0
                      label: A free hamburger
                      state: redeemable
                      type: amount
                    points_products:
                    - id: 92b7b0dac4
                      label: A free hamburger
                      cost: 1.0
                    points_balances:
                    - points_experience_id: 92b7b0dac4
                      balance: 10.0
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/baskets:
    post:
      operationId: createUpdateBasket
      summary: Create And Update Basket
      description: >-
        Creates or updates an ordering basket and computes applicable loyalty
        discounts. Only a single reward or points product can be redeemed per
        order.
      tags:
      - Baskets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BasketInput'
            examples:
              CreateUpdateBasketRequestExample:
                summary: Default createUpdateBasket request
                x-microcks-default: true
                value:
                  id: 92b7b0dac4
                  state: open
                  order_timestamp: '2025-06-01T18:02:05Z'
                  location_uid: 92b7b0dac4
                  rewards:
                  - example
                  points_products:
                  - example
                  payments:
                  - issuer: example
                    last4: '1234'
                    amount: 9.99
                    authorized_at: '2025-06-01T18:02:05Z'
                  items:
                  - id: 92b7b0dac4
                    name: Pizza Town Co
                    price: 9.99
                    categories:
                    - example
                    modifiers:
                    - id: 92b7b0dac4
                      name: Pizza Town Co
                      price: 9.99
                      item_base_price: 9.99
                  subtotal: 9.99
      responses:
        '201':
          description: The created or updated basket.
          content:
            application/vnd.thanx-v1+json:
              schema:
                $ref: '#/components/schemas/Basket'
              examples:
                CreateUpdateBasket201Example:
                  summary: Default createUpdateBasket 201 response
                  x-microcks-default: true
                  value:
                    id: 92b7b0dac4
                    state: CA
                    discount: example
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: End-user access token.
    merchantKey:
      type: apiKey
      in: header
      name: Merchant-Key
      description: Merchant key provided by Thanx.
  responses:
    Unauthorized:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Account:
      type: object
      properties:
        id:
          type: string
          example: 92b7b0dac4
        email:
          type: string
          format: email
          example: jane.smith@example.com
        rewards:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyReward'
        points_products:
          type: array
          items:
            $ref: '#/components/schemas/PointsProduct'
        points_balances:
          type: array
          items:
            type: object
            properties:
              points_experience_id:
                type: string
              balance:
                type: number
                format: double
    LoyaltyReward:
      type: object
      properties:
        id:
          type: string
          example: 92b7b0dac4
        value:
          type: number
          example: 1.0
        label:
          type: string
          example: A free hamburger
        state:
          type: string
          enum:
          - redeemable
          - delivered
          - active
          example: redeemable
        type:
          type: string
          enum:
          - amount
          - percent
          - item
          example: amount
    PointsProduct:
      type: object
      properties:
        id:
          type: string
          example: 92b7b0dac4
        label:
          type: string
          example: A free hamburger
        cost:
          type: number
          format: double
          example: 1.0
    BasketInput:
      type: object
      required:
      - state
      - order_timestamp
      - location_uid
      - items
      - subtotal
      properties:
        id:
          type: string
          example: 92b7b0dac4
        state:
          type: string
          enum:
          - open
          - validated
          - billed
          - checkout
          example: open
        order_timestamp:
          type: string
          format: date-time
          example: '2025-06-01T18:02:05Z'
        location_uid:
          type: string
          example: 92b7b0dac4
        rewards:
          type: array
          items:
            type: string
        points_products:
          type: array
          items:
            type: string
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        items:
          type: array
          items:
            $ref: '#/components/schemas/BasketItem'
        subtotal:
          type: number
          format: double
          example: 9.99
    BasketItem:
      type: object
      properties:
        id:
          type: string
          example: 92b7b0dac4
        name:
          type: string
          example: Pizza Town Co
        price:
          type: number
          format: double
          example: 9.99
        categories:
          type: array
          items:
            type: string
        modifiers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              price:
                type: number
                format: double
              item_base_price:
                type: number
                format: double
    Payment:
      type: object
      properties:
        issuer:
          type: string
          example: example
        last4:
          type: string
          example: '1234'
        amount:
          type: number
          format: double
          example: 9.99
        authorized_at:
          type: string
          format: date-time
          example: '2025-06-01T18:02:05Z'
    Basket:
      type: object
      properties:
        id:
          type: string
          example: 92b7b0dac4
        state:
          type: string
          example: CA
        discount:
          type: string
          example: example
    Error:
      type: object
      properties:
        code:
          type: integer
          example: 1
        message:
          type: string
          example: example