The Async Events API is used to record events in Antavo asynchronously, allowing events to be accepted quickly and processed in the background.

Unlike the synchronous Events API, this API is designed for high-throughput and peak-load scenarios, where immediate processing is not required, but reliable delivery and tracking are critical.

The Async Events API is useful when:

A large number of events need to be sent in a short period of time (for example, during campaigns, promotions, or data imports)
The client application must not wait for event processing to complete
Temporary traffic spikes should not impact system stability
Event submission reliability is more important than immediate feedback

When an event is submitted, the API immediately acknowledges the submission and returns a correlation ID, which can later be used to track the processing result.

Event compatibility

The Async Events API supports the following events:

point_add
checkout
checkout_item
checkout_update
checkout_update_item
checkout_accept
checkout_accept_item
checkout_reject
partial_refund
refund_item
refund
opt_in
opt_out
profile

The corresponding attributes of the events can be found on the Events page.

Endpoints

Submitting events asynchronously

The Async Events API supports single event submission.

POST /v1/async/events: Submits a single event for asynchronous processing. Only one event can be submitted per request. Each request is processed independently and tracked using a correlation ID.

❗️
Important
The order in which events are submitted is important. The API expects events to be sent in the correct sequence, and the system guarantees that events are processed in the order they were received.
You must wait for a successful acknowledgment from the API (HTTP 200 OK) before sending the next event in the sequence. For example:

After an opt_in event is accepted, only then should a checkout event be sent.

After a checkout event is processed, the corresponding checkout_accept can be submitted.

Ensuring proper ordering allows the Loyalty Engine to correctly apply loyalty program rules and maintain accurate customer state.

Tracking event processing

Since events are processed asynchronously, the final processing result is not returned immediately.

GET /v1/async/events/{correlation_id}: Retrieves the processing status and result of a previously submitted event.

Using the correlation ID, you can:

Check whether the event has been processed
Retrieve the full customer information and detailed event data once processing is complete
Inspect error details if processing failed

This makes it possible to build reliable retry, monitoring, or audit mechanisms on the client side.

Callback mechanism

The Async Events API supports an optional callback mechanism that allows your system to receive the processing result of an asynchronous event without polling the correlation endpoint.

If a callback_url is provided when submitting an event via the Async Events API, Antavo will send the processing result to the specified URL once the event has been handled. The callback request references the original submission using the correlation_id.

The callback_url must be configured as a Trusted Site in the Management UI. The callback request has a timeout of 1 second. If you need a longer timeout, please contact the Antavo Service Desk.

Success payload

{
  "status": "success",
  "payload": {
    "correlation_id": "62cc313988befe60e3413e75",
    "status": "success",
    "processed_at": "2025-10-16T15:29:41+02:00"
  }
}

Error payload

{
  "status": "success",
  "payload": {
    "correlation_id": "62cc313988befe60e3413e75",
    "status": "error",
    "processed_at": "2025-10-16T15:29:41+02:00",
    "error": {
      "code": 123456,
      "message": "Transaction not found."
    }
  }
}

Dead-Letter Queues (DLQs)

The Async Events API provides two separate Dead-Letter Queues: one for events and one for callbacks. These queues store messages that could not be processed or delivered successfully, allowing manual inspection, retry, or export via the Management UI.

The Events DLQ stores events that were successfully enqueued but failed processing after 5 retry attempts.
The Callback DLQ stores callback requests that could not be delivered to the callback_url within the configured timeout.

For detailed instructions on managing both DLQs, see the Management UI user manual.

Submission-based timestamping

Each asynchronous event sent through the /v1/async/events endpoint is recorded using the time it is submitted to the system, regardless of when it is queued or processed. This ensures that the event is evaluated according to the loyalty program configuration active at the time of submission, not any subsequent changes. The date, timestamp, and effective_timestamp attributes on the event are all set to the submission time by default.

The endpoint also supports backdating. Optionally, the event payload can include an effective_timestamp to register the event as occurring at a past time. If provided, the event is stored as if it happened at the specified timestamp. If no effective_timestamp is provided in the request, the submission time is automatically used.

API principles

The Async Events API follows RESTful principles, utilizing standard HTTP methods to interact with resources. All responses are formatted in JSON, ensuring easy integration into user interfaces.

Security and compliance

All server-to-server calls must comply with the API authentication requirements and adhere to the defined API rate limits.

The Async Events API uses Bearer token authentication, with access tokens issued by the /v1/auth/token endpoint of the Authentication API.