Point of Sales
Introduction
This is a guide on how to build an integration for POS software. The flows describe the typical flow, but much depends on possibilities and limitations offered by both hardware and software involved.
In this tutorial, we assume you'll build the UI yourself, leveraging our API endpoints to feed the flows with the necessary data. However, there is also the option to use Portal Sessions to power your POS integration. This involves using either the Portal Sessions API or the Portal Sessions SDK. This option is sometimes used for a quick launch strategy or prototyping, while a more polished API-based approach is built in the mean time.
In this tutorial
- 1. Main Loyalty Flow— Identify customers, view rewards & vouchers, redeem offers
- 2. Scan Voucher Flow— Scan and redeem vouchers directly
- 3. Buy Giftcard Flow— Sell and activate physical giftcards
- 4. Pay with Giftcard Flow— Accept giftcard payments
- 5. Buy Prepaid Credit Flow— Top up customer Prepaid balance
- 6. Pay with Prepaid Credit Flow— Accept Prepaid balance payments
Identifying Customers
Identifying Customers
On the POS, a button will need to be added to trigger the identification of the customer and subsequent loyalty flows. Where this button is placed and how it looks is up to you, it's usually accompanied by a label stating 'Loyalty' or 'Rewards' or similar.
When the button is clicked, the POS will open a modal or a separate screen where the customer can be identified. This could be done by scanning a QR code, entering a loyalty card number or entering an email address. Scanning a QR-code is often quickest and most convenient.
Try it: Click the green Rewards button on the POS screen to start the identification flow.
Scanning the Customer's Card
After clicking the rewards button, the customer needs to identify themselves. There are three common methods for this, depending on your hardware capabilities:
Scanning the Customer's Card
After clicking the rewards button, the customer needs to identify themselves. There are three common methods for this, depending on your hardware capabilities:
- Camera Scanner: Uses the device camera to scan QR codes - ideal for tablets and modern POS systems
- Barcode/QR Scanner: Uses dedicated hardware scanners - fastest and most reliable for high-volume environments
- Keyboard Entry: Manual entry of card number or email - works on any system as a fallback
Try it: Hover over the scan area and click to simulate a successful scan.
Tip: You can also use Find or Create Contact to identify customers by email address - useful when they've forgotten their loyalty card, though slower.
Customer Overview
Once the customer is identified, you'll display their loyalty information. This typically includes their tier status, point balance, available offers (combination of Vouchers and Collectable Rewards), and redeemable rewards. Hover over each section to see which API endpoints provide this data.
Customer Overview
Once the customer is identified, you'll display their loyalty information. This typically includes their tier status, point balance, available offers (combination of Vouchers and Collectable Rewards), and redeemable rewards. Hover over each section to see which API endpoints provide this data.
Displaying Rewards: Rewards are typically displayed as a list ordered ascending by required_credits, showing the reward title, required points, and sometimes image.
- Show a "Redeem" button for each reward
- Disable the button if the customer has insufficient points
- Optionally show a progress bar indicating how many more points they need
Displaying Offers: Rewards are typically fewer, therefore displayed as a grid or horizontal list, showing title, expiration date (if present), and sometimes image.
Redeeming Rewards
When a customer selects a reward from their available options, you'll show a confirmation screen. This allows them to confirm they want to spend their points on this reward before it's applied to their order.
Redeeming Rewards
When a customer selects a reward from their available options, you'll show a confirmation screen. This allows them to confirm they want to spend their points on this reward before it's applied to their order.
Note: Applying discount logic to the cart is often the most complex part of the integration. See the Custom Attributes section for how to configure discount logic.
There are two common approaches for handling reward redemption. Neither is inherently better — the right choice depends on your POS system's capabilities.
Option 1: Redeem → Reverse on Failure
- Create Reward Reception — subtracts points immediately
- Process payment
- On success: done!
- On failure: Reverse Reward Reception
Best when your POS can easily handle failed orders but lacks post-success hooks.
Option 2: Pre-Redeem → Collect on Success
- Create Reward Reception with
reward.pre_redeemable: true— creates a Collectable Reward - Process payment
- On success: Collect Reward
- On failure: reward remains collectable for later
Best when your POS can easily trigger an API call after a successful order. Allows customers to save rewards for later visits.
Redeeming Offers
Similarly, when a customer wants to use a voucher or collectable reward (like a birthday offer), they'll see a confirmation screen. These offers could have conditions like minimum spend requirements and expiration dates.
Redeeming Offers
Similarly, when a customer wants to use a voucher or collectable reward (like a birthday offer), they'll see a confirmation screen. These offers could have conditions like minimum spend requirements and expiration dates.
Note: Applying discount logic to the cart is often the most complex part of the integration. See the Custom Attributes section for how to configure discount logic.
There are two common approaches for handling voucher redemption. Neither is inherently better — the right choice depends on your POS system's capabilities.
Option 1: Lock → Redeem on Success
- Check Voucher Validity , then Lock Voucher — reserves the voucher
- Process payment
- On success: Redeem Voucher
- On failure: Release Voucher (or let it expire)
Best when your POS can easily trigger an API call after a successful order.
Option 2: Redeem → Reverse on Failure
- Redeem Voucher — immediately redeems
- Process payment
- On success: done!
- On failure: Reverse Voucher Redemption
Best when your POS can easily handle failed orders but lacks post-success hooks.
Checkout with Rewards Applied
After rewards and offers are confirmed, they're applied to the order. The checkout screen shows the discounts applied (highlighted in green) and the updated total. This is where you'll process the final payment and record the transaction.
Checkout with Rewards Applied
After rewards and offers are confirmed, they're applied to the order. The checkout screen shows the discounts applied (highlighted in green) and the updated total. This is where you'll process the final payment and record the transaction.
Order Complete
After payment, show the customer how many points they earned from this transaction. This reinforces the value of the loyalty program and encourages future visits.
Order Complete
After payment, show the customer how many points they earned from this transaction. This reinforces the value of the loyalty program and encourages future visits.
Clients often want to display the points earned and new balance on the receipt. The response from the Create and Process Order endpoint includes this information.
Applying discounts to the cart/order is often the most complex part of the integration. To enable your POS to handle this correctly, you'll need to create custom attributes that define the discount logic.
Important: Custom attributes must be created on the correct entity:
- For Rewards: Create custom attributes on the Rewards entity
- For Vouchers: Create custom attributes on the Promotions entity (the parent of Vouchers)
Naming Convention: We highly recommend adding an integration-based prefix (or suffix) to each custom attribute's internal name to ensure uniqueness. For example: mypos_discount_type instead of just discount_type. This prevents errors due to duplicate attribute names, as other integrating parties might try to create attributes with the same names.
There are two common approaches for configuring discount logic:
Option 1: Reference ID
discount_rule_id - Reference to an existing discount/price rule in your POS system, often as a single select attribute
Option 2: Direct Configuration
Build the discount logic with a set of attributes fully (or partially) in Leat
Common custom attributes for Option 2:
discount_type- Dropdown: percentage_discount, absolute_discount, or free_itemdiscount_value- Number field (e.g., 100 for 100% off = free item, or 5 for £5 off)product_code- SKU of the specific product (used in ~80% of rewards). Can be comma-separated for multiple optionscategory- If the reward applies to any product in a category rather than a specific SKU
These attribute values are returned in the API responses when listing and claiming rewards, or redeeming vouchers, allowing your POS to apply the correct discount.
If the customer hasn't identified themselves during the order flow, you can still offer them the opportunity to collect loyalty points after payment. This is useful for customers who forgot to scan their card or decided to join the loyalty program at checkout.
After a successful payment, prompt the customer: "Would you like to collect loyalty points on this order?"
- If they choose Yes, show the scan identifier screen and link the transaction to their account
- If they choose No, optionally print a QR code on the receipt that allows them to claim points later
Tip: You can generate a Loyalty Token URL without an API call to print on receipts. See our documentation for more details on implementing this feature.
When an order is cancelled or (partially) returned, you'll need to correct the loyalty data. This involves two separate concerns: correcting issued points, and reversing any redeemed rewards, vouchers, or payment transactions.
1. Correcting Issued Points
To correct points that were issued for a cancelled or returned order, use the Create and Process Order Return endpoint. This will subtract the points that were originally awarded for the returned items.
For partial returns, only include the returned line items — the system will calculate the correct point deduction.
2. Reversing Redeemed Rewards & Vouchers
If rewards or vouchers were redeemed as part of the order, these need to be reversed separately. Each type has its own reversal endpoint:
- Reverse Reward Reception — restores the points and marks the reward as unredeemed
- Reverse Voucher Redemption — restores the voucher to its original state
- Reverse Reward Collection — restores a collected reward back to collectable status
3. Reversing Payment Transactions
If the order was (partially) paid with giftcard balance or prepaid credit, those transactions also need to be reversed:
- Reverse Giftcard Transaction — refunds the amount back to the giftcard
- Reverse Prepaid Transaction — refunds the amount back to the customer's prepaid balance
💡 Tip: Store the transaction UUIDs (reward reception UUID, voucher redemption UUID, giftcard transaction UUID, prepaid transaction UUID) alongside your order data. This makes it easy to reverse the correct transactions when processing returns.
Scan Voucher Directly
Instead of identifying the customer first and then retrieving their vouchers, customers can also scan a voucher QR code directly. This is useful when customers receive vouchers via email or printed flyers.
Trigger Voucher Scan
Similar to the main loyalty flow, a button triggers the voucher scanning flow. This could be a separate "VOUCHER" button next to the "REWARDS" button, or integrated into the same flow.
Trigger Voucher Scan
Similar to the main loyalty flow, a button triggers the voucher scanning flow. This could be a separate "VOUCHER" button next to the "REWARDS" button, or integrated into the same flow.
This flow is typically used when a customer presents a voucher code (from an email, flyer, or printed coupon) without first identifying themselves via their loyalty card.
Try it: Click the green Voucher button on the POS screen to start the voucher scanning flow.
Scan Voucher QR Code
The customer presents a voucher QR code (from an email, flyer, or printed coupon). Use the Find Voucher endpoint to retrieve the voucher details using the scanned code.
Scan Voucher QR Code
The customer presents a voucher QR code (from an email, flyer, or printed coupon). Use the Find Voucher endpoint to retrieve the voucher details using the scanned code.
Try it: Hover over the scan area and click to simulate scanning a voucher QR code.
Link Customer (If Not Linked)
If the voucher is not yet linked to a contact, prompt the customer to scan their loyalty card to link the voucher to their account. This use case is relatively rare, as most vouchers are linked to a contact upon creation.
Link Customer (If Not Linked)
If the voucher is not yet linked to a contact, prompt the customer to scan their loyalty card to link the voucher to their account. This use case is relatively rare, as most vouchers are linked to a contact upon creation.
If the voucher is already linked to a contact, this step can be skipped.
This process can also be used to link the contact to the order itself, so the customer can earn points.
Note: When redeeming an unlinked voucher, you'll need to pass the contact_uuid parameter to the Redeem Voucher API call to link the transaction to the customer.
Confirm & Redeem Voucher
Show the voucher details and ask the customer to confirm redemption. The Promotion linked to the Voucher should contain custom attributes (like discount_rule_id) that enable the POS to apply the discount.
Confirm & Redeem Voucher
Show the voucher details and ask the customer to confirm redemption. The Promotion linked to the Voucher should contain custom attributes (like discount_rule_id) that enable the POS to apply the discount.
Use Lock Voucher to reserve it, then Redeem Voucher after successful payment.
Note: Applying discount logic to the cart is often the most complex part of the integration. See the Custom Attributes section for how to configure discount logic.
Buying Giftcards
This flow covers selling physical giftcards at the POS. These are pre-printed cards (already registered in the system with a €0 balance) that the cashier grabs from behind the counter when a customer wants to purchase one. Digital giftcards can also be purchased, though this use case is less common for POS systems.
Trigger Giftcard Sale
When a customer wants to buy a giftcard, the cashier clicks the "GIFTCARD" button to start the flow. The cashier then grabs a physical giftcard from behind the counter.
Trigger Giftcard Sale
When a customer wants to buy a giftcard, the cashier clicks the "GIFTCARD" button to start the flow. The cashier then grabs a physical giftcard from behind the counter.
Try it: Click the Giftcard button on the POS screen to start the giftcard sale flow.
Scan Giftcard
The cashier scans the QR code on the physical giftcard. The system calls the Find Giftcard endpoint to retrieve the giftcard details and verify it has a €0 balance (i.e., it hasn't been sold yet).
Scan Giftcard
The cashier scans the QR code on the physical giftcard. The system calls the Find Giftcard endpoint to retrieve the giftcard details and verify it has a €0 balance (i.e., it hasn't been sold yet).
Choose Amount
The customer chooses how much credit to load onto the giftcard. Common options are preset amounts (€10, €25, €50, etc.) but a custom amount can also be entered.
Choose Amount
The customer chooses how much credit to load onto the giftcard. Common options are preset amounts (€10, €25, €50, etc.) but a custom amount can also be entered.
Giftcard Added to Cart
The giftcard appears as a line item in the cart for the chosen amount. The customer pays for the giftcard like any other product.
Giftcard Added to Cart
The giftcard appears as a line item in the cart for the chosen amount. The customer pays for the giftcard like any other product.
After successful payment, the system calls Create Giftcard Transaction with a positive amount to load the credit onto the giftcard.
For digital giftcards (not physical cards), the flow is slightly different:
- Create Giftcard — creates a new giftcard in the system
- Create Giftcard Transaction — loads the purchased amount
- (Optional) Send Giftcard by Email — sends the giftcard code to the recipient
Paying with Giftcards
Customers can use their giftcard balance to pay for (part of) their order. This flow is triggered at the payment step.
Select Giftcard Payment
At the payment step, the customer indicates they want to pay with a giftcard. The cashier selects the "GIFTCARD" payment method.
Select Giftcard Payment
At the payment step, the customer indicates they want to pay with a giftcard. The cashier selects the "GIFTCARD" payment method.
Try it: Click the Giftcard payment button to start the giftcard payment flow.
Scan Giftcard
The customer scans or enters their giftcard code (e.g., 'HT123ABC'). The system calls Find Giftcard to retrieve the current balance.
Scan Giftcard
The customer scans or enters their giftcard code (e.g., 'HT123ABC'). The system calls Find Giftcard to retrieve the current balance.
Try it: Hover over the scan area and click to simulate scanning a giftcard.
Confirm Payment
The system shows the giftcard balance and calculates how much will be deducted. The customer confirms they want to use their giftcard funds.
Confirm Payment
The system shows the giftcard balance and calculates how much will be deducted. The customer confirms they want to use their giftcard funds.
Upon confirmation, the system calls Create Giftcard Transaction with a negative amount to deduct from the balance.
Note: If the giftcard balance doesn't cover the full order, the remaining amount can be paid with another payment method (card, cash, etc.).
If the order is cancelled or fails after the giftcard transaction has been created, use the Reverse Giftcard Transaction endpoint to restore the giftcard's balance.
Buying Prepaid Credit
Prepaid credit is tied to a customer's account, not a physical card. Customers can top up their prepaid balance at the POS and use it for future purchases.
Trigger Prepaid Top-up
When a customer wants to add credit to their prepaid balance, the cashier clicks the "PREPAID" button to start the flow.
Trigger Prepaid Top-up
When a customer wants to add credit to their prepaid balance, the cashier clicks the "PREPAID" button to start the flow.
Try it: Click the Prepaid button on the POS screen to start the prepaid top-up flow.
Identify Customer
Since prepaid credit is tied to a customer account (not a physical card), the customer must first be identified by scanning their loyalty card or entering their details.
Identify Customer
Since prepaid credit is tied to a customer account (not a physical card), the customer must first be identified by scanning their loyalty card or entering their details.
The system calls Find Contact Identifier to retrieve the customer and their current prepaid balance.
Choose Amount
The customer chooses how much credit to add to their prepaid balance. The screen shows their current balance and preset amount options.
Choose Amount
The customer chooses how much credit to add to their prepaid balance. The screen shows their current balance and preset amount options.
Top-up Added to Cart
The prepaid top-up appears as a line item in the cart. The customer pays for it like any other product.
Top-up Added to Cart
The prepaid top-up appears as a line item in the cart. The customer pays for it like any other product.
After successful payment, the system calls Create Prepaid Transaction with a positive amount to add credit to the customer's prepaid balance.
Paying with Prepaid Credit
Customers who have prepaid credit on their account can use it to pay for (part of) their order. Since prepaid is tied to their account, the customer must already be identified.
Select Prepaid Payment
At the payment step, if the customer has been identified and has prepaid credit, the "PREPAID" payment option becomes available. The cashier selects it to use the customer's balance.
Select Prepaid Payment
At the payment step, if the customer has been identified and has prepaid credit, the "PREPAID" payment option becomes available. The cashier selects it to use the customer's balance.
Try it: Click the Prepaid payment button to start the prepaid payment flow.
Scan Identifier
If the customer hasn't identified themselves yet at this point, they must do so before proceeding with the prepaid payment.
Scan Identifier
If the customer hasn't identified themselves yet at this point, they must do so before proceeding with the prepaid payment.
Confirm Payment
The system shows the customer's prepaid balance and calculates how much will be deducted. The customer confirms they want to use their prepaid credit.
Confirm Payment
The system shows the customer's prepaid balance and calculates how much will be deducted. The customer confirms they want to use their prepaid credit.
Upon confirmation, the system calls Create Prepaid Transaction with a negative amount to deduct from the balance.
Note: If the prepaid balance doesn't cover the full order, the remaining amount can be paid with another payment method (card, cash, etc.).
If the order is cancelled or fails after the prepaid transaction has been created, use the Reverse Prepaid Transaction endpoint to restore the customer's balance.