The Bulk Operations API consists of the Bulk Reward claim API, Bulk Customer list API and Bulk Coupon API endpoints. These APIs offer a comprehensive solution for managing large-scale operations within the Antavo Loyalty Engine.

For both APIs, once the batch requests have been submitted, the batches are queued and processed asynchronously one after the other. After the batch has been added to the queue, the /status endpoint provides information about the status of the process, which may be:

Queued: The batch has been added to the queue.
Processing: the batch is being processed.
Done: The batch processing is completed, and the result is available.

The /error endpoint can query the errors that may have occurred during the process. The endpoint provides a paginated list of erroneous reward claims, customer lists, or coupon operation attempts.

This document helps you understand how to work with the endpoints when executing bulk reward claims, bulk customer list operations, and bulk coupon management through the Antavo Loyalty Engine.

Endpoints Overview

Rewards

The Bulk Reward Claim API handles bulk operations for distributing rewards to multiple customers.

It enables you to distribute coupon rewards to a large number of customers.

The benefit of using the Bulk Reward claim API over the Reward claim endpoint of the Display API is that it enables the assignment of a reward to a large number of customers in one process.

Each batch claim request should include customers who should receive one of the coupon rewards configured under the Rewards module with a coupon pool assigned. The request may also include custom data that Antavo can forward to an endpoint (callback_url) via a webhook message.

A bulk-operation cron job task must be manually set up to process the submitted bulk reward claim requests. Once a request is processed, a reward event is registered for each customer specified in the request.

Customer Lists

The Bulk Customer List API enables you to efficiently add or remove a group of customers from a customer list.

This API can be used to synchronize customer segments from CDP, CRM platforms, and other customer repositories without the need to synchronize all the data attributes from the source systems to Antavo.

Each request should include the ID of the customer list where customers should be added or removed, as well as the IDs of the specific customers.

A bulk-operation-customer-list cron job task must be manually set up to process the submitted requests to add or remove customers from a customer list. Multiple requests to update the same customer list are processed asynchronously, and a customer_list_customer_add or a customer_list_customer_remove event is registered accordingly for each customer specified in the request.

Coupons

The Bulk Coupons API facilitates bulk operations for managing coupon codes within coupon pools. This API enables users to upload, assign, and unassign coupon codes for a large number of customers efficiently, processing up to 50,000 coupon codes in a single request.

The use of the endpoints offers significant advantages over individual coupon management endpoints, as it allows for streamlined operations when handling large volumes of coupons simultaneously. Each batch request must specify the coupon pool and the corresponding action.

To process submitted coupon operations, a cron job named coupon-pool-bulk-operation-upload must be manually set up. Once processed, relevant events (coupon_assign, coupon_unassign) and coupon statuses will be registered for each coupon operation performed.

API Principles

The Bulk Operations 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 security protocol and signing procedure and adhere to the defined API rate limits.