Rewards#

Rewards are a key component in the Antavo ecosystem as they provide a mechanism to reward the customer’s loyalty performance. There are many different types of rewards available in Antavo and are usually used with, but not restricted to, points.

This section provides a complementary API-based approach for the reward lifecycle and all customer interactions. All the work described here can also be performed within the Antavo Backoffice.

Note

All API examples have not included authentication to maintain clarity. Calls to production environments can only be authenticated by using API signing.

Reward management#

Antavo rewards are entities and thus can be fully accessed using the custom entities module and corresponding Entities APIs. The mechanisms described here can be modified to work for other custom entities using the generic entities APIs.

Rewards can be created using a PUT request to https://api.environment.antavo.com/entities/Rewards/reward with the following request body:

Minimal requirements for generation of a reward via API#

 {
 "name": "Example",
 "description": "This is a reward created in custom entities",
 "price": 100, //The value of the reward
 "type": "coupon" // The type of reward to be generated
 }

A reward can also created with these addition fields:

Built-in Reward attributes

Field	Type	Description
claim_button_label	string	A field contain text which can be used for a claim button
cost	numeric	The cost of the reward
countdown_until_end	boolean	Displays a countdown until the rewards enddate
countdown_until_start	boolean	Displays a countdown until the rewards startdate
coupon_pool	string	The unique identify of the coupon pool to be associated with this reward
description	string	A customer-facing description of the rewards
display_coming_soon	boolean	The reward will visible but not claimable for customer before the start date
ends_at	date	The end date for the rewards. After this date, the reward will not be visible for eligible customers
hidden	boolean	The reward is not listed in the available rewards of the customer but can still be claimed via workflows and via the backoffice
hide_restricted	boolean
image_url	string	An image associated with the reward
limit	numeric	the maximum number of times the customer can claim the reward
max_claims	numeric	the maximum number of times the customer can claim the reward
max_price
name	string	The name of the reward
notifications	boolean
price	numeric	The face value of the rewards
price_ste
redeem_instructions
repeat_interval	time	The relative time before the customer can claim the reward again
restricted_message	string	Message displayed to customer if they try to claim a reward and are not eligible.
starts_at	date	The date from which the reward is claimable
status	string	The status of the reward. Options: active,inactive,archived
stock	numeric	the number of total rewards available. Automatically adjusted when rewards are claimed/revoked
terms	string	The customer-facing terms and conditions for the rewards
user_notification	boolean
visibility
webhook_data	array	Additional configurable key:pair values which are added to automatic generated webhooks

Note

Coupons and rewards are separate entities in Antavo. Coupon Pools are now the default mechanism for the configuration of coupons.

Rewards can also be modified using a POST request to https://api.environment.antavo.com/entities/Rewards/reward/entity_id. The unique entity ID of the reward to be modified can be accessed from the PUT response from its creation or extracted from a GET request to https://api.environment.antavo.com/entities/Rewards/reward/, which returns all rewards in the system.

Note

It is not possible to change the unique ID or the type of reward once created.

Inactive rewards can also be archive using a DELETE request. Antavo archives data and objects by policy. Archiving makes the reward completely non-visible and inaccessible for customers and Antavo back office users, effectively removing it from the system. The reward can be restored but only by raising a support ticket with Antavo

All rewards in the system can be accessed using a GET request to https://api.environment.antavo.com/entities/Rewards. The response contains the standard customer reward response and additional information:

Additional response information

category
hide_restricted
limits
notifications
segments
start_at and end_at dates
status
stock
transferrable

Typical Response for a GET Reward request

{
    "data": [{
        "id": "5f05b989a44bc1c44008b4590",
        "name": {
            "en": "Reward name"
        },
        "description": {
            "en": "Reward description"
        },
        "redeem_instructions": {
            "en": "Redeem instructions"
        },
        "terms": {
            "en": "Terms & Conditions"
        },
        "type": "coupon",
        "starts_at": {},
        "ends_at": {},
        "message": "Message",
        "claim_button_label": {
            "en": "Claim"
        },
        "category": {
            "id": "5ef1ad79a44b5e15008b456e"
        },
        "segments": [{
            "id": "5ef1ad79a44b5e15008b456e"
        }],
        "cost": "150.5",
        "hide_restricted": false,
        "hidden": false,
        "restricted_message": {
            "en": "Message"
        },
        "repeat_interval": "1 week",
        "stock": 42,
        "max_claims": 90,
        "notifications": false,
        "user_notifications": false,
        "status": "inactive",
        "price": {
            "EUR": 500
        }
    }]
}

Customer-driven interactions#

Antavo is a customer-driven Antavo Enterprise Loyalty Cloud and the Display API reward section provides a customer-centric API interface. Only the customer-specific and valid rewards are accessible and claimable.

Accessing reward information#

Antavo can return information all available rewards for a given customer by making a GET call to the https://api.environment.antavo.com/customers/customer_id/activities/rewards endpoint. Each reward within the returned list of rewards contains an _actions field for directly claiming the reward and the API response can be enhanced with numerous field options, include the number of claims and wallet passes, where applicable. This response can also be paginated.

A more detailed breakdown of an individual reward can be made via a GET call to https://api.environment.antavo.com/customers/customer_id/activities/Rewards/reward_id.

All previously claimed rewards are accessible from a GET call to https://api.environment.antavo.com/customers/customer_id/Rewards/. This endpoint is independent of the current status of the claimed reward in Antavo.

Claiming a Reward#

A reward can be claimed for a customer by posting a POST request to https://api.environment.antavo.com//customers/customer_id/activities/Rewards/reward_id/claim. This action will result in a API response and an Reward claim event being written to the customers’s event stream.

Revoking a Reward#

In some scenarios, a Reward may need to be withdrawn from the customer and any associated points/statistics need to be reset. A POST request to https://api.environment.antavo.com//customers/customer_id/activities/Rewards/reward_id/revoke provides this functionality and requires the specific unique identifier of the Reward event, written when the reward was claimed. This information can be accessed from the customers’s event history.