> For the complete documentation index, see [llms.txt](https://noctaly-bot.gitbook.io/noctaly-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://noctaly-bot.gitbook.io/noctaly-api/economy/items.md).

# Items

#### List Guild Items <a href="#list-guild-items" id="list-guild-items"></a>

```http
GET guilds/{guildID}/items
```

Returns all items configured in the guild's economy.

**Response Fields**

| Field | Type     | Description                               |
| ----- | -------- | ----------------------------------------- |
| items | `Item[]` | All items defined in the guild's economy. |

```json
{
    "items": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Magic Sword",
            "description": "A legendary blade.",
            "type": "CUSTOM",
            "flags": ["KEEP_AFTER_USE"],
            "emoji": "⚔️",
            "emojiType": "UNICODE",
            "iconURL": null,
            "buyPrice": 1000,
            "sellPrice": 500,
            "cooldown": 60,
            "durability": 10,
            "quantity": 50,
            "quantityLimit": 100
        },
        {
            "id": "771fa622-g41d-63f6-c938-668877662222",
            "name": "Potion",
            "description": null,
            "type": "CUSTOM",
            "flags": ["INSTANT_USE", "IN_CHEST"],
            "emoji": "🧪",
            "emojiType": "UNICODE",
            "iconURL": null,
            "buyPrice": 200,
            "sellPrice": 0,
            "cooldown": 0,
            "durability": 0,
            "quantity": null,
            "quantityLimit": null
        }
    ]
}
```

#### Add Items to a Member <a href="#add-items-to-a-member" id="add-items-to-a-member"></a>

```http
POST guilds/{guildID}/users/{userID}/items
```

Adds a quantity of an item to the member's inventory.

**Request Body**

| Field                                       | Type     | Description                                  | Default |
| ------------------------------------------- | -------- | -------------------------------------------- | ------- |
| itemID <mark style="color:red;">\*</mark>   | `string` | UUID of the item to add.                     | —       |
| quantity <mark style="color:red;">\*</mark> | `number` | Quantity to add. Min: `1`. Max: `1,000,000`. | —       |

**Response Fields**

| Field    | Type     | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| quantity | `number` | New quantity of the item in the user's inventory. |

```json
{
    "quantity": 5
}
```

***

#### Remove Items from a Member <a href="#remove-items-from-a-member" id="remove-items-from-a-member"></a>

```http
DELETE guilds/{guildID}/users/{userID}/items
```

Removes a quantity of an item from the member's inventory. If the resulting quantity falls to `0` or below, the item is deleted from the inventory entirely.

**Request Body**

| Field                                       | Type     | Description                                     | Default |
| ------------------------------------------- | -------- | ----------------------------------------------- | ------- |
| itemID <mark style="color:red;">\*</mark>   | `string` | UUID of the item to remove.                     | —       |
| quantity <mark style="color:red;">\*</mark> | `number` | Quantity to remove. Min: `1`. Max: `1,000,000`. | —       |

**Response Fields**

| Field    | Type     | Description                       |
| -------- | -------- | --------------------------------- |
| quantity | `number` | New quantity of the item (≥ `0`). |

```json
{
    "quantity": 2
}
```

***

#### Set Item Quantity for a Member <a href="#set-item-quantity-for-a-member" id="set-item-quantity-for-a-member"></a>

```http
PUT guilds/{guildID}/users/{userID}/items
```

Sets the exact quantity of an item in the member's inventory. Passing `0` removes the item entirely.

**Request Body**

| Field                                           | Type     | Description                                  | Default |
| ----------------------------------------------- | -------- | -------------------------------------------- | ------- |
| itemID <mark style="color:$danger;">\*</mark>   | `string` | UUID of the item.                            | —       |
| quantity <mark style="color:$danger;">\*</mark> | `number` | Target quantity. Min: `0`. Max: `1,000,000`. | —       |

**Response Fields**

| Field    | Type     | Description                |
| -------- | -------- | -------------------------- |
| quantity | `number` | The quantity that was set. |

```json
{
    "quantity": 10
}
```

***

#### Use an Item <a href="#use-an-item" id="use-an-item"></a>

```http
POST guilds/{guildID}/users/{userID}/items/{itemID}/use
```

Triggers the item's actions (give/remove money, XP, roles, other items…). Only works for items of type `CUSTOM` with at least one action configured. The item is consumed from the inventory unless it has the `KEEP_AFTER_USE` flag.

**Request Body**

| Field    | Type     | Description                                 | Default |
| -------- | -------- | ------------------------------------------- | ------- |
| quantity | `number` | Number of uses. Min: `1`. Max: `1,000,000`. | `1`     |

**Response Fields**

| Field         | Type                     | Description                                                      |
| ------------- | ------------------------ | ---------------------------------------------------------------- |
| xp            | `number`                 | Total XP awarded (negative if removed).                          |
| money         | `number`                 | Total money awarded (negative if removed).                       |
| addedRoles    | `string[]`               | Role IDs added to the member.                                    |
| removedRoles  | `string[]`               | Role IDs removed from the member.                                |
| addedItems    | `Record<string, number>` | Map of item UUID → quantity added.                               |
| itemsRemoved  | `Record<string, number>` | Map of item UUID → quantity removed.                             |
| addedChests   | `Record<string, number>` | Map of chest UUID → quantity added.                              |
| chestsRemoved | `Record<string, number>` | Map of chest UUID → quantity removed.                            |
| rolesDuration | `Record<string, number>` | Map of role ID → Unix timestamp when the temporary role expires. |

```json
{
    "xp": 250,
    "money": 500,
    "addedRoles": ["845437147925446696"],
    "removedRoles": [],
    "addedItems": {},
    "itemsRemoved": {},
    "addedChests": {},
    "chestsRemoved": {},
    "rolesDuration": {
        "845437147925446696": 1440
    }
}
```