openapi: 3.1.0
info:
  title: Thanx Consumer Account Purchases API
  description: The Thanx Consumer API lets brands integrate Thanx into a custom consumer experience, covering users and authentication, cards, gift cards, rewards, purchases, points and loyalty balances, locations, and feedback. It powers branded apps and digital experiences built on top of the Thanx loyalty and CRM platform. Endpoints are protected and authorized via end-user access tokens acquired through Thanx SSO.
  version: v4.0
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
  license:
    name: Proprietary
servers:
- url: https://api.thanx.com
  description: Production
- url: https://api.thanxsandbox.com
  description: Sandbox
- url: https://secure.api.thanx.com
  description: Production (PCI-scoped card endpoints)
- url: https://secure.api.thanxsandbox.com
  description: Sandbox (PCI-scoped card endpoints)
security:
- bearerAuth: []
  clientId: []
tags:
- name: Purchases
  description: Retrieve and report consumer purchases.
paths:
  /purchases:
    get:
      operationId: getPurchases
      summary: Get Purchases
      description: Retrieves consumer purchases, optionally filtered by merchant, location, or user.
      tags:
      - Purchases
      parameters:
      - name: merchant_id
        in: query
        schema:
          type: string
        example: 92b7b0dac4
      - name: location_id
        in: query
        schema:
          type: string
        example: 92b7b0dac4
      - name: user_id
        in: query
        schema:
          type: string
        example: 92b7b0dac4
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of purchases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchases:
                    type: array
                    items:
                      $ref: '#/components/schemas/Purchase'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                GetPurchases200Example:
                  summary: Default getPurchases 200 response
                  x-microcks-default: true
                  value:
                    purchases:
                    - id: 92b7b0dac4
                      user_id: 92b7b0dac4
                      merchant_id: 92b7b0dac4
                      location_id: 92b7b0dac4
                      purchased_at: '2025-06-01T18:02:05Z'
                      amount: 9.99
                      order:
                        id: 92b7b0dac4
                        provider: OLO
                    pagination:
                      total_page: 1
                      per_page: 1
                      current_page: 1
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPurchase
      summary: Create Purchase
      description: Reports a consumer purchase to Thanx.
      tags:
      - Purchases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                purchase:
                  $ref: '#/components/schemas/Purchase'
            examples:
              CreatePurchaseRequestExample:
                summary: Default createPurchase request
                x-microcks-default: true
                value:
                  purchase:
                    id: 92b7b0dac4
                    user_id: 92b7b0dac4
                    merchant_id: 92b7b0dac4
                    location_id: 92b7b0dac4
                    purchased_at: '2025-06-01T18:02:05Z'
                    amount: 9.99
                    order:
                      id: 92b7b0dac4
                      provider: OLO
      responses:
        '201':
          description: The created purchase.
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchase:
                    $ref: '#/components/schemas/Purchase'
              examples:
                CreatePurchase201Example:
                  summary: Default createPurchase 201 response
                  x-microcks-default: true
                  value:
                    purchase:
                      id: 92b7b0dac4
                      user_id: 92b7b0dac4
                      merchant_id: 92b7b0dac4
                      location_id: 92b7b0dac4
                      purchased_at: '2025-06-01T18:02:05Z'
                      amount: 9.99
                      order:
                        id: 92b7b0dac4
                        provider: OLO
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    PerPage:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
  schemas:
    Pagination:
      type: object
      properties:
        total_page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 1
        current_page:
          type: integer
          example: 1
    Purchase:
      type: object
      properties:
        id:
          type: string
          example: 92b7b0dac4
        user_id:
          type: string
          example: 92b7b0dac4
        merchant_id:
          type: string
          example: 92b7b0dac4
        location_id:
          type: string
          example: 92b7b0dac4
        purchased_at:
          type: string
          format: date-time
          example: '2025-06-01T18:02:05Z'
        amount:
          type: number
          format: double
          example: 9.99
        order:
          type: object
          properties:
            id:
              type: string
            provider:
              type: string
              enum:
              - OLO
              - Toast
              - Other
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: End-user access token acquired through Thanx SSO.
    clientId:
      type: apiKey
      in: header
      name: X-ClientId
      description: Client-specific identifier provided by Thanx.