Fetching and Opening Loot Boxes for a Program Membership

Loot boxes are collections of virtual items or rewards that a user can obtain within a program.

How Loot Boxes Work in Hang

A loot box for a program represents a set of virtual items or rewards that can be obtained by a user. Hang's Partner API lets you fetch all allocated loot boxes for a particular program membership as well as open any loot box to reveal its contents.

Fetching All Allocated Loot Boxes for a Program Membership

Fetching all loot boxes for a specific program membership is as straightforward as making a GET request to the /v2/program-memberships/:program_membership_id/loot-boxes endpoint.

Request Parameters

• program_membership_id (required): The ID of the user's program membership.

Example Request

Here's an example of a valid GET request to fetch all allocated loot boxes for a program membership:

curl -X GET 'https://loyalty.hang.xyz/partner-api/v2/program-memberships/12345/loot-boxes' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

If successful, the API will return a 200 OK status along with a JSON object containing information about all the allocated loot boxes.

Example Response

{
  "allocated_loot_boxes": [
    {
      "loot_box_id": "loot_box_1",
      "name": "Special Box",
      "description": "A special loot box containing unique items.",
      // ... (other fields)
    }
  ]
}

Opening a Loot Box

To open a loot box, make a POST request to the /v2/program-memberships/:program_membership_id/loot-boxes/:loot_box_id/open endpoint.

Request Parameters

• program_membership_id (required): The ID of the user's program membership.

• loot_box_id (required): The ID of the loot box to be opened.

Example Request

Here's an example of a valid POST request to open a loot box:

curl -X POST 'https://api.yourapp.com/v2/program-memberships/12345/loot-boxes/loot_box_1/open' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

If successful, the API will return a 200 OK status along with a JSON object containing information about the reward obtained from the loot box.

Example Response

{
  "loot_box_reward_outcome": {
    "loot_box_reward_choice_id": "choice_1",
    "loot_box_reward_choice_title": "Special Item",
    // ... (other fields)
  }
}

Error Handling

In case of an error, the API will return a specific error code and message. Refer to the API documentation for details on how to handle different types of errors.