Loyalty: Overview

Swagger Definition

The Swagger definition for this version of the Loyalty API can be found at: https://app.swaggerhub.com/apis/Triquestra/loyalty/3.4.

Overview

The Loyalty API enables the retrieval of loyalty data associated with the Infinity Loyalty program functionality. This covers Loyalty programs, Loyalty accounts, and the offers and points for a Loyalty account.

 

Using the Loyalty API you can:

  • Retrieve a list of Loyalty programs.
  • Retrieve the categories of a Loyalty program.
  • Retrieve an individual Loyalty account.
  • Delete a Loyalty account.
  • Update the category of an existing Loyalty account.
  • Create an individual Loyalty account based on a person.
  • Link an existing Loyalty account to a person.
  • Search for a list of Loyalty accounts.
  • Add identifiers to an existing Loyalty account.
  • Update identifiers on an existing Loyalty account.
  • Retrieve all identifiers on an existing Loyalty account.
  • Delete identifiers on an existing Loyalty account.
  • Retrieve all accumulator information for a specified Loyalty account.
  • Add notes against a Loyalty customer.
  • Retrieve notes against a Loyalty customer and their transactions.
  • Create an offer for a Loyalty account.
  • Retrieve the offers available to a Loyalty account.
  • Delete an offer for a Loyalty account.
  • Update an offer for a Loyalty account.
  • Consume one or more Loyalty offers.
  • Retrieve the points available to a Loyalty account.
  • Create and retrieve a “Check In” object.
  • Lock and unlock a “Check In” object.

The Loyalty API is composed of the following:

  • Programs: Defines an individual Loyalty program, including an ID and a name.
  • Loyalty account: Identifies an entity that belongs to a Loyalty scheme, the people associated with the account and the identifiers associated with the account.
  • Identifier: An identifier is a string associated with a single Loyalty account to enable a quick lookup. This could be a licence plate, RFID code or a barcode on the customer’s keyring. An identifier cannot be assigned to more than one account.
  • Offers: Offers are assigned to customers to incentivise them to make purchases; e.g. 20% off your next purchase, or $50 store credit. An offer is consumed as part of a sale, and can be in the form of a dollar value or a percentage off. Offers have a validity period and can be tied to the purchase of a specific product.
  • Points: Points are earned by customers when a transaction is made, and can also be awarded to customers at any time. Points can be used to trigger offers, or to move the customer to a new program, which in turn drives purchasing behaviour. For example: “Earn 100 points and receive 20% off your next purchase”.
  • Check In: A check-in allows a customer to pre-select Loyalty offers and a pre-authorisation prior to approaching the point of sale. For example, a customer may select some offers on their smartphone app which then produces an identifier such as a unique code, or a barcode. At the point of sale that identifier is used to retrieve the Loyalty offers that the customer would like to redeem. A check-in also allows a customer to redeem a fuel CPL balance across other loyalty accounts and an external fuel CPL balance for an external identifier that is not associated with the loyalty account.
  • Note: A note is a text note that is captured against a customer for future reference. A customer can have many notes, each up to 5000 characters long.
  • Transaction Note: This is a note that is captured against a transaction. A transaction note contains the reference to the original transaction as well as indicating if it is internal or externally facing. The transaction note is pulled from a view in your AKPOS database called web_CustomerTransactionNotes.
  • Accumulators: Accumulators can be defined as a loyalty reward promotion that accumulates each time it is triggered. An example would be a simple buy-five-hot-drinks-and-get-the-sixth-hot-drink-free offer. Each time a Loyalty customer buys a hot drink the promotion increments by the amount that is purchased.

Identifier Types

  • Flybuys
  • Airpoints
  • Mobile App ID
  • Number plate
  • Velocity
  • External CRM ID

Examples

Retrieve a list of all Loyalty programs:

GET /loyalty/programs

 

Retrieve the categories of a Loyalty program:

GET /loyalty/programs/1/categories

 

Retrieve Loyalty account 12345:

GET /loyalty/programs/3/loyalty_accounts/12345

 

Delete a Loyalty account:

DELETE /loyalty/programs/3/loyalty_accounts/12345

 

Link PersonCode 98765 to an existing Loyalty account 12345:

PUT /loyalty/programs/3/loyalty_accounts/12345


{


"person_code": "98765"


}

 

Update the category 4 to an existing Loyalty account 12345:

PUT /loyalty/programs/3/loyalty_accounts/12345/category


{


"category": "4"


}

 

Add an Identifier to Loyalty account 12345:

POST /loyalty/programs/1/loyalty_accounts/12345/identifier

 

Update an identifier on Loyalty account 12345:

PUT /loyalty/programs/1/loyalty_accounts/12345/identifier

 

Get specific identifiers details:

GET /loyalty/programs/1/loyalty_account_identifiers/abcdef/identifier

 

Get specific identifiers details on Loyalty account 12345:

GET /loyalty/programs/1/loyalty_account_identifiers/12345fdentifier

 

Get all identifiers on Loyalty account 12345:

GET /loyalty/programs/1/loyalty_accounts/12345/identifier

 

Get all accumulator information for Loyalty account 12345:

GET /loyalty/programs/1/loyalty_accounts/12345/accumulators

 

Retrieve the 10 most recent notes for Loyalty account 12345:

GET /loyalty/programs/3/loyalty_accounts/12345/notes?page_number=1&page_size=10

 

Retrieve the next 10 most recent notes for Loyalty account 12345:

GET /loyalty/programs/3/loyalty_accounts/12345/notes?page_number=2&page_size=10

 

Retrieve the 10 most recent transaction notes for Loyalty account 12345:

GET /loyalty/programs/3/loyalty_accounts/12345/transaction_notes?page_number=1&page_size=10

 

Retrieve the offers for Loyalty account 12345:

GET /loyalty/programs/3/loyalty_accounts/12345/offers

 

Create an offer for Loyalty account 12345:

POST /loyalty/programs/1/loyalty_accounts/12345/offers

 

Delete an offer for Loyalty account 12345:

DELETE /loyalty/programs/1/loyalty_accounts/12345/offers/100

 

Update an offer for Loyalty account 12345:

PUT /loyalty/programs/1/loyalty_accounts/12345/offers/100

 

Consume one or more Loyalty offers:

POST /loyalty/programs/1/loyalty_accounts/12345/offers/consumption

 

Retrieve the points for Loyalty account 12345:

GET /loyalty/programs/3/loyalty_accounts/12345/points

 

Create a check-in object that contains a Loyalty account and offers:

POST /loyalty/programs/1/check_in/request

 

Get an existing check-in object based on a check-in code. Used for verifying a check in within a sales transaction:

GET /loyalty/programs/1/check_in/a2db6571-f79a-4fa1-9273-860daabd1440

 

Lock or unlock a check-in object:

PUT /loyalty/programs/1/check_in/a2db6571-f79a-4fa1-9273-860daabd1440

 

Consume a check-in object:

POST /loyalty/programs/1/check_in/consume

 

Get an existing check-in code for the Loyalty account code provided:

GET /loyalty/programs/1/check_in/loyalty_accounts/12345

 

Security Risk Profile

Financial Data 1: details of offer values and loyalty points values are exposed.

Personal Data 3: details of loyalty people are exposed.

Business Data 1: offers which may relate to business-specific promotions are exposed.