About Async Events API

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.

• 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.