Records customer interactions from e-commerce, POS, websites, and mobile apps as loyalty events (for example point_add, checkout_accept), driving the rules and workflows of the loyalty program. Supports single and bulk event submission and reading a customer's event history.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/antavo-events-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.0.0
info:
contact:
email: support@antavo.com
title: Antavo Events API
version: 1.0.0.0
servers:
- url: https://api.staging.antavo.com
description: The Antavo staging environment
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
/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
components:
schemas:
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).
events_bulkrequest:
title: Bulk request
required:
- events
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/Event'
description: ''
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.
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.
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'
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).
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_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
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'
securitySchemes:
api_key:
type: apiKey
description: ''
name: api_key
in: query
security:
- api_key: []