Checking applicable Rewards for a Toast cart
Activities are events that change the points a specific user has in a program.
The POST /v2/program-memberships/:program_membership_id/applicable-rewards endpoint lets you see which of a user's rewards are applicable to a given Toast check object.
It returns all the user's rewards, split into two lists - valid_rewards and invalid_rewards.
Rewards are deemed if they require menu items or menu groups not present in the cart, or if they include either with a quantity that the check doesn't contain. Matching is done based on the multiLocationId of the included items and itemGroups.
Request Parameters
toast_restaurant_guid(required): The GUID of the toast restaurant the order is for.check(required): The serialized Toast check object.
The check object contains:
amount(required): The total order amount.selections(required): The array of selection objects.
Each selection in the selections array contains:
guid(required): The Toast item guid.amount(required): The quantity of the item in the cart.price(required): The price (in cents).tax(required): The tax (in cents).taxInclusion(required): Whether tax is included ("INCLUDED"or"NOT_INCLUDED").item(required): The Toast item object.itemGroup(required): The Toast item group object.
Each item in the selection contains:
guid(required): The Toast GUID for the item.entityType(required): The Toast type of the item..externalId(required): The Toast external lD for the item.multiLocationId(optional): The Toast multi-location lD for the item.
Each itemGroup in the selection contains:
guid(required): The Toast GUID for the item group.entityType(required): The Toast type of the item group.externalId(required): The Toast external lD for the item group.multiLocationId(optional): The Toast multi-location lD for the item group.
Example Request
Here's an example of a valid POST request to the activity endpoint:
curl -X POST 'https://loyalty.hang.xyz/partner-api/v2/program-memberships/12345/applicable-rewards' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"toast_restaurant_guid": "8eaa0d9d-9d73-4e59-86c2-0aef842c9e7d",
"check": {
"amount": 22.00,
"selections": [{
"guid": "123",
"name": "Test",
"amount": "1",
"price": 20.00,
"tax": 2.00,
"item": {
"entityType": "MenuItem",
"externalId": "EX0001",
"multiLocationId": "0001",
"guid": "1"
},
"itemGroup": {
"entityType": "MenuGroup",
"externalId": "EX0002",
"multiLocationId": "0002",
"guid": "2"
}
}]
}
}'Response
If successful, the API will return a 200 OK status along with valid and invalid rewards.
Example Response
{
"valid_rewards": [
{
"uuid": "105a23d5-2253-458f-bff5-aec135fac64b",
"name": "Test Reward 1",
"priority": null,
"description": "This is a description",
"redemption_instruction": "This is a brand description",
"redemption_count": 0,
"redemption_method": "code",
"interval": 0,
"limit": 12,
"start_date": 1716674851,
"end_date": 0,
"reward_type": "discount_value_based",
"reward_value": 18.0,
"maximum_discount_value": 17.5,
"last_redeemed_at": null,
"image_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/images/000/000/001/original/image.png",
"video_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/videos/000/000/001/original/foo.mp4",
"achievement_id": "5024ac89-7397-4da0-b8be-0d7402945d84",
"terms_and_conditions": "##### Aut\nOdio eligendi totam. Minima corporis ipsum. Vitae ea aut. Earum et possimus. Velit et ut.\n#### Et",
"store_discount_url": null,
"metadata": {
"foo": "bar"
},
"can_be_combined_with_other_rewards": true,
"applicable_menu_item_multi_location_ids": ["0001"],
"applicable_menu_group_multi_location_ids": [],
"minimum_quantity": null
}, {
"uuid": "ce7b4d00-97ae-4f6b-8453-7c43ecdf9d0e",
"name": "Test Reward 2",
"priority": null,
"description": "This is a description",
"redemption_instruction": "This is a brand description",
"redemption_count": 0,
"redemption_method": "code",
"interval": 30,
"limit": 2,
"start_date": 1716674851,
"end_date": 0,
"reward_type": "redemption",
"reward_value": 15.0,
"maximum_discount_value": null,
"last_redeemed_at": null,
"image_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/images/000/000/002/original/image.png",
"video_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/videos/000/000/002/original/foo.mp4",
"achievement_id": "815f4d24-5ec2-4173-85e1-f7639d2a216e",
"terms_and_conditions": "## Soluta\nOmnis quibusdam sed. Ipsa inventore nam. Culpa voluptatem porro. Qui dolorem aut. Adipisci qui quasi.\n```ruby\nNam.\n```",
"store_discount_url": null,
"metadata": {
"foo": "bar"
},
"can_be_combined_with_other_rewards": false,
"applicable_menu_item_multi_location_ids": [],
"applicable_menu_group_multi_location_ids": ["0002"],
"minimum_quantity": null
}, {
"uuid": "bf728700-111d-417c-b6f0-66ed3043ab45",
"name": "Test Reward 3",
"priority": null,
"description": "This is a description",
"redemption_instruction": "This is a brand description",
"redemption_count": 0,
"redemption_method": "code",
"interval": 0,
"limit": 20,
"start_date": 1716674851,
"end_date": 0,
"reward_type": "redemption",
"reward_value": 16.0,
"maximum_discount_value": null,
"last_redeemed_at": null,
"image_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/images/000/000/004/original/image.png",
"video_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/videos/000/000/004/original/foo.mp4",
"achievement_id": "d282080d-2636-416f-b739-34eb9a29862b",
"terms_and_conditions": "##### Nihil\nSint unde a. Dolorem accusamus repudiandae. Alias maiores libero. Fugit aspernatur doloribus. Dolor qui laboriosam.\n```ruby\nRepellendus.\n```",
"store_discount_url": null,
"metadata": {
"foo": "bar"
},
"can_be_combined_with_other_rewards": false,
"applicable_menu_item_multi_location_ids": [],
"applicable_menu_group_multi_location_ids": [],
"minimum_quantity": null
}
],
"invalid_rewards": [
{
"uuid": "ffde002f-9354-42cd-bede-c21e80d9ca90",
"name": "Invalid Test Reward",
"priority": null,
"description": "This is a description",
"redemption_instruction": "This is a brand description",
"redemption_count": 0,
"redemption_method": "code",
"interval": 0,
"limit": 12,
"start_date": 1716674851,
"end_date": 0,
"reward_type": "discount_value_based",
"reward_value": 18.0,
"maximum_discount_value": 17.5,
"last_redeemed_at": null,
"image_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/images/000/000/001/original/image.png",
"video_url": "https://s3-us-north-south-1.amazonaws.com/test-buckets/live/nft_loyalty_rewards/videos/000/000/001/original/foo.mp4",
"achievement_id": "5024ac89-7397-4da0-b8be-0d7402945d84",
"terms_and_conditions": "##### Aut\nOdio eligendi totam. Minima corporis ipsum. Vitae ea aut. Earum et possimus. Velit et ut.\n#### Et",
"store_discount_url": null,
"metadata": {
"foo": "bar"
},
"can_be_combined_with_other_rewards": true,
"applicable_menu_item_multi_location_ids": ["0004"],
"applicable_menu_group_multi_location_ids": [],
"minimum_quantity": null
}
]
}Error Handling
If the API encounters an error, a relevant error message will be returned to guide you through the troubleshooting process.
Last updated