Introduction
Our loyalty API is a powerful tool that allows you to seamlessly integrate loyalty programs into your applications. This documentation provides a comprehensive overview of the endpoints you'll use to manage customer data, display loyalty tiers, and handle the entire program application lifecycle.
By leveraging these endpoints, you can create a smooth and intuitive loyalty experience for your users. You can enable them to:
- View their loyalty status and wallet balance in real-time.
- Discover and apply loyalty programs that are relevant to their orders.
- Enjoy automatic point redemption when they make a purchase.
The following sections will guide you through each part of the loyalty API, from managing customer profiles to handling the final stages of program redemption.
Simplified Loyalty Journey Flow
Configuration Endpoints
| ENDPOINT | TYPE | FUNCTION |
|---|---|---|
| Get configuration 🔗 | GET | Returns information on the current loyalty configuration. |
Customer Management Endpoints
The following endpoints are available for managing customer information and loyalty data.
| Endpoint | Method | Purpose |
|---|---|---|
| Create customer 🔗 | POST | This endpoint is used to create a customer profile. It allows a channel to send customer information (such as name, email, and phone number) to the loyalty provider. |
| Get customer 🔗 | GET | This endpoint is used to retrieve a customer's profile details. A channel can call this endpoint to fetch a customer's information, including their loyalty customer ID and other relevant profile data. This is essential for subsequent API calls that require the customer's unique loyalty ID. |
Tier System Endpoint
The tier system allows loyalty providers to define and manage customer loyalty tiers based on criteria such as lifetime points. Channels can use the following endpoint to retrieve a list of all available tiers and their requirements, enabling them to display a customer's progress and the benefits of reaching higher tiers.
| Endpoint | Method | Purpose |
|---|---|---|
| Get loyalty tiers 🔗 | GET | This endpoint is used to retrieve a list of all available loyalty tiers. The response includes details about each tier, such as its name, a description, and the point requirements to achieve it. This information is valuable for building a user interface that visualizes a customer's current tier status and motivates them to earn more points to reach the next level. |
Wallet Application Lifecycle
| Endpoint | Method | Purpose |
|---|---|---|
| Get customer wallet 🔗 | GET | This endpoint is used to retrieve a customer's wallet balance. It provides the channel with the customer's available funds in the form of cash and/or loyalty points. This allows the channel to display the customer's current balance, enabling them to make informed decisions about using their rewards. This endpoint is crucial for functionalities such as "pay with points" or showing a customer's current points balance on the application's user interface. |
| Validate Wallet Application 🔗 | POST | This webhook is initiated by our system to validate a customer's request to use cash or points from their loyalty wallet as a discount on a current order. Your system, as the loyalty provider, is responsible for performing the necessary business rule checks and returning the discount amount and type. |
Program Application Lifecycle
During the program application lifecycle, you will need to provide a sessionId, which is a unique token that you generate and maintain to link all customer actions throughout the loyalty program lifecycle.
You must provide the same sessionId for all calls to get programs, validate programs, and the create order request. Using a consistent sessionId ensures a single, continuous customer journey is followed, which helps loyalty partners prevent fraudulent activity.
Once the customer has placed the order, the session is considered complete. The sessionId used during that process should no longer be used for new loyalty interactions.
| Endpoint | Method | Purpose |
|---|---|---|
| Get programs 🔗 | POST | The channel calls this endpoint to get a list of all loyalty programs a customer is eligible for. This is typically done to populate a list of available programs in the user interface. |
| Validate Program application 🔗 | POST | As the customer builds their order, the channel calls this endpoint to validate that selected programs are applicable to the current basket. The response will indicate which discounts should be applied. |