PassEntry provides a number of RESTful endpoints for interacting and manipulating passes created under the Loyalty vertical.
This includes but is not limited to: Loyalty Cards, Gift Cards, Coupons, Memberships…

Terminology

Balance: This can represent loyalty points, stamps, credit, and more in an integer type. Balance can be accumulated or used. Balance is stored in our database and represented on the pass.

POS System: handles in store sales transactions, inventory management, and reporting

Loyalty Program: This is implemented externally to PassEntry, is where the loyalty behaviour is handled and loyalty/customer data is stored. Ideally, this would be closely integrated with the POS system, in order to allow for seamless tracking of purchases and points. As a best practice, any loyalty data relevant to a pass must always be mirrored in the loyalty program.

Payment Terminal: where payment is made, can also be used to read the loyalty pass and thus identify the customer

Enabling loyalty balance

To allow interacting with your passes using the Loyalty API, the first step is to ensure that the parent template has loyalty balance enabled. Once this is done, you must choose how you want the balance to be represented on the pass, set at the pass template level. We currently offer support for integer and decimal types.

  • Integer: Choose this if your balance is represented as whole numbers. Eg: 3, 42, 9000. The loyalty balance will appear as an integer in our responses to the loyalty API, and any numeric value sent in a request will be coerced to an integer. The value on the pass will be represented as an integer.
  • Decimal: We support up to 2 decimal places. Eg: 3.14, 10.95, 100000.34. The loyalty balance will appear as a float in our responses to the loyalty API. When making requests, format the number as a float with no more than 2 decimal places. When displaying the value on the pass, it will be represented using thousand separators with 2 decimal places. (100,000.34)

What does a loyalty integration with PassEntry look like?

Example: PassEntry Coffee has a loyalty program. Every £10 spent, a customer receives 1 Point
When a customer has received 5 points they are able to get £5 off on their order total

Distributing a loyalty pass

  1. A loyalty pass is created and distributed to a customer with an ext_id equivalent to customer in the loyalty program

  2. The loyalty pass balance on this loyalty pass is 0. This is represented on the loyalty pass as Points 0 and is stored on the loyalty program.

  3. When the customer makes a purchase in store and presents their device to make payment, the reader identifies their loyalty pass and sends both the loyalty pass ext_id and the loyalty pass balance to the POS

Accumulating balance

  1. The POS system takes payment, and updates the loyalty pass with a balance equal to a value determined by the loyalty program, alongside an optional push notification.

  2. In this example, the customer has spent £20, so the the balance is increased by 2 points and the customer receives Thank you for your order. You've earned 2 points! as a push notification.

Receiving a reward

  1. The POS system takes £10 payment and customer balance is increased by 1 point.

  2. As the threshold of 5 points has been reached, as determined by the loyalty program, the customer is sent a push notification Congratulations! You've got £5 off on your next order!

  3. The pass design can be updated via the /passes/ endpoint so that the £5 off reward appears on the loyalty pass design to inform the customer of their reward

Redeeming a reward

  1. The POS system is ready to receive payment of £8

  2. The customer presents their device, and their loyalty pass ext_id and balance are sent to the POS system, identifying the customer to the loyalty program

  3. The loyalty program detects that the customer has 5 points and is thus entitled to a £5 off discount

  4. The POS system prompts the user to redeem their £5 off! reward via a Would you like get £5 off on this order? prompt (Optional: rewards can be applied automatically as determined by the loyalty program)

  5. The transaction amount on the payment terminal is updated to £3

  6. The customer makes payment

  7. The reward is removed from the loyalty pass alongside a You've used your £5 off discount! push notification

Resetting the balance (Optional)

  1. At this stage, the loyalty balance can be reset to 0 points

Was this page helpful?