Antavo Loyalty Read API

openapi: 3.0.0
info:
  contact:
    name: Antavo
    url: https://antavo.com
  title: Antavo Loyalty Read API
  version: 0.1.0
servers:
- url: https://read-api.<environment>.antavo.com
paths:
  /v1/customers/{customer_id}:
    get:
      operationId: getCustomer
      summary: Retrieve detailed customer data of a single customer
      description: Retrieves a customer by customer ID and returns the data associated with the customer.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/CustomerIdParam'
      responses:
        '200':
          description: Success - Customer data provided
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - metadata
                - payload
                properties:
                  status:
                    type: string
                    const: success
                    example: success
                  metadata:
                    type: object
                  payload:
                    $ref: '#/components/schemas/CustomerEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Error - Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        5XX:
          $ref: '#/components/responses/ServerError'
  /v1/customers/{customer_id}/coupons:
    get:
      operationId: listCustomerCoupons
      summary: Retrieve the list of a customer's coupons
      description: 'Returns a paginated list of coupons associated with a specific customer.

        Results can be filtered by `status`, `claimed_at`, `redeemed_at`, `expiration_date` coupon attribute
        values, and sorted by `claimed_at`, `redeemed_at`, `expiration_date` values.

        '
      tags:
      - Coupons
      parameters:
      - $ref: '#/components/parameters/CustomerIdParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: filter
        in: query
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/CouponsFilter'
      - name: sort
        in: query
        style: deepObject
        explode: true
        description: 'Sorts results by one or more fields in the specified order. Each field can be used
          only once.

          When multiple sort instructions are provided, the first field is used as the primary sort field.
          Each additional field determines the order of results that have the same value for the preceding
          field.

          Example: `?sort[0][field]=claimed_at&sort[0][direction]=asc&sort[1][field]=redeemed_at&sort[1][direction]=desc`

          '
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCouponSortEntry'
      responses:
        '200':
          description: Success - Coupon data provided
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - metadata
                - payload
                properties:
                  status:
                    type: string
                    const: success
                    example: success
                  metadata:
                    allOf:
                    - $ref: '#/components/schemas/CollectionMetadata'
                    example:
                      pagination:
                        next: /v1/customers/55e5d4dc2cf1901e688b45d3/coupons?offset=0&limit=20
                        previous: null
                  payload:
                    type: object
                    required:
                    - coupons
                    properties:
                      coupons:
                        type: array
                        description: Coupons associated with the customer.
                        items:
                          $ref: '#/components/schemas/CouponEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        5XX:
          $ref: '#/components/responses/ServerError'
  /v1/customers/{customer_id}/events:
    get:
      operationId: listCustomerEvents
      summary: Retrieve the list of a customer's events
      description: 'Returns paginated list of events registered in the customer''s events history.

        Results can be filtered and sorted by `action`, `date`, `account`, `expdate` and `points` event
        attribute values.

        '
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/CustomerIdParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: filter
        in: query
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/EventsFilter'
      - name: sort
        in: query
        style: deepObject
        explode: true
        description: 'Sorts results by one or more fields in the specified order. Each field can be used
          only once.

          When multiple sort instructions are provided, the first field is used as the primary sort field.
          Each additional field determines the order of results that have the same value for the preceding
          field.

          Example: `?sort[0][field]=action&sort[0][direction]=asc&sort[1][field]=points&sort[1][direction]=desc`

          '
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CustomerEventSortEntry'
      responses:
        '200':
          description: Success - Customer event data provided
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - metadata
                - payload
                properties:
                  status:
                    type: string
                    const: success
                  metadata:
                    allOf:
                    - $ref: '#/components/schemas/CollectionMetadata'
                    example:
                      pagination:
                        next: /v1/customers/55e5d4dc2cf1901e688b45d3/events?offset=0&limit=20
                        previous: null
                  payload:
                    type: object
                    required:
                    - events
                    properties:
                      events:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventEntity'
              example:
                status: success
                metadata:
                  pagination:
                    next: null
                    previous: null
                payload:
                  events:
                  - _id: 6a57a9681d81297bdc042a6e
                    timestamp: '2026-06-13T15:38:16+00:00'
                    unix_timestamp: 1784129896
                    process_timestamp: '2026-06-13T15:38:16+00:00'
                    date: '2026-06-13'
                    ip_address: 87.97.9.123
                    user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
                    customer: 55e5d4dc2cf1901e688b45d3
                    action: checkout
                    points: 0
                    properties:
                      transaction_id: txn_8f3c2a91d7b64e5a
                      total: 119.96
                      points_burned: 0
                      currency: GBP
                    admin: false
                    hash: checkout-txn_8f3c2a91d7b64e5a
                    user_id: 100012233
                    signed: false
                    source: Events API
                    account: family_account
                    cid: 5098a0ea-70e1-8c3b-4e4b-ac585cb9fed2
                    snapshot:
                      score: 34749
                      spent: 12167
                      pending: 34521
                      expired: 0
                  - _id: 6a57dae6998349a15c05813a
                    timestamp: '2026-06-13T15:38:16+00:00'
                    unix_timestamp: 1784129896
                    process_timestamp: '2026-06-13T15:38:16+00:00'
                    date: '2026-06-13'
                    ip_address: 87.97.9.123
                    user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
                    customer: 55e5d4dc2cf1901e688b45d3
                    action: checkout_item
                    points: 60
                    properties:
                      transaction_id: txn_8f3c2a91d7b64e5a
                      total: 59.98
                      product_id: PROD-84721
                      product_name: Classic Leather Sneakers
                      product_url: https://example.com/products/prod-84721
                      quantity: 2
                      country: GB
                      points_rewarded: 60
                      subtotal: 49.98
                      price: 29.99
                      discount: 10
                      unit_burn: 0
                      currency: GBP
                      product_category: Footwear > Sneakers
                      store: london-oxford-street
                      effective_timestamp: 1784129896
                      total_quantity: 2
                    parent: 6a57a9681d81297bdc042a6e
                    change:
                      id: 6a57a9681d81297bdc042a6f
                      at: '2026-07-15T19:09:26+00:00'
                      by: '100012233'
                    admin: false
                    hash: checkout_item-txn_8f3c2a91d7b64e5a-PROD-84721
                    signed: false
                    expdate: '2026-07-16'
                    source: Events API
                    account: family_account
                    cid: 5098a0ea-70e1-8c3b-4e4b-ac585cb9fed2
                    snapshot:
                      score: 34749
                      spent: 12167
                      pending: 34521
                      expired: 0
                  - _id: 69efdcada19262f4a90101f8
                    timestamp: '2026-04-27T22:01:17+00:00'
                    unix_timestamp: 1777327277
                    process_timestamp: '2026-04-27T22:01:17+00:00'
                    date: '2026-04-27'
                    ip_address: 91.82.30.113
                    user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
                    customer: 55e5d4dc2cf1901e688b45d3
                    action: point_add
                    points: 100
                    properties:
                      points: 100
                    admin: false
                    user_id: 100012233
                    signed: false
                    source: Platform
                    cid: d62c732a-a525-96cc-80cc-498889fc1053
                    snapshot:
                      score: 34649
                      spent: 12167
                      pending: 34521
                      expired: 0
                    usages:
                      652f9bad5924e77e8269be13: 100
                    used_points: 100
                    expired: true
                    original: 6a57a9681d81297bdc042a6f
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        5XX:
          $ref: '#/components/responses/ServerError'
  /v1/customers:
    get:
      operationId: listCustomers
      summary: Retrieve the list of customers
      description: 'Returns a paginated list of customers, including standard customer fields and any
        custom customer attributes configured in the workspace.

        Results can be filtered and sorted by `created_at` and `status` customer attribute values.

        '
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: filter
        in: query
        style: deepObject
        explode: true
        description: Use the supported fields and operators to filter the results.
        schema:
          $ref: '#/components/schemas/CustomersFilter'
      - name: sort
        in: query
        style: deepObject
        explode: true
        description: 'Sorts results by one or more fields in the specified order. Each field can be used
          only once.

          When multiple sort instructions are provided, the first field is used as the primary sort field.
          Each additional field determines the order of results that have the same value for the preceding
          field.

          Example: `?sort[0][field]=status&sort[0][direction]=asc&sort[1][field]=created_at&sort[1][direction]=desc`

          '
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSortEntry'
      responses:
        '200':
          description: Success - Customer data provided
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - metadata
                - payload
                properties:
                  status:
                    type: string
                    const: success
                  metadata:
                    allOf:
                    - $ref: '#/components/schemas/CollectionMetadata'
                    example:
                      pagination:
                        next: /v1/customers/55e5d4dc2cf1901e688b45d3/customers?offset=0&limit=20
                        previous: null
                  payload:
                    type: object
                    required:
                    - customers
                    properties:
                      customers:
                        type: array
                        items:
                          $ref: '#/components/schemas/CustomerEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        5XX:
          $ref: '#/components/responses/ServerError'
  /v1/customers/{customer_id}/transactions:
    get:
      operationId: listCustomerTransactions
      summary: Retrieve the list of a customer's transactions
      description: 'Returns a paginated list of transactions registered for the customer, including their
        items, associated events, point values, and current processing status.

        Results can be filtered and sorted by `status`, `checkout_date`, `auto_accept`, `account`, `points_rewarded`,
        `earned`, and `burned` transaction attribute values.

        '
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/CustomerIdParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: filter
        in: query
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/TransactionsFilter'
      - name: sort
        description: 'Sorts results by one or more fields in the specified order. Each field can be used
          only once.

          When multiple sort instructions are provided, the first field is used as the primary sort field.
          Each additional field determines the order of results that have the same value for the preceding
          field.

          Example: `?sort[0][field]=status&sort[0][direction]=asc&sort[1][field]=earned&sort[1][direction]=desc`

          '
        in: query
        style: deepObject
        explode: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CustomerTransactionSortEntry'
      responses:
        '200':
          description: Success - Transaction data provided
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - metadata
                - payload
                properties:
                  status:
                    type: string
                    const: success
                  metadata:
                    allOf:
                    - $ref: '#/components/schemas/CollectionMetadata'
                    example:
                      pagination:
                        next: /v1/customers/55e5d4dc2cf1901e688b45d3/transactions?offset=0&limit=20
                        previous: null
                  payload:
                    type: object
                    required:
                    - transactions
                    properties:
                      transactions:
                        type: array
                        description: Transactions associated with the customer.
                        items:
                          $ref: '#/components/schemas/TransactionEntity'
              example:
                status: success
                metadata:
                  pagination:
                    next: /v1/customers/55e5d4dc2cf1901e688b45d3/transactions?offset=0&limit=20
                    previous: null
                payload:
                  transactions:
                  - _id: txn_8f3c2a91d7b64e5a
                    created_at: '2025-11-13T13:10:19+00:00'
                    updated_at: '2025-11-13T13:10:20+00:00'
                    customer: 55e5d4dc2cf1901e688b45d3
                    status: accepted
                    event: 6734a53c8bd9da0c85066e1b
                    items:
                    - transaction_id: txn_8f3c2a91d7b64e5a
                      total: 100
                      product_id: prd_987654
                      product_name: Vintage Leather Jacket
                      product_url: https://example.com/products/vintage-leather-jacket
                      quantity: 1
                      points_rewarded: 50
                      subtotal: 50
                      price: 50
                      discount: 0
                      currency: EUR
                      total_quantity: 2
                    - transaction_id: txn_8f3c2a91d7b64e5a
                      total: 100
                      product_id: prd_123456
                      product_name: Classic Denim Jeans
                      product_url: https://example.com/products/classic-denim-jeans
                      quantity: 1
                      points_rewarded: 50
                      subtotal: 50
                      price: 50
                      discount: 0
                      currency: EUR
                      total_quantity: 2
                    total: 100
                    earned: 0
                    burned: 0
                    events:
                    - _id: 6734a53c8bd9da0c85066e1b
                      action: checkout
                      points: 0
                    - _id: 6734a53c8bd9da0c85066e1c
                      action: checkout_item
                      points: 0
                    - _id: 6734a53c8bd9da0c85066e1d
                      action: checkout_item
                      points: 0
                    - _id: 6734a53c8bd9da0c85066e1e
                      action: pending_campaign_bonus
                      points: 0
                    currency: EUR
                    points_rewarded: 100
                    account: family_account
                    auto_accept: '2025-12-13'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        5XX:
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    CustomerIdParam:
      name: customer_id
      in: path
      required: true
      description: Customer identifier. Using an external ID is not supported.
      schema:
        type: string
    OffsetParam:
      name: offset
      in: query
      description: 'Offsets the starting position in the sorted result set. Used for pagination together
        with the `limit` query parameter.

        '
      schema:
        type: integer
        minimum: 0
        default: 0
    LimitParam:
      name: limit
      in: query
      description: 'Sets the maximum number of items to return from the sorted result set. Used for pagination
        together with the `offset` query parameter.

        '
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 20
  schemas:
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Contains details about the error.
          required:
          - message
          - code
          - resendable
          properties:
            message:
              type: string
              description: Human-readable description of the error.
              example: Unauthorized
            code:
              type: integer
              description: Numeric code identifying the error.
              example: 2132
            resendable:
              type: boolean
              description: Indicates whether the request can be retried.
              example: false
    CustomerEntity:
      type: object
      description: 'Customer entity. The fields and values returned may differ based on workspace configuration.

        '
      properties:
        _id:
          type: string
          description: The unique customer identifier.
          example: 55e5d4dc2cf1901e688b45d3
        external_ids:
          type: object
          description: 'External IDs associated with the customer.

            Omitted when the customer has no external ID.

            '
          properties:
            crm_id:
              type: string
              description: 'The ID of the customer field [configured](https://docs.antavo.com/docs/customers#add-a-new-field)
                az external_id.

                The `crm_id` property name is shown as an example. The list of external ids returned depend
                on the fields configured in the workspace.

                '
              example: 1749RRCT23
          example:
            crm_id: 1749RRCT23
        email:
          type: string
          description: Customer's email address.
          example: jsmith@example.com
        first_name:
          type: string
          description: Customer's first name.
          example: John
        last_name:
          type: string
          description: Customer's last name.
          example: Smith
        handler:
          type: string
          description: Nickname displayed on the customer's profile.
          example: John
        status:
          description: 'The current loyalty program status of the customer.

            Customers with an `opted_out` status are not returned by the API.

            '
          type: string
          enum:
          - active
          - inactive
          - banned
          - merged
          - suspended
          example: active
        gender:
          type: string
          description: Customer's gender.
          enum:
          - male
          - female
          example: male
        language:
          type: string
          description: Customer language code (ISO-639-1 format).
          example: en
        image_url:
          description: The URL of the customer profile picture, if available.
          type: string
          example: https://example.com/image.png
        currency:
          type: string
          description: The ISO 3-Letter Currency Code for the last currency used.
          example: GBP
        mobile_phone:
          type: string
          description: The member's mobile phone number.
          example: 123 456 789
        country:
          type: string
          description: The ISO 3166-1 alpha-2 country code associated with the customer.
          example: GB
        membership_id:
          type: array
          description: A unique identifier for membership, used across platforms including mobile apps.
            This ID may function as a range of IDs in specific contexts.
          items:
            type: string
          example:
          - MA465927t85w
          - DA465927t85w
        group_id:
          type: array
          description: 'The IDs of the user groups assigned to the customer.

            Returned only when the customer is assigned to at least one user group.

            '
          items:
            type: string
          example:
          - '146'
          - '126'
        src:
          type: string
          description: 'The source through which the customer was created. For customers created

            through an import, the value contains the import ID.

            '
          example: import:672b564c4219e3a65b0f43a0
        referrer:
          type: string
          description: 'The unique account ID of the customer who referred the member to the loyalty program.

            Returned only when the customer has a referrer.

            '
          example: 557e5d4eg2cf1461e688b45e8
        score:
          description: The total number of points ever earned by the customer.
          type: number
          example: 100
        spent:
          description: The points spent by the customer.
          type: number
          example: 20
        reserved:
          description: The amount of points reserved on bids or discounts.
          type: number
          example: 0
        expired:
          description: The number of points expired.
          type: number
          example: 100
        pending:
          description: The number of pending points for non-finalized actions. Typically given when the
            purchase is in its refund/return period.
          type: number
          example: 20
        purchase_total:
          description: 'The money spent on purchases by the customer since enrolling into the program.

            Can be `null` or omitted when the customer has no recorded purchases.

            '
          type: number
          example: 100
        purchase_count:
          description: 'The number of purchases made by the customer since enrolling into the program.

            Can be `null` or omitted when the customer has no recorded purchases.

            '
          type: integer
          example: 1
        purchase_item_count:
          description: 'The number of items purchased since enrolling into the program.

            Can be `null` or omitted when the customer has no recorded purchases.

            '
          type: integer
          example: 2
        created_at:
          description: The date and time when the customer was created.
          type: string
          format: date-time
          example: '2026-07-14T19:41:35+00:00'
        updated_at:
          description: The date and time when the customer data was last updated.
          type: string
          format: date-time
          example: '2026-07-14T19:41:35+00:00'
        birth_date:
          type: string
          pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
          description: Customer's date of birth.
          format: date
          example: '1969-12-25'
        purchase_first_date:
          type: string
          description: 'First time the customer made a purchase since enrolling into the program.

            Can be `null` or omitted when the customer has no recorded purchases.

            '
          format: date
          pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
          example: '2020-10-01'
        purchase_last_date:
          type: string
          description: 'Last time the customer made a purchase since enrolling into the program.

            Can be `null` or omitted when the customer has no recorded purchases.

            '
          format: date
          pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
          example: '2020-10-01'
        last_earn_date:
          type: string
          description: 'Last time the customer earned points since enrolling into the program.

            Omitted if the customer has not been earned yet.

            '
          format: date
          pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
          example: '2026-04-27'
        last_spend_date:
          type: string
          description: 'Last time the customer spent points since enrolling into the program.

            Omitted if the customer has not spent yet.

            '
          format: date
          pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
          example: '2025-10-28'
        last_login_at:
          description: The date of the last login of the customer.
          type: string
          format: date-time
          example: '2026-06-28T10:27:03+00:00'
        optin_at:
          description: The date of the enrollment of the customer.
          type: string
          format: date-time
          example: '2026-06-28T10:27:03+00:00'
        optout_at:
          description: 'The date when the customer was unenrolled.

            Omitted if the customer has not been opted-out.

            '
          type: string
          format: date-time
          example: '2026-06-28T10:27:03+00:00'
        labels:
          type: array
          items:
            type: string
          description: 'Labels associated with the customer.

            Can be empty or omitted when the customer has no recorded purchases.

            '
          example:
          - Elite member
          - Frequent flyer
        properties:
          type: object
          description: '[Custom attributes](https://developers.antavo.com/docs/customers#attribute-types)
            that are stored on the customer object.

            The `city` property name is shown as an example. The custom attributes returned depend on
            the fields configured in the workspace.

            '
          properties:
            city:
              type: string
              example: London
        tiers:
          type: object
          description: 'The customer''s current tier information within tier structures.

            Only available is the Tiers module is used.

            '
          properties:
            fashion_tiers:
              type: object
              description: 'Tier information for a specific tier structure.

                The `fashion_tiers` property name is shown as an example of a tier structure ID. The list
                of tier strucures returned depend on the Tiers module configuration in the workspace.

                '
              properties:
                history:
                  type: object
                  description: Historical tier point values keyed by date.
                  additionalProperties:
                    type: number
                  example:
                    '2025-06-24': 1010
                points:
                  type: number
                  description: The number of points currently used to determine the customer's tier.
                  example: 1010
                next:
                  $ref: '#/components/schemas/NextCustomerTier'
                points_after_expiration:
                  type: number
                  description: The number of tier points remaining after the next point expiration.
                  example: 1010
                _id:
                  type: string
                  description: The ID of the customer's current tier.
                  example: Couture_Elite
                event:
                  type: string
                  description: The ID of the event associated with the customer's current tier assignment.
                  example: 685a9c5abe38329c6501bf87
                expdate:
                  type: string
                  format: date
                  description: The date when the tier expires and the customers' tier is recalculated.
                  example: '2025-06-30'
                manual:
                  type: boolean
                  description: Indicates whether the customer was manually assigned to the current tier
                    by a Management UI user.
                  example: false
                name:
                  description: The customer-facing name of the current tier.
                  oneOf:
                  - type: string
                  - type: object
                    additionalProperties:
                      type: string
                  example:
                    en: 

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antavo/refs/heads/main/openapi/antavo-loyalty-read-openapi.yml