In-Store Customer Onboarding
This flow demonstrates how a new customer can scan a QR code at a store, register with the loyalty platform, and receive an immediate welcome coupon that can be used during their current purchase.
Process overview
- Registration offer: The store employee offers a 10% discount incentive for joining the loyalty program.
- Customer registration: Customer scans the in-store QR code and completes registration with their email and phone.
- System notification: The Loyalty Platform sends an automatic notification to the Point of Sale (PoS) system (see details).
- Coupon delivery: A welcome coupon is delivered to the customer's device which will be notified thought the webhook to the PoS system (see details).
- Redemption: The customer shows the coupon to the salesperson who applies the discount via PoS.
- Check the coupon status: The PoS system can optionally check the status of the coupon (see details).
- Transaction completion: The purchase is completed with the applied discount.
- Purchase notification: The PoS system notifies the Loyalty Platform the purchase performed by the customer along with the coupon that has been used (see details).
Notification events
User Created + Welcome Coupon Assigned Notification
Once the customer completes the registration process, the Loyalty Platform automatically notifies the Point of Sale (PoS) system through a Webhook. This occurs as a two-step process.
1. User Created Notification Payload (member-created)
{
"event": {
"loyaltyEventId": "1262268",
"eventType": "member-created",
"status": "success",
"executionResults": {
"tiers": [
{
"loyaltyTierId": 1,
"loyaltyProgramId": 1,
"loyaltyManualTierId": null,
"loyaltySystemTierId": 1
}
],
"active": true,
"onChain": {
"wallets": []
},
"profile": {
"name": "John",
"email": "test-user@email.com",
"govId": {
"id": "94343643",
"type": "DNI",
"issuingCountry": "Ar"
},
"emails": [
"test-user@email.com"
],
"lastName": "Doe",
"birthdate": "2025-04-24T13:20:24.404Z",
"phoneNumber": "541123364526"
},
"createdAt": "2025-04-24T13:22:50.049Z",
"updatedAt": "2025-04-24T13:22:50.049Z",
"organizations": [
{
"active": true,
"createdAt": "2025-04-24T13:22:50.156Z",
"updatedAt": "2025-04-24T13:22:50.156Z",
"loyaltyMemberId": "test-user@email.com",
"publicLoyaltyMemberId": "11111-11111"
}
],
"ledgerWalletId": 16069,
"ledgerWalletKey": "wal_01JSKZE71W1MD7KWS453W9VJDH"
},
"payload": {
"active": true,
"profile": {
"name": "John",
"email": "test-user@email.com",
"govId": {
"id": "94343643",
"type": "DNI",
"issuingCountry": "Ar"
},
"lastName": "Doe",
"birthdate": "2025-04-24T13:20:24.404Z",
"phoneNumber": "541123364526"
},
"loyaltyMemberId": "test-user@email.com",
"publicLoyaltyMemberId": "11111-11111"
},
"externalEventDate": null,
"evaluationStatus": 0,
"systemUniqueKey": "8952c2f4-d76f-40f3-890d-aef3af273356",
"loyaltyEventKey": "ev_01JSKZG24NMDB0RRQHF247NSCX",
"updatedAt": "2025-04-24T13:23:50.586Z",
"createdAt": "2025-04-24T13:23:50.586Z",
"externalId": null,
"lastError": null,
"description": null,
"tags": null,
"evaluationResults": null
}
}
2. Coupon Assigned Notification Payload (coupon-code-assigned)
{
"event": {
"eventType": "coupon-code-assigned",
"loyaltyEventKey": "ev_01JSG9YM0YZHBS9X3G0VMVMAW6",
"updatedAt": "2025-04-23T03:09:35.646Z",
"createdAt": "2025-04-23T03:09:35.646Z",
"systemUniqueKey": "6efee6f7-2128-4f9b-9d0e-9d771a4a8dec",
"loyaltyMemberId": "11111111",
"status": "success",
"executionResults": {
"coupon": {
"code": "PyMsNLgHR3yfMQAAc11viQ",
"createdAt": "2025-04-23T03:08:29.976Z",
"expiredAt": "2025-06-23T01:52:32.275Z",
"updatedAt": "2025-04-23T03:08:29.976Z",
"totalUsages": 0,
"totalAssigned": 0,
"couponBookKey": "cbk_01JSG2C0V4AJHVZ6P3E0PQH9EV",
"customAttributes": null
},
"createdAt": "2025-04-23T03:08:30.031Z",
"updatedAt": "2025-04-23T03:08:30.031Z",
"amountUsed": 0,
"amountAssigned": 1,
"couponUsageKey": "cbu_01JSG9WKYEJDKTSKVYABF2WQBC",
"revertedUsageId": null,
"systemUniqueKey": "6efee6f7-2128-4f9b-9d0e-9d771a4a8dec",
"customAttributes": null,
"updatedTotalUsages": 0,
"updatedTotalAssigned": 1
},
"payload": {
"usage": {
"coupon": {
"code": "PyMsNLgHR3yfMQAAc11viQ",
"couponBookKey": "cbk_01JSG2C0V4AJHVZ6P3E0PQH9EV",
"createdAt": "2025-04-23T03:08:29.976Z",
"expiredAt": "2025-06-23T01:52:32.275Z",
"updatedAt": "2025-04-23T03:08:29.976Z",
"totalUsages": 0,
"totalAssigned": 0,
"customAttributes": null
},
"createdAt": "2025-04-23T03:08:30.031Z",
"updatedAt": "2025-04-23T03:08:30.031Z",
"amountUsed": 0,
"amountAssigned": 1,
"couponUsageKey": "cbu_01JSG9WKYEJDKTSKVYABF2WQBC",
"revertedUsageId": null,
"systemUniqueKey": "6efee6f7-2128-4f9b-9d0e-9d771a4a8dec",
"loyaltyMemberId": "11111111",
"customAttributes": null,
"updatedTotalUsages": 0,
"updatedTotalAssigned": 1
},
"couponBook": {
"couponBookKey": "cbk_01JSG2C0V4AJHVZ6P3E0PQH9EV",
"name": "Test discount",
"type": "generated",
"externalId": "Y6QF-TEST",
"pictureUrl": "https://example.com/coupon-image.png",
"description": "<p>Test discount description</p>",
"validToDate": null,
"validFromDate": null,
"discountType": "percentage",
"discountAmount": 20,
"tags": null,
"customAttributes": null
}
},
"externalEventDate": null,
"evaluationStatus": 0,
"externalId": null,
"lastError": null,
"description": null,
"tags": null,
"evaluationResults": null
}
}
API Endpoints
Coupon status query
If the PoS system needs to verify a coupon's validity or status, it can query the Loyalty Platform directly using the following endpoint.
Sample request to query the coupon status
curl -X 'GET' \
'https://api.sandbox.qurable.io/v2/coupons?code={code}page=0&limit=10' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}'
Sample response of the coupon status
{
"totalCount": 1,
"page": 0,
"limit": 10,
"results": [
{
"code": "PyMsNLgHR3yfMQAAc11viQ",
"amountAssigned": 1,
"assignments": [
{
"loyaltyMemberId": "11111111"
}
],
"amountUsed": 0,
"customAttributes": {},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"couponBook": {
"couponBookKey": "cbk_01JSG2C0V4AJHVZ6P3E0PQH9EV",
"externalId": "Y6QF-TEST",
"name": "Test discount",
"description": "<p>Test discount description</p>",
"pictureUrl": "https://example.com/coupon-image.png",
"type": "generated",
"publishingStatus": "published",
"validFromDate": "2025-01-01T00:00:00Z",
"validToDate": "2025-12-31T23:59:59Z",
"totalAssigned": 1,
"totalUsages": 0,
"discountType": "percentage",
"discountAmount": 20,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
}
}
]
}
Purchase Notification
After the purchase is complete, the PoS system should notify the Loyalty Platform the event with all the information that will be used in the campaigns. Additionally, if a coupon was used, it will need to send that information in the event to mark the coupon as redeemed.
Sample request to track the purchase
curl -X 'POST' \
'https://api.sandbox.qurable.io/v2/events/track' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
"events": [
{
"loyaltyMemberId": "11111111",
"externalId": "ORDER-1234",
"eventType": "member-purchase-order-confirmed",
"description": "Sample Order",
"payload": {
"items": [
{
"productCode": "PROD123",
"description": "Premium Coffee Beans",
"total": 200000,
"amount": 2,
"subTotal": 100000,
"customAttributes": {
"origin": "Colombia",
"roastLevel": "medium"
},
"discountedTotal": 180000
},
{
"productCode": "PROD456",
"description": "Coffee Grinder",
"total": 500000,
"amount": 1,
"subTotal": 500000,
"discountedTotal": 450000
}
],
"customAttributes": {
"orderSource": "mobile_app",
"promoApplied": "SUMMER2023"
},
"discountedTotal": 630000,
"description": "Coffee equipment purchase",
"total": 700000,
"type": "retail_purchase",
"coupons": ["PyMsNLgHR3yfMQAAc11viQ"]
},
"externalEventDate": "2019-08-24T14:15:22Z",
"tags": [
"coffee",
"equipment",
"premium"
],
}
]
}'
Sample response for the tracking of the purchase
{
"results": [
{
"loyaltyEventKey": "ev_01JG29AJQAQ3NB706GFCHS91H5",
"effects": [
{
"actionKey": "act_01JJY3KNVV8YHH4W46F5XXPTR1",
"campaignCode": "CODE-REDEMPTION",
"campaignKey": "cpg_01JJY3GPJNHMS957NZHCJMENGT",
"campaignName": "Code Redemption",
"actionIndex": 0,
"effectIndex": 0,
"actionName": "Use Coupons",
"effectId": "use-coupons",
"status": "success",
"results": {
"loyaltyProgramId": 1,
"ledgerWalletKey": "wal_01HNX388HM1QN6RKPR4DQQ66D6"
}
}
],
"state": {
"couponUses": [
{
"code": "PyMsNLgHR3yfMQAAc11viQ",
"couponUsageKey": "cbu_01JPJQK43MDH8SXW5XGG9NH3N7",
"updatedTotalUsages": 1,
"success": true
}
]
},
"organizationKey": "org_01JG29AJQAQ3NB706GFCHS91H5",
"status": "ok"
}
]
}