> 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/fetching-and-opening-loot-boxes-for-a-program-membership.md).

# 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`](broken://pages/8eqT8axl5iyR7wIoJ1Gr#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:

```bash
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**

```json
{
  "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`](broken://pages/8eqT8axl5iyR7wIoJ1Gr#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:

```bash
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**

```json
{
  "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.