Displaying Loyalty
NOTE: These mutations and queries will only work when used with a valid customer ID and apiKey which should be received during user authentication.
Loyalty Structure:
This diagram gives you an idea of how loyalty programmes are structured in Slerp:
Key principles:
- Each programme has cards, cards are awarded units (points or stamps) based on actions either in store (stamping via a QR code) or online (ordering).
- Stamps are reconciled to cards using a customer_card
- Each customer can have many customer_cards
- Each merchant can have many loyalty_cards
- Each loyalty_card has at least one, sometimes many, rewards.
- When a pre-determined number of points are achieved on a customer_card a reward is issued.
- A reward can be redeemed in-store (via a scan) or online (via a purchase)
- A reward can only be redeemed once
- Only 1 reward can be redeemed per online purchase
Displaying a Loyalty Card
Run this query to get all valid loyalty programmes for a merchant. If there are no valid programmes an empty array is returned.
query GetCards {
loyalty_cards(where: {merchant: {id: {_eq: "be246f08-7271-4350-b95c-72b3902b02c0"}}, archived_at: {_is_null: true}, published: {_eq: true}}) {
all_stores_enabled
code
store_ids
name
description
image
theme
stamp_label
stamp_value
starts_at
ends_at
rewards {
description
name
required_quantity
earned_reward_message
product_ids
product_limit
redeem_reward_message
reward_type
reward_value
reward_value_type
variants_only
}
id
inserted_at
product_ids
stamp_type
stamps_per_scan
}
}
Sample response:
{
"data": {
"loyalty_cards": [
{
"all_stores_enabled": true,
"code": "fb5967a812482eb67dece2271d01e10a",
"store_ids": [],
"name": "Itsu Butterfly Loyalty",
"description": "This is a close mimic of the existing Itsu Loyalty Card",
"image": "Screenshot 2022-02-08 at 22.38.25.png?63811579210",
"theme": null,
"stamp_label": "stamps",
"stamp_value": 5,
"starts_at": "2022-02-08T00:00:00",
"ends_at": null,
"rewards": [
{
"description": "This is the current reward, a free itsu.",
"name": "One Free Itsu",
"required_quantity": 8,
"earned_reward_message": "Congratulations your next itsu is free",
"product_ids": [],
"product_limit": 1,
"redeem_reward_message": "Great, you've redeemed a free itsu",
"reward_type": "value",
"reward_value": 100,
"reward_value_type": "percentage",
"variants_only": true
}
],
"id": "162306cd-ba9a-475d-95f5-2f05cd1198cc",
"inserted_at": "2022-02-08T22:40:09",
"product_ids": [],
"stamp_type": "value",
"stamps_per_scan": 1
},
{
"all_stores_enabled": true,
"code": "e05ba37613e72877746ef896eb9a4db4",
"store_ids": [],
"name": "Itsu product loyalty - buy 6 Dragon Rolls get 1 Free",
"description": "This is a fictional product based card based on dragon rolls, it's effectively buy 6 get 1 free",
"image": "Screenshot 2022-02-08 at 22.38.25.png?63811579345",
"theme": null,
"stamp_label": "stamps",
"stamp_value": null,
"starts_at": "2022-02-08T00:00:00",
"ends_at": null,
"rewards": [
{
"description": "Congratulations you've earned 1 free Dragon Roll",
"name": "Get 1 free Dragon Roll",
"required_quantity": 6,
"earned_reward_message": "Thanks, this Dragon Roll is free",
"product_ids": [
"7fdd2d79-9224-461d-81ad-298e7bd87b56",
"34e44a5b-b0b5-4169-836c-3823fd0a0e4f",
"04fc2a55-187f-445e-bfe1-4f16953b2d82"
],
"product_limit": 1,
"redeem_reward_message": null,
"reward_type": "product",
"reward_value": 100,
"reward_value_type": "percentage",
"variants_only": true
}
],
"id": "4d37c558-2c67-4805-abce-7ccb91911404",
"inserted_at": "2022-02-08T22:42:24",
"product_ids": [
"7fdd2d79-9224-461d-81ad-298e7bd87b56",
"34e44a5b-b0b5-4169-836c-3823fd0a0e4f",
"04fc2a55-187f-445e-bfe1-4f16953b2d82"
],
"stamp_type": "product",
"stamps_per_scan": 1
}
]
}
}
Key Fields:
- The stamp_value is the £'s required to earn a stamp so can be used for the calculation.
- "reward_type": Is this a percent off, £ off or product based card
- "product_ids": only if a product card, which products can I get for free
- "product_limit": only if a product card, how many free products can I get with this card
- "reward_value": what % or £ off am I getting
- "reward_value_type": am I getting a % or £ off?
- "code": The code used to check a stamp associates to a card. Required in several queries
Displaying a customers Loyalty Cards
Getting data on a customer loyalty card requires this query:
query CustomerCards {
customer_loyalty_cards(
where: {customer: {id: {_eq: "a01ae086-dc25-4ae3-851f-01a4c6edd915"}, merchant: {id: {_eq: "2ba090b2-d4dc-4fd1-ba5c-9e0b73586673"}}}}
) {
id
stamps_aggregate(where: {forfeited_at: {_is_null: true}}) {
aggregate {
count
}
}
loyalty_card_id
customer_rewards {
archived_at
redeemed_at
id
reward_id
}
}
}
Response:
{
"data": {
"customer_loyalty_cards": [
{
"id": "ebdf1c03-9271-4946-b421-826091ea8528",
"stamps_aggregate": {
"aggregate": {
"count": 18,
},
},
"loyalty_card_id": "74c7479b-9051-4de9-bc25-baa242acfb1d",
"customer_rewards": [
{
"archived_at": null,
"redeemed_at": "2022-04-28T07:32:26.617895",
"id": "d0fc8ba1-4f82-4fad-856d-601be3569c4d",
"reward_id": "20b383b7-b541-4b89-a779-c4c79e2f7e7d"
},
{
"archived_at": null,
"redeemed_at": null,
"id": "c005af63-84af-4bb5-b5a8-37aa3c42c13d",
"reward_id": "a250a0fc-9f4a-4859-a612-66866bc87537"
},
{
"archived_at": null,
"redeemed_at": "2022-05-10T13:32:49.367303",
"id": "e3aa4d12-ca29-4c82-a7f3-0d85765c555f",
"reward_id": "dd92e510-de1f-4ae8-9dae-04b59efe52a7",
}
],
},
{
"id": "71d70dc5-e6b9-4ed4-8b47-5e9642d5eee2",
"stamps_aggregate": {
"aggregate": {
"count": 2
}
},
"loyalty_card_id": "720ab7fa-27da-452a-b4d3-38d572601754",
"customer_rewards": []
}
]
}
}
Key notes:
- stamps_aggregate.aggregate.count is the number of stamps on the card
- customer rewards is the array of rewards earned on the card. If none this will be empty
Rewards
Rewards can be found on the above query under customer_rewards.
NOTE: If a reward has an archived at or redeemed at date it cannot be redeemed again