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.