Antavo Events API

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.
         

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