> For the complete documentation index, see [llms.txt](https://docs.hang.com/hang-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hang.com/hang-platform/api-usage/checking-applicable-rewards-for-a-toast-cart.md). # Checking applicable Rewards for a Toast cart 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 invalid if they require menu items, menu groups, or modifiers not present in the cart, or if they include any of these with a quantity that the `check` doesn't contain. Matching is done based on the `multiLocationId` of the included `item`s, `itemGroup`s, and `modifier`s. ### 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. * `modifiers` *(optional)*: The array of modifier objects applied to this selection. Required for modifier-scoped rewards (e.g. a free add-on) to be evaluated against the cart. 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. Each `modifier` in the `modifiers` array contains: * `quantity` *(optional)*: The quantity of the modifier on this selection. * `price` *(optional)*: The price of the modifier. * `item` *(required)*: The Toast modifier option object, containing: * `guid` *(required)*: The Toast GUID for the modifier option. * `entityType` *(required)*: The Toast entity type; modifier options are `"MenuItem"`. * `multiLocationId` *(optional)*: The Toast multi-location ID for the modifier option. This is matched against the reward's `applicable_modifier_multi_location_ids`. #### Example Request Here's an example of a valid **`POST`** request to the activity endpoint: ```bash 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" }, "modifiers": [{ "quantity": 1, "price": 1.50, "item": { "entityType": "MenuItem", "multiLocationId": "0003", "guid": "3" } }] }] } }' ``` ### 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": [], "applicable_modifier_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"], "applicable_modifier_multi_location_ids": [], "minimum_quantity": null }, { "uuid": "bf728700-111d-417c-b6f0-66ed3043ab45", "name": "Free Add-On Reward", "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": [], "applicable_modifier_multi_location_ids": ["0003"], "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": [], "applicable_modifier_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.