openapi: 3.2.0
info:
  title: Antavo Events API
  version: '1.0'
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: antavo-events-openapi.yml, antavo-loyalty-read-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.staging.antavo.com
  description: The Antavo staging environment
- url: https://read-api.<environment>.antavo.com
tags:
- name: Events
paths:
  /events/bulk:
    post:
      tags:
      - Events
      summary: Submit multiple Antavo events in a single request
      description: "Use this endpoint to submit multiple events within a single API request. Events are processed individually and synchronously. \n\nExamples of event submissions:\n\n- **Standard event submission**: Submit events for the customers without any additional identifiers.\n- **Event submission with an external ID**: Include the `external_id` attribute to link the events with external identifiers of customers from another system or database.\n- **Event submission with multiple accounts**: Specify multiple accounts by including their IDs in the `account` attribute. This requires the Points economy module to be enabled.<br>\n*Note*: if no account is specified, the events will be assigned to the default account.\n\nThe response will include a success message or an error for each event in the order they were submitted. An error code is only returned if the entire request is invalid, not for errors related to individual event submissions.\n\n> **Note**\n> This endpoint is **not compatible with guest checkout**. Guest checkout events must be submitted individually via the `/events` endpoint using `\"guest\": \"true\"`, and later linked to a member with the `checkout_claim` event.  \n"
      operationId: bulk
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/events_bulkrequest'
            examples:
              Standard:
                value:
                  events:
                  - customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    action: point_add
                    data:
                      points: 325
                  - customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    action: point_sub
                    data:
                      points: 35
              External ID:
                value:
                  events:
                  - customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    action: point_add
                    account: main_account
                    data:
                      points: 325
                  - customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    external_id: ASeab0cbaa181a
                    action: point_sub
                    account: main_account
                    data:
                      points: 35
              Multi-accounts:
                value:
                  events:
                  - customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    action: point_add
                    account: main_account
                    data:
                      points: 145
                  - customer: '001'
                    action: point_sub
                    account: main_account
                    data:
                      points: 35
        required: true
      responses:
        '200':
          description: 'A 200 success response means the request was submitted successfully, not the processing of each event.

            This example shows two point manipulation events submitted in one API request. Responses are returned in the order of submission. The first event includes an error to demonstrate the error response format. This response format is only valid for point_add/point_sub events.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bulk_Event_response'
              example:
                results:
                - error:
                    type: InterruptException
                    code: 127201
                    message: Workflow interruption
                - events:
                  - id: 667c850e8ca0cb5f6e0abe03
                    action: point_add
                    points: 325
                total: 2
                errors: 1
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /events:
    post:
      tags:
      - Events
      summary: Submit an Antavo event
      description: 'Use this endpoint to submit a single event for a specified customer. The attributes provided in the data object are examples of `point_add` and `checkout` events. Refer to the [complete list of events](/docs/api-events) for all available actions and their attributes.


        Examples of event submission:


        - **Standard event submission**: Submit an event for the customer without any additional identifiers.

        - **Event submission with an external ID**: Include the `external_id` attribute to link the event with an external identifier of the customer from another system or database.

        - **Event submission with multiple accounts**: Specify multiple accounts by including their IDs in the ''account'' attribute. This requires the Points economy module to be enabled.<br>

        *Note*: if no account is specified, the event will be assigned to the default account.

        '
      operationId: events
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/PointAddRequestBody'
              - $ref: '#/components/schemas/CheckoutRequestBody'
            examples:
              Point add Standard:
                value:
                  customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                  action: point_add
                  data:
                    points: 325
              Point add with External ID:
                value:
                  customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                  action: point_add
                  external_id: ASeab0cbaa181a
                  data:
                    points: 325
              Point add with Multi-accounts:
                value:
                  customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                  action: point_add
                  account: main_account
                  data:
                    points: 325
              Checkout Standard:
                value:
                  customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                  action: cehckout
                  data:
                    transaction_id: 64b647cd257f93741550d3e4
                    total: 100
                    total_quantity: 1
                    currency: EUR
                    points_burned: 0
                    items:
                    - product_id: prd_987654
                      product_name: Vintage Leather Jacket
                      product_url: https://example.com/products/vintage-leather-jacket
                      price: 100
                      quantity: 1
                      discount: 0
                      subtotal: 50
              Checkout with External ID:
                value:
                  customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                  action: checkout
                  external_id: ASeab0cbaa181a
                  data:
                    transaction_id: 64b647cd257f93741550d3e4
                    total: 100
                    total_quantity: 1
                    currency: EUR
                    points_burned: 0
                    items:
                    - product_id: prd_987654
                      product_name: Vintage Leather Jacket
                      product_url: https://example.com/products/vintage-leather-jacket
                      price: 100
                      quantity: 1
                      discount: 0
                      subtotal: 50
              Checkout withMulti-accounts:
                value:
                  customer: 280e674c-c4ea-4a30-987a-d9267d1a5018
                  action: checkout
                  account: main_account
                  data:
                    transaction_id: 64b647cd257f93741550d3e4
                    total: 100
                    total_quantity: 1
                    currency: EUR
                    points_burned: 0
                    items:
                    - product_id: prd_987654
                      product_name: Vintage Leather Jacket
                      product_url: https://example.com/products/vintage-leather-jacket
                      price: 100
                      quantity: 1
                      discount: 0
                      subtotal: 50
      responses:
        '200':
          description: "A successful event submission returns a customer object. \nThe events field will only include events that directly modify spendable points (e.g., no events will be returned for processes involving pending points).\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event_response'
              examples:
                point_add event response:
                  value:
                    id: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    created_at: '2024-01-01T00:00:00Z'
                    handler: John
                    status: active
                    score: 100
                    spent: 50
                    pending: 10
                    language: en
                    currency: USD
                    first_name: John
                    last_name: Doe
                    email: john.doe@example.com
                    events:
                    - id: 667c850e8ca0cb5f6e0abe03
                      action: point_add
                      points: 325
                      expdate: '2024-12-01'
                      account:
                        id: main_account
                        name: Main Account
                checkout response per transaction:
                  value:
                    id: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    created_at: '2024-01-01T00:00:00Z'
                    handler: John
                    status: active
                    score: 100
                    spent: 50
                    pending: 10
                    language: en
                    currency: USD
                    first_name: John
                    last_name: Doe
                    email: john.doe@example.com
                    events:
                    - id: 67349428fb18e9b3ec0062d4
                      action: checkout
                      points: 100
                      expdate: '2024-12-01'
                      account:
                        id: main_account
                        name: Main Account
                checkout response per item:
                  value:
                    id: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    created_at: '2024-01-01T00:00:00Z'
                    handler: John
                    status: active
                    score: 100
                    spent: 50
                    pending: 10
                    language: en
                    currency: USD
                    first_name: John
                    last_name: Doe
                    email: john.doe@example.com
                    events:
                    - id: 67349428fb18e9b3ec0067y4
                      action: checkout_item
                      points: 50
                      expdate: '2024-12-01'
                      account:
                        id: main_account
                        name: Main Account
                    - id: 67349428fb18e9b3ec0064s4
                      action: checkout_item
                      points: 50
                      expdate: '2024-12-01'
                      account:
                        id: main_account
                        name: Main Account
                checkout response with pending period:
                  value:
                    id: 280e674c-c4ea-4a30-987a-d9267d1a5018
                    created_at: '2024-01-01T00:00:00Z'
                    handler: John
                    status: active
                    score: 100
                    spent: 50
                    pending: 10
                    language: en
                    currency: USD
                    first_name: John
                    last_name: Doe
                    email: john.doe@example.com
                    events: []
        '404':
          description: Customer or contest not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Customer not found:
                  value:
                    type: NotFoundException
                    code: 160212
                    message: Customer not found
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /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'
    servers:
    - url: https://read-api.<environment>.antavo.com
components:
  schemas:
    PointAddRequestBody:
      title: Point add event request
      required:
      - customer
      - action
      - data
      type: object
      properties:
        customer:
          type: string
          description: The unique ID of the customer.
        external_id:
          type: string
          description: The external ID of the customer. This is only required for external ID lookup.
          example: ext_001
        action:
          type: string
          description: The corresponding event action. For a complete list of available actions, please visit full list of events.
          enum:
          - point_add
          example: point_add
        account:
          type: string
          description: The unique ID of the account. This is only required for multi-accounts.
          example: main_account
        data:
          $ref: '#/components/schemas/PointAddData'
    CheckoutRequestBody:
      title: Checkout event request
      required:
      - customer
      - action
      - data
      type: object
      properties:
        customer:
          type: string
          description: The unique ID of the customer.
        external_id:
          type: string
          description: The external ID of the customer. This is only required for external ID lookup.
          example: ext_001
        action:
          type: string
          description: The corresponding event action. For a complete list of available actions, please visit full list of events.
          enum:
          - checkout
          example: checkout
        account:
          type: string
          description: The unique ID of the account. This is only required for multi-accounts.
          example: main_account
        data:
          $ref: '#/components/schemas/CheckoutData'
    Bulk_Event_response:
      type: object
      properties:
        results:
          description: Array of event processing results.
          $ref: '#/components/schemas/results'
        total:
          type: integer
          description: Number of events submitted.
          example: 2
        errors:
          type: integer
          description: Number of erroneous entries.
          example: 0
    results:
      type: array
      description: Array of event processing results.
      items:
        type: object
        properties:
          error:
            type: object
            description: Array of errors occurred while events were processed.
            properties:
              type:
                type: string
                description: Type of the error.
              code:
                type: number
                description: Error code.
              message:
                type: string
                description: Human-readable error message.
          events:
            type: object
            description: Array of events related to the customer. This section, along with all the attributes listed below, only appears if the event changes the customer’s point balance.
            properties:
              id:
                type: string
                description: ID of the event.
              action:
                type: string
                description: The event action.
              points:
                type: number
                description: Number of points involved in the event.
    PointAddData:
      title: data
      required:
      - points
      type: object
      properties:
        points:
          type: integer
          format: int32
          description: Number of points to be added or subtracted.
        effective_timestamp:
          type: number
          description: Unix timestamp representing the original occurrence time of the event, allowing it to be recorded as [backdated](/docs/actions-and-events#/backdated-event-registration).
    Event_response:
      type: object
      description: Submitting an Event
      properties:
        id:
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
          description: Unique identifier of the customer.
        created_at:
          example: '2024-01-01T00:00:00Z'
          description: Timestamp of when the event was created.
        handler:
          example: Sally
          description: Handler of the customer.
        status:
          example: active
          description: Membership status.
        score:
          example: 100
          description: The member's total point balance after processing the event.
        spent:
          example: 50
          description: The member’s total points spent balance after processing the event.
        pending:
          example: 10
          description: The member’s total pending points balance after processing the event.
        language:
          example: en
          description: Language of the customer.
        currency:
          example: USD
          description: Currency associated with the customer.
        first_name:
          example: John
          description: First name of the customer.
        last_name:
          example: Doe
          description: Last name of the customer.
        email:
          example: john.doe@example.com
          description: Email address of the customer.
        events:
          type: array
          description: Array of events related to the customer. This section, along with all the attributes listed below, only appears if the event changes the customer's point balance.
          items:
            type: object
            properties:
              id:
                example: 667c850e8ca0cb5f6e0abe03
                description: Unique identifier of the event.
              action:
                example: point_add
                description: Action associated with the related event.
              points:
                example: 325
                description: Number of points added in the related event.
              expdate:
                description: Expiration date for the points added, if there is any.
                example: '2024-12-31T23:59:59Z'
              account:
                type: object
                description: Account information for the related event.
                properties:
                  id:
                    description: Unique identifier for the account.
                    example: main_account
                  name:
                    description: Name of the account.
                    example: Main Account
    CheckoutData:
      title: data
      required:
      - transaction_id
      type: object
      properties:
        transaction_id:
          type: string
          example: 64b647cd257f93741550d3e4
        effective_timestamp:
          type: number
          description: Unix timestamp representing the original occurrence time of the event, allowing it to be recorded as [backdated](/docs/actions-and-events#/backdated-event-registration).
        total:
          type: number
          description: This attribute is required if purchases are rewarded on the transaction level.
          example: 100
        total_quantity:
          type: number
          example: 1
        currency:
          type: string
          example: EUR
        points_burned:
          type: number
          example: 0
        items:
          type: array
          description: This attribute is required if purchases are rewarded on the item level.
          properties:
            product_id:
              type: string
              example: prd_987654
            product_name:
              type: string
              example: Vintage Leather Jacket
            product_url:
              type: string
              example: https://example.com/products/vintage-leather-jacket
            price:
              type: number
              example: 100
            quantity:
              type: number
              example: 1
            discount:
              type: number
              example: 0
            subtotal:
              type: number
              example: 50
            points_rewarded:
              type: number
    Event:
      title: Event
      required:
      - customer
      - action
      - data
      type: object
      properties:
        customer:
          type: string
          description: The target customer.
        action:
          type: string
          description: The corresponding event action. For a complete list of available actions, please visit full list of events.
        account:
          type: string
          description: The unique ID of the account. This is only required for multi-accounts.
          example: main_account
        data:
          $ref: '#/components/schemas/Data'
          description: Additional data related to the event.
    events_bulkrequest:
      title: Bulk request
      required:
      - events
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: ''
    Data:
      title: data
      description: Refer to the [complete list of events](/docs/api-events) for the data attributes to be sent with each action.
      required:
      - points
      type: object
      properties:
        points:
          type: integer
          format: int32
          description: Number of points to be added or subtracted.
        effective_timestamp:
          type: number
          description: Unix timestamp representing the original occurrence time of the event, allowing it to be recorded as [backdated](/docs/actions-and-events#/backdated-event-registration).
    ErrorResponse:
      type: object
      description: This describes the structure returned if an error occurred
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          properties:
            type:
              type: string
              description: Type of the error occurred.
              example: BadRequestException
            code:
              type: number
              description: Error code.
              example: 113401
            message:
              type: string
              description: Human readable error message
              example: Missing required parameter 'parameter_name'
    PaginationLinks:
      type: object
      required:
      - next
      - previous
      properties:
        next:
          type:
          - string
          - 'null'
          description: URL of the next page, or null if this is the last page.
        previous:
          type:
          - string
          - 'null'
          description: URL of the previous page, or null if this is the first page.
    EventEntity:
      type: object
      description: 'An event registered for the customer. The fields returned depend on the

        event type and how the event was registered.

        '
      properties:
        _id:
          type: string
          description: The unique ID of the event.
          example: 6a57a9681d81297bdc042a6e
        timestamp:
          type: string
          format: date-time
          description: The date and time when the event occurred.
          example: '2026-06-13T15:38:16+00:00'
        unix_timestamp:
          type: integer
          format: int64
          description: The time when the event occurred, represented as a Unix timestamp in seconds.
          example: 1784131896
        process_timestamp:
          type: string
          format: date-time
          description: The date and time when the event was processed by Antavo.
          example: '2026-06-13T15:38:16+00:00'
        date:
          type: string
          format: date
          description: The date when the event occurred.
          example: '2026-06-13'
        ip_address:
          type: string
          description: The IP address from which the event was registered.
          example: 87.97.9.123
        user_agent:
          type: string
          description: The user agent associated with the event request.
          example: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
        customer:
          type: string
          description: The ID of the customer associated with the event.
          example: 55e5d4dc2cf1901e688b45d3
        action:
          type: string
          description: Event type.
          example: checkout
        points:
          type: number
          description: The number of points added or deducted by the event.
          example: 60
        properties:
          type: object
          description: 'The properties registered with the event. The properties returned depend

            on the event type and the fields configured for the event.

            The example response includes `checkout`, `checkout_item`, and `point_add` events with their registered properties.

            '
          example:
            transaction_id: txn_8f3c2a91d7b64e5a
            total: 119.996
            points_burned: 0
            currency: GBP
        parent:
          type: string
          description: 'The ID of the parent event. Returned when the event is associated with

            another event, such as a `checkout_item` associated with a `checkout`.

            '
          example: 6a57a9681d81297bdc042a6e
        change:
          type: object
          description: 'Information about a change applied to the event.

            For example, a change may occur when the event expiration date is modified in the Management UI.

            '
          properties:
            id:
              type: string
              description: The ID of the original event before the change was applied.
              example: 6a57a9681d81297bdc042a6f
            at:
              type: string
              format: date-time
              description: The date and time when the event was changed.
              example: '2026-06-13T19:09:26+00:00'
            by:
              type: string
              description: The ID of the user who initiated the change.
              example: '100012233'
        admin:
          type: boolean
          description: 'Indicates whether the event was registered through the Management UI.

            The value is `true` for events registered through the Management UI and `false` for events registered through an API or another system process.

            '
          example: false
        hash:
          type: string
          description: 'An automatically generated hash for uniqueness checks.

            '
          example: checkout-txn_8f3c2a91d7b64e5a
        user_id:
          type: integer
          format: int64
          description: 'The ID of the Management UI user associated with the event.

            Returned only when the event was initiated by a Management UI user.

            '
          example: 100012233
        signed:
          type: boolean
          description: Indicates whether the API request that registered the event was authenticated using request signing.
          example: false
        expdate:
          type: string
          format: date
          description: 'The expiration date of the points earned by the event.

            Returned only when the event earns points that can expire.

            '
          example: '2026-07-16'
        source:
          type: string
          description: 'Identifies the channel or system process through which the event was registered.

            The value may indicate an API, an workflow, an import, or the manual or module operation that generated the event.

            '
          example: Events API
        account:
          type: string
          description: The ID of the point account affected by the event.
          example: family_account
        cid:
          type: string
          description: 'The correlation ID shared by related events registered as part of the same operation.

            '
          example: 5098a0ea-70e1-8c3b-4e4b-ac585cb9fed2
        snapshot:
          type: object
          description: The customer's point balances immediately after the event was processed.
          properties:
            score:
              type: number
              description: The customer's total earned point balance.
              example: 34749
            spent:
              type: number
              description: The customer's total spent point balance.
              example: 12167
            pending:
              type: number
              description: The customer's pending point balance.
              example: 34521
            expired:
              type: number
              description: The customer's total expired point balance.
              example: 0
        usages:
          type: object
          description: 'Shows how points earned by this event were used. Each property is keyed

            by the ID of the event that used the points, and its value is the number

            of points applied to that event.

            Omitted if no points have been used.

            '
          additionalProperties:
            type: number
          example:
            652f9bad5924e77e8269be13: 100
        used_points:
          type: number
          description: 'The total number of points earned by this event that have already been used.

            Omitted if no points have been used.

            '
          example: 100
        expired:
          type: boolean
          description: 'Indicates whether the points earned by the event are no longer available

            for use because they have been fully used or have expired.

            '
          example: true
        original:
          type: string
          description: 'The ID of the customer from whom the event was transferred during a customer merge.

            Returned only for events transferred from a merged customer.

            '
          example: 6a57a9681d81297bdc042a6f
    CollectionMetadata:
      type: object
      required:
      - pagination
      properties:
        pagination:
          description: Links to the next and previous pages of the result set.
          $ref: '#/components/schemas/PaginationLinks'
    CustomerEventSortEntry:
      type: object
      description: Defines a single sorting instruction by specifying the field and direction.
      required:
      - field
      - direction
      properties:
        field:
          type: string
          description: The field used to sort the results.
          enum:
          - action
          - date
          - account
          - points
          - expdate
        direction:
          $ref: '#/components/schemas/SortDirection'
    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
    EventsFilter:
      type: object
      description: 'Filter by allowed fields and operators.

        '
      properties:
        action:
          type: object
          description: 'Filters events by the event type recorded in the `action` property. The comparison operators compare values alphabetically.

            '
          properties:
            eq:
              type: string
              description: Equals.
            lt:
              type: string
              description: Less than.
            lte:
              type: string
              description: Less than or equal to.
            gt:
              type: string
              description: Greater than.
            gte:
              type: string
              description: Greater than or equal to.
        date:
          type: object
          description: 'Filters events by the date when the event occurred, as recorded in the `date` property. The comparison operators compare values alphabetically.

            Typed as string values (as shown in the example response) even though they are date-like in storage.

            '
          properties:
            eq:
              type: string
              description: Equals.
            lt:
              type: string
              description: Less than.
            lte:
              type: string
              description: Less than or equal to.
            gt:
              type: string
              description: Greater than.
            gte:
              type: string
              description: Greater than or equal to.
        account:
          type: object
          description: 'Filters events by the ID of the point account associated with the event. The comparison operators compare values alphabetically.

            '
          properties:
            eq:
              type: string
              description: Equals.
            lt:
              type: string
              description: Less than.
            lte:
              type: string
              description: Less than or equal to.
            gt:
              type: string
              description: Greater than.
            gte:
              type: string
              description: Greater than or equal to.
        points:
          type: object
          description: 'Filters events by the number of points assigned to the event. Only whole numbers are accepted, decimal values return a `422` error.

            '
          properties:
            eq:
              type: integer
              description: Equals.
            lt:
              type: integer
              description: Less than.
            lte:
              type: integer
              description: Less than or equal to.
            gt:
              type: integer
              description: Greater than.
            gte:
              type: integer
              description: Greater than or equal to.
        expdate:
          type: object
          description: 'Filters events by the date when the points earned by the event expire, as recorded in the `expdate` property. The comparison operators compare values alphabetically.

            Typed as string values (as shown in the example response) even though they are date-like in storage.

            '
          properties:
            eq:
              type: string
              description: Equals.
            lt:
              type: string
              description: Less than.
            lte:
              type: string
              description: Less than or equal to.
            gt:
              type: string
              description: Greater than.
            gte:
              type: string
              description: Greater than or equal to.
    SortDirection:
      type: string
      enum:
      - asc
      - desc
  parameters:
    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
    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
    CustomerIdParam:
      name: customer_id
      in: path
      required: true
      description: Customer identifier. Using an external ID is not supported.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Error - Escher signature missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServerError:
      description: Error - Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ValidationError:
      description: Error - Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    api_key:
      type: apiKey
      description: ''
      name: api_key
      in: query
x-refined-from:
- antavo-events-openapi.yml
- antavo-loyalty-read-openapi.yml