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:

  • category

  • hide_restricted

  • limits

  • notifications

  • segments

  • start_at and end_at dates

  • status

  • stock

  • transferrable

{
    "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.