<!-- source: docs/api/2_capi/useritems/awarduseritem.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/awarduseritem -->

# AwardUserItem

Allows item(s) to be awarded to a user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.

> **Note:** Awarding 0 or negative userItem will return an error. Use <code>[DropUserItme](/api/capi/useritems/dropuseritem)</code> to remove usertem.

> **Caution:** For security reasons calling this API from the client is not recommended, and is rejected at the server by default. To over-ride, enable the 'Allow AwardUserItem to be called from client (not recommended)' compatibility setting in the Design Portal.

| Service | Operation |
| ------- | --------- |
| userItems | AWARD_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
defId | The unique id of the item definition to award. 
quantity | The quantity of the item to award. 
includeDef | If true, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string defId = "sword001";
int quantity = 1;
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.awardUserItem(defId, quantity, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *defId = "sword001";
int quantity = 1;
bool includeDef = true;
_bc->getUserItemsService()->awardUserItem(defId, quantity, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *idefId = "sword001";
int quantity = 1;
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] awardUserItem:defId
                   quantity:quantity
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String defId = "sword001";
int quantity = 1;
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().awardUserItem(defId, quantity, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var defId = "sword001";
var quantity = 1;
var includeDef = true;

_bc.userItems.awardUserItem(defId, quantity, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  defId = "sword001";
var  quantity = 1;
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.awardUserItem(defId:defId, quantity:quantity, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local defId = "sword001"
local quantity = 1
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:awardUserItem(defId, quantity, includeDef, callback)
```

**GDScript:**

```gdscript
var def_id = "sword001"
var quantity = 1
var include_def = true

var result = await _bc.user_items_service.award_user_item(def_id, quantity, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local defId = "sword001"
local quantity = 1
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:awardUserItem(defId, quantity, includeDef, callback)
```

**Cloud Code:**

```cfscript
var defId = "sword001";
var quantity = 1;
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.awardUserItem(defId, quantity, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "DROP_USER_ITEM",
    "data": {
        "defId": "sword001",
        "quantity": 1,
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "items": {
            "d01c70b8-b1a1-457e-ba14-dd52909ffc4a": {
                "itemId": "d01c70b8-b1a1-457e-ba14-dd52909ffc4a",
                "defId": "medal_bronze_1",
                "quantity": 1,
                "usesLeft": null,
                "coolDownStart": -1,
                "recoveryStart": -1,
                "itemData": {
                    "exp": 0
                },
                "giftedTo": null,
                "giftedFrom": null,
                "blockId": null,
                "createdAt": 1566847876350,
                "updatedAt": 1566847876350,
                "version": 1,
                "maxUses": null,
                "coolDownUntil": -1,
                "recoveryUntil": -1,
                "itemDef": {
                    "defId": "medal_bronze_1",
                    "name": "Small Bronze Medal",
                    "desc": "",
                    "type": "ITEM",
                    "category": "collectable",
                    "tags": [
                        "medal"
                    ],
                    "buyPrice": {
                        "coins": 2000
                    },
                    "sellPrice": {
                        "coins": 200
                    },
                    "image": "https://api.braincloudservers.com/files/portal/g/00000/metadata/itemDefinitions/medal_bronze_1.png",
                    "resourceGroup": null,
                    "resourceTag": null,
                    "meta": {
                        "level": "bronze"
                    },
                    "pState": "PUBLISHED",
                    "publishedAt": 1566584361752,
                    "stackable": true,
                    "consumable": false,
                    "uses": null,
                    "coolDownSecs": 0,
                    "recoverySecs": 0,
                    "activatable": false,
                    "statusName": null,
                    "activeSecs": null,
                    "tradable": false,
                    "blockchain": false,
                    "blockchainDefId": null
                }
            }
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/awarduseritemwithoptions.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/awarduseritemwithoptions -->

# AwardUserItemWithOptions
Allows item(s) to be awarded to a user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | AWARD_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
defId | The unique id of the item definition to award.
quantity | The quantity of the item to award.
includeDef | If true, the associated item definition will be included in the response.
optionsJson | Optional support for specifying 'blockIfExceedItemMaxStackable' indicating how to process the award if the defId is for a stackable item with a max stackable quantity and the specified quantity to award is too high. If true and the quantity is too high, the call is blocked and an error is returned. If false (default) and quantity is too high, the quantity is adjusted to the allowed maximum and the quantity not awarded is reported in response key 'itemsNotAwarded' - unless the adjusted quantity would be 0, in which case the call is blocked and an error is returned.

## Usage

**C#:**

```csharp
string defId = "sword001";
int quantity = 1;
bool includeDef = True;
string optionsJson = "{\"blockIfExceedItemMaxStackable\": False}";

SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UseritemsService.AwardUserItemWithOptions(defId, quantity, includeDef, optionsJson, successCallback, failureCallback);
```

**C++:**

```cpp
const char *defId = "sword001";
int quantity = 1;
bool includeDef = True;
const char *optionsJson = "{\"blockIfExceedItemMaxStackable\": False}";
_bc.getUseritemsService().awardUserItemWithOptions(defId, quantity, includeDef, optionsJson, this);
```

**Obj-C:**

```objectivec
NSString *defId = @"sword001";
int quantity = 1;
BOOL includeDef = True;
NSString *optionsJson = @"{\"blockIfExceedItemMaxStackable\": False}";
BCCompletionBlock successBlock; // define callback
BCErrorCompletionBlock failureBlock; // define callback
[[_bc userItemsService] awardUserItemWithOptions:
                        defId:defId
                     quantity:quantity
                   includeDef:includeDef
                  optionsJson:optionsJson
              completionBlock:successBlock
         errorCompletionBlock:failureBlock
                     cbObject:nil]
```

**Java:**

```java
String defId = "sword001";
int quantity = 1;
bool includeDef = True;
String optionsJson = "{\"blockIfExceedItemMaxStackable\": False}";
this; // implements IServerCallback
_bc.getUseritemsService.awardUserItemWithOptions(defId, quantity, includeDef, optionsJson, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var defId = "sword001";
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
_bc.userItems.awardUserItemWithOptions(defId, quantity, includeDef, optionsJson, result =>
{
  var status = result.status;
  console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var defId = "sword001";
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
ServerResponse result = await _bc.userItemsService.awardUserItemWithOptions(defId:defId, quantity:quantity, includeDef:includeDef, optionsJson:optionsJson);

if (result.statusCode == 200) {
    print("Success");    
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local defId = "sword001"
local quantity = 1
local includeDef = True
local optionsJson = {
    blockIfExceedItemMaxStackable = false
}

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:awardUserItemWithOptions(defId, quantity, includeDef, optionsJson, callback)
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
local defId = "sword001"
local quantity = 1
local includeDef = true
local optionsJson = { blockIfExceedItemMaxStackable = false }

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:awardUserItemWithOptions(defId, quantity, includeDef, optionsJson, callback)
```

**Cloud Code:**

```cfscript
var defId = "sword001";
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.awardUserItemWithOptions(defId, quantity, includeDef, optionsJson);
```

**Raw:**

```r
{
    "service":"userItems",
    "operation":"AWARD_USER_ITEM",
    "data":{
        "defId":"sword001",
        "quantity":1,
        "includeDef":true,
        "optionsJson":{
            "blockIfExceedItemMaxStackable":false
        }
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "items": {
            "3f980b72-e9b0-421c-a23b-09f4a297432f": {
                "itemId": "3f980b72-e9b0-421c-a23b-09f4a297432f",
                "defId": "sword001",
                "type": "ITEM",
                "quantity": 1,
                "itemData": {},
                "giftedTo": null,
                "giftedFrom": null,
                "createdAt": 1763999328116,
                "updatedAt": 1763999328116,
                "version": 1,
                "usesLeft": null,
                "coolDownStart": -1,
                "recoveryStart": -1,
                "maxUses": null,
                "coolDownUntil": -1,
                "recoveryUntil": -1,
                "itemDef": {
                    "defId": "sword001",
                    "name": "crimson sword",
                    "desc": "a sword whose blade is forged in...",
                    "type": "ITEM",
                    "category": "sword",
                    "tags": [
                        "sword",
                        "crimson",
                        "pointy"
                    ],
                    "buyPriceDisabled": false,
                    "buyPrice": {
                        "coins": 200
                    },
                    "sellPrice": {
                        "coins": 200
                    },
                    "image": null,
                    "resourceGroup": "equipment.asset",
                    "resourceTag": "sword001",
                    "meta": null,
                    "pState": "PUBLISHED",
                    "publishedAt": 1763999316395,
                    "stackable": true,
                    "maxStackable": null,
                    "tradable": false,
                    "blockchain": false,
                    "consumable": false,
                    "uses": null,
                    "coolDownSecs": 0,
                    "recoverySecs": 0,
                    "activatable": false,
                    "statusName": null,
                    "activeSecs": null,
                    "maxActiveSecs": null,
                    "statusBehaviour": null
                }
            }
        }
    },
    "status": 200
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/dropuseritem.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/dropuseritem -->

# DropUserItem

Allows a quantity of a specified user item to be dropped, without any recovery of the money paid for the item. If any quantity of the user item remains, it will be returned, potentially with the associated itemDef (with language fields limited to the current or default language).

| Service | Operation |
| ------- | --------- |
| userItems | DROP_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the user item. 
quantity | The quantity of the user item to drop. 
includeDef | If true and any quantity of the user item remains, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
int quantity = 1;
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.DropUserItem(itemId, quantity, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
int quantity = 1;
bool includeDef = true;
_bc->getUserItemsService()->dropUserItem(itemId, quantity, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
int quantity = 1;
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] dropUserItem:itemId
                   quantity:quantity
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
int quantity = 1;
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().dropUserItem(itemId, quantity, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var quantity = 1;
var includeDef = true;

_bc.userItems.dropUserItem(itemId, quantity, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  itemId = "aaa-bbb-ccc-ddd";
var  quantity = 1;
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.dropUserItem(itemId:itemId, quantity:quantity, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local quantity = 1
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:dropUserItem(itemId, quantity, includeDef, callback)
```

**GDScript:**

```gdscript
var item_id = "aaa-bbb-ccc-ddd"
var quantity = 1
var include_def = true

var result = await _bc.user_items_service.drop_user_item(item_id, quantity, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local quantity = 1
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:dropUserItem(itemId, quantity, includeDef, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var quantity = 1;
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.dropUserItem(itemId, quantity, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "DROP_USER_ITEM",
    "data": {
        "itemId": "aaa-bbb-ccc-ddd",
        "quantity": 1,
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "item": {}
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/getitempromotiondetails.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/getitempromotiondetails -->

# GetItemPromotionDetails
Returns list of promotional details for the specified item definition, for promotions available to the current user.

| Service | Operation |
| ------- | --------- |
| userItems | GET_ITEM_PROMOTION_DETAILS |

## Method Parameters
Parameter | Description
--------- | -----------
defId | The unique id of the item definition to check.
shopId | The id identifying the store the item is from, if applicable.
includeDef | If true, the associated item definition will be included in the response.
includePromotionDetails | If true, the promotion details will be included in the response.

## Usage

**C#:**

```csharp
string defId = "sword001";
string shopId = "None";
bool includeDef = True;
bool includePromotionDetails = True;

SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UseritemsService.GetItemPromotionDetails(defId, shopId, includeDef, includePromotionDetails, successCallback, failureCallback);
```

**C++:**

```cpp
const char *defId = "sword001";
const char *shopId = "None";
bool includeDef = True;
bool includePromotionDetails = True;
_bc.getUseritemsService().getItemPromotionDetails(defId, shopId, includeDef, includePromotionDetails, this);
```

**Obj-C:**

```objectivec
NSString *defId = @"sword001";
NSString *shopId = @"None";
BOOL includeDef = True;
BOOL includePromotionDetails = True;
BCCompletionBlock successBlock; // define callback
BCErrorCompletionBlock failureBlock; // define callback
[[_bc userItemsService] getItemPromotionDetails:
                        defId:defId
                       shopId:shopId
                   includeDef:includeDef
      includePromotionDetails:includePromotionDetails
              completionBlock:successBlock
         errorCompletionBlock:failureBlock
                     cbObject:nil]
```

**Java:**

```java
String defId = "sword001";
String shopId = "None";
bool includeDef = True;
bool includePromotionDetails = True;
this; // implements IServerCallback
_bc.getUseritemsService.getItemPromotionDetails(defId, shopId, includeDef, includePromotionDetails, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var defId = "sword001";
var shopId = "None";
var includeDef = True;
var includePromotionDetails = True;
_bc.userItems.getItemPromotionDetails(defId, shopId, includeDef, includePromotionDetails, result =>
{
  var status = result.status;
  console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var defId = "sword001";
var shopId = "None";
var includeDef = True;
var includePromotionDetails = True;
ServerResponse result = await _bc.userItemsService.getItemPromotionDetails(defId:defId, shopId:shopId, includeDef:includeDef, includePromotionDetails:includePromotionDetails);

if (result.statusCode == 200) {
    print("Success");    
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local defId = "sword001"
local shopId = "None"
local includeDef = True
local includePromotionDetails = True

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getItemPromotionDetails(defId, shopId, includeDef, includePromotionDetails, callback)
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
local defId = "sword001"
local shopId = "None"
local includeDef = true
local includePromotionDetails = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getItemPromotionDetails(defId, shopId, includeDef, includePromotionDetails, callback)
```

**Cloud Code:**

```cfscript
var defId = "sword001";
var shopId = "None";
var includeDef = True;
var includePromotionDetails = True;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.getItemPromotionDetails(defId, shopId, includeDef, includePromotionDetails);
```

**Raw:**

```r
{
    "service":"userItems",
    "operation":"GET_ITEM_PROMOTION_DETAILS",
    "data":{
        "defId":"sword001",
        "shopId":null,
        "includeDef":true,
        "includePromotionDetails":true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "itemDef": {
            "defId": "s001",
            "name": "Sword",
            "desc": "weapon",
            "type": "ITEM",
            "category": "weapon",
            "tags": null,
            "buyPriceDisabled": false,
            "buyPrice": {
                "bar": 88
            },
            "sellPrice": {},
            "image": null,
            "resourceGroup": null,
            "resourceTag": null,
            "meta": null,
            "pState": "PUBLISHED",
            "publishedAt": 1713324249793,
            "stackable": true,
            "maxStackable": 1,
            "tradable": false,
            "blockchain": false,
            "consumable": false,
            "uses": null,
            "coolDownSecs": 0,
            "recoverySecs": 0,
            "activatable": false,
            "statusName": null,
            "activeSecs": null,
            "maxActiveSecs": null,
            "statusBehaviour": null
        },
        "promotions": [
            {
                "gameId": "23782",
                "promotionId": 1,
                "type": "AUTOMATED",
                "name": "test",
                "message": "test",
                "enabled": true,
                "segments": [
                    1
                ],
                "prices": [
                    {
                        "itemId": "comearmarkcpeappunlimited",
                        "priceId": 0
                    }
                ],
                "notifications": [],
                "duration": 10,
                "customJson": {
                    "priority": 100,
                    "itemIds": {
                        "barBundle1Imp": {
                            "currency": {
                                "bars": 12
                            },
                            "extra": {
                                "specialItemReward": "bonusItemA"
                            }
                        },
                        "gemcollection": {
                            "currency": {
                                "gems": 7
                            },
                            "extra": {
                                "specialItemReward": "bonusItemA"
                            }
                        }
                    }
                },
                "isRetriggerable": true,
                "maxRetriggers": null,
                "maxPurchases": null,
                "createdAt": 1612991666850,
                "updatedAt": 1764000936099,
                "version": 8,
                "items": {
                    "s001": {
                        "defId": "s001",
                        "buyPrice": {
                            "bar": 44
                        }
                    }
                },
                "triggeredForUserAt": 1764000265580,
                "expiresForUserAt": 1764036265580
            }
        ]
    },
    "status": 200
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/getitemsonpromotion.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/getitemsonpromotion -->

# GetItemsOnPromotion
Returns all catalog items for which the current user has an eligible promotion, with optional support to filter on a specific 'category'. For each item, the most recently started promotion is considered the 'winning' promotion, if more than one promotion is active at the same time with a promotional price for same item. Optionally include the catalog item definition for each item and the promotion details for all 'winning' promotions.

| Service | Operation |
| ------- | --------- |
| userItems | GET_ITEMS_ON_PROMOTION |

## Method Parameters
Parameter | Description
--------- | -----------
shopId | The id identifying the store the item is from, if applicable.
includeDef | If true, the associated item definition info of the promotional items will be included in the response.
includePromotionDetails | If true, the promotion details of the eligible promotions will be included in the response.
optionsJson | Optional support for specifying additional options. Currently supporting option 'category' to include only catalog items configured with the specified category, if desired.

## Usage

**C#:**

```csharp
string shopId = "None";
bool includeDef = True;
bool includePromotionDetails = True;
string optionsJson = "{\"category\": \"Equipment\"}";

SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UseritemsService.GetItemsOnPromotion(shopId, includeDef, includePromotionDetails, optionsJson, successCallback, failureCallback);
```

**C++:**

```cpp
const char *shopId = "None";
bool includeDef = True;
bool includePromotionDetails = True;
const char *optionsJson = "{\"category\": \"Equipment\"}";
_bc.getUseritemsService().getItemsOnPromotion(shopId, includeDef, includePromotionDetails, optionsJson, this);
```

**Obj-C:**

```objectivec
NSString *shopId = @"None";
BOOL includeDef = True;
BOOL includePromotionDetails = True;
NSString *optionsJson = @"{\"category\": \"Equipment\"}";
BCCompletionBlock successBlock; // define callback
BCErrorCompletionBlock failureBlock; // define callback
[[_bc userItemsService] getItemsOnPromotion:
                       shopId:shopId
                   includeDef:includeDef
      includePromotionDetails:includePromotionDetails
                  optionsJson:optionsJson
              completionBlock:successBlock
         errorCompletionBlock:failureBlock
                     cbObject:nil]
```

**Java:**

```java
String shopId = "None";
bool includeDef = True;
bool includePromotionDetails = True;
String optionsJson = "{\"category\": \"Equipment\"}";
this; // implements IServerCallback
_bc.getUseritemsService.getItemsOnPromotion(shopId, includeDef, includePromotionDetails, optionsJson, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var shopId = "None";
var includeDef = True;
var includePromotionDetails = True;
var optionsJson = {
    "category": "Equipment"
};
_bc.userItems.getItemsOnPromotion(shopId, includeDef, includePromotionDetails, optionsJson, result =>
{
  var status = result.status;
  console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var shopId = "None";
var includeDef = True;
var includePromotionDetails = True;
var optionsJson = {
    "category": "Equipment"
};
ServerResponse result = await _bc.userItemsService.getItemsOnPromotion(shopId:shopId, includeDef:includeDef, includePromotionDetails:includePromotionDetails, optionsJson:optionsJson);

if (result.statusCode == 200) {
    print("Success");    
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local shopId = "None"
local includeDef = True
local includePromotionDetails = True
local optionsJson = {
    category = "Equipment"
}

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getItemsOnPromotion(shopId, includeDef, includePromotionDetails, optionsJson, callback)
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
local shopId = "None"
local includeDef = true
local includePromotionDetails = true
local optionsJson = { category = "Equipment" }

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getItemsOnPromotion(shopId, includeDef, includePromotionDetails, optionsJson, callback)
```

**Cloud Code:**

```cfscript
var shopId = "None";
var includeDef = True;
var includePromotionDetails = True;
var optionsJson = {
    "category": "Equipment"
};
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.getItemsOnPromotion(shopId, includeDef, includePromotionDetails, optionsJson);
```

**Raw:**

```r
{
    "service":"userItems",
    "operation":"GET_ITEMS_ON_PROMOTION",
    "data":{
        "shopId":null,
        "includeDef":true,
        "includePromotionDetails":true,
        "optionsJson":{
            "category":"Equipment"
        }
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "items": [
            {
                "defId": "s001",
                "itemDef": {
                    "resourceGroup": null,
                    "sellPrice": {},
                    "type": "ITEM",
                    "coolDownSecs": 0,
                    "recoverySecs": 0,
                    "statusName": null,
                    "buyPrice": {
                        "bar": 88
                    },
                    "image": null,
                    "stackable": true,
                    "publishedAt": 1713324249793,
                    "pState": "PUBLISHED",
                    "activatable": false,
                    "tags": null,
                    "defId": "s001",
                    "maxStackable": 1,
                    "blockchain": false,
                    "meta": null,
                    "consumable": false,
                    "name": {
                        "en": "Sword"
                    },
                    "tradable": false,
                    "resourceTag": null,
                    "uses": null,
                    "_id": {
                        "timestamp": 1711508420,
                        "date": 1711508420000
                    },
                    "activeSecs": null,
                    "category": "weapon",
                    "desc": {
                        "en": "weapon"
                    }
                },
                "winningPromotionId": 1,
                "promotionPrices": [
                    {
                        "promotionPrice": {
                            "bar": 44
                        },
                        "name": "test",
                        "type": "AUTOMATED",
                        "promotionId": 1
                    }
                ]
            }
        ],
        "promotionDetails": [
            {
                "promotionId": 1,
                "type": "AUTOMATED",
                "name": "test",
                "duration": 10,
                "customJson": {
                    "priority": 100,
                    "itemIds": {
                        "barBundle1Imp": {
                            "currency": {
                                "bars": 12
                            },
                            "extra": {
                                "specialItemReward": "bonusItemA"
                            }
                        },
                        "gemcollection": {
                            "currency": {
                                "gems": 7
                            },
                            "extra": {
                                "specialItemReward": "bonusItemA"
                            }
                        }
                    }
                },
                "isRetriggerable": true,
                "maxRetriggers": null,
                "maxPurchases": null,
                "triggeredForUserAt": 1764353888374,
                "expiresForUserAt": 1764389888374
            }
        ]
    },
    "status": 200
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/getuseritem.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/getuseritem -->

# GetUserItem

Retrieves the identified user item from the server. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | GET_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the user item. 
includeDef | If true, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.GetUserItem(itemId, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
bool includeDef = true;
_bc->getUserItemsService()->getUserItem(itemId, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] getUserItem:itemId
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().getUserItem(itemId, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var includeDef = true;

_bc.userItems.getUserItem(itemId, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  itemId = "aaa-bbb-ccc-ddd";
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.getUserItem(itemId:itemId, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getUserItem(itemId, includeDef, callback)
```

**GDScript:**

```gdscript
var item_id = "aaa-bbb-ccc-ddd"
var include_def = true

var result = await _bc.user_items_service.get_user_item(item_id, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getUserItem(itemId, includeDef, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.getUserItem(itemId, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "GET_USER_ITEM",
    "data": {
        "itemId": "aaa-bbb-ccc-ddd",
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "item": {
            "itemId": "2f100f95-60cd-436e-b973-e33cbc6b3728",
            "defId": "medal_bronze_2",
            "quantity": 1,
            "usesLeft": null,
            "coolDownStart": -1,
            "recoveryStart": -1,
            "itemData": {},
            "giftedTo": null,
            "giftedFrom": null,
            "blockId": null,
            "createdAt": 1566849320462,
            "updatedAt": 1566849320462,
            "version": 1,
            "maxUses": null,
            "coolDownUntil": -1,
            "recoveryUntil": -1,
            "itemDef": {
                "defId": "medal_bronze_2",
                "name": "Medium Bronze Medal",
                "desc": "",
                "type": "ITEM",
                "category": "collectable",
                "tags": [
                    "medal"
                ],
                "buyPrice": {},
                "sellPrice": {},
                "image": null,
                "resourceGroup": null,
                "resourceTag": null,
                "meta": {},
                "pState": "PUBLISHED",
                "publishedAt": 1566585957049,
                "stackable": false,
                "consumable": false,
                "uses": null,
                "coolDownSecs": 0,
                "recoverySecs": 0,
                "activatable": false,
                "statusName": null,
                "activeSecs": null,
                "tradable": false,
                "blockchain": false,
                "blockchainDefId": null
            }
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/getuseritemspage.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/getuseritemspage -->

# GetUserItemsPage

Retrieves the page of user's inventory from the server based on the context. If includeDef is true, response includes associated itemDef with each user item, with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | GET_USER_ITEMS_PAGE |

## Method Parameters
Parameter | Description
--------- | -----------
context | The json context for the page request. 
includeDef | If true, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string context = "{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"defId\":\"sword001\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.GetUserItemsPage(context, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *context = "{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"defId\":\"sword001\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";
bool includeDef = true;
_bc->getUserItemsService()->getUserItemsPage(context, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *context = "{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"defId\":\"sword001\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] getUserItemsPage:context
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String context = "{\"pagination\":{\"rowsPerPage\":50,\"pageNumber\":1},\"searchCriteria\":{\"defId\":\"sword001\"},\"sortCriteria\":{\"createdAt\":1,\"updatedAt\":-1}}";
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().getUserItemsPage(context, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var context = {
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1
  },
  "searchCriteria": {
    "defId": "sword001"
  },
  "sortCriteria": {
    "createdAt": 1,
    "updatedAt": -1
  }
};
var includeDef = true;

_bc.userItems.getUserItemsPage(context, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  context = {
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1
  },
  "searchCriteria": {
    "defId": "sword001"
  },
  "sortCriteria": {
    "createdAt": 1,
    "updatedAt": -1
  }
};
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.getUserItemsPage(context:context, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local context = {
  pagination = {
    rowsPerPage = 50,
    pageNumber = 1
  },
  searchCriteria = {
    defId = "sword001"
  },
  sortCriteria = {
    createdAt = 1,
    updatedAt = -1
  }
}
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getUserItemsPage(context, includeDef, callback)
```

**GDScript:**

```gdscript
var context = {
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1
  },
  "searchCriteria": {
    "defId": "sword001"
  },
  "sortCriteria": {
    "createdAt": 1,
    "updatedAt": -1
  }
}
var include_def = true

var result = await _bc.user_items_service.get_user_items_page(context, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local context = {
    pagination = { rowsPerPage = 50, pageNumber = 1 },
    searchCriteria = { defId = "sword001" },
    sortCriteria = { createdAt = 1, updatedAt = -1 }
}
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getUserItemsPage(context, includeDef, callback)
```

**Cloud Code:**

```cfscript
var context = {
  "pagination": {
    "rowsPerPage": 50,
    "pageNumber": 1
  },
  "searchCriteria": {
    "defId": "sword001"
  },
  "sortCriteria": {
    "createdAt": 1,
    "updatedAt": -1
  }
};
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.getUserItemsPage(context, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "GET_USER_ITEMS_PAGE",
    "data": {
        "context": {
            "pagination": {
                "rowsPerPage": 50,
                "pageNumber": 1
            },
            "searchCriteria": {
                "defId": "sword001"
            },
            "sortCriteria": {
                "createdAt": 1,
                "updatedAt": -1
            }
        },
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "context": "eyJzZWFyY2hDcml0ZXJpYSI6eyJnYW1lSWQiOiIyMzQwMyIsInBsYXllcklkIjoiOGNlNmU0NzUtMzVhOS00MmY2LWJhMDgtMjA2YmQwNzY1MGNhIiwiZ2lmdGVkVG8iOm51bGx9LCJzb3J0Q3JpdGVyaWEiOnsiY3JlYXRlZEF0IjoxLCJ1cGRhdGVkQXQiOi0xfSwicGFnaW5hdGlvbiI6eyJyb3dzUGVyUGFnZSI6NTAsInBhZ2VOdW1iZXIiOjF9LCJvcHRpb25zIjpudWxsfQ",
        "results": {
            "count": 1,
            "page": 1,
            "items": [
                {
                    "itemId": "2f100f95-60cd-436e-b973-e33cbc6b3728",
                    "defId": "medal_bronze_2",
                    "quantity": 1,
                    "usesLeft": null,
                    "coolDownStart": -1,
                    "recoveryStart": -1,
                    "itemData": {},
                    "giftedTo": null,
                    "giftedFrom": null,
                    "blockId": null,
                    "createdAt": 1566849320462,
                    "updatedAt": 1566849320462,
                    "version": 1,
                    "maxUses": null,
                    "coolDownUntil": -1,
                    "recoveryUntil": -1,
                    "itemDef": {
                        "defId": "medal_bronze_2",
                        "name": "Medium Bronze Medal",
                        "desc": "",
                        "type": "ITEM",
                        "category": "collectable",
                        "tags": [
                            "medal"
                        ],
                        "buyPrice": {},
                        "sellPrice": {},
                        "image": null,
                        "resourceGroup": null,
                        "resourceTag": null,
                        "meta": {},
                        "pState": "PUBLISHED",
                        "publishedAt": 1566585957049,
                        "stackable": false,
                        "consumable": false,
                        "uses": null,
                        "coolDownSecs": 0,
                        "recoverySecs": 0,
                        "activatable": false,
                        "statusName": null,
                        "activeSecs": null,
                        "tradable": false,
                        "blockchain": false,
                        "blockchainDefId": null
                    }
                }
            ],
            "moreAfter": false,
            "moreBefore": false
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/getuseritemspageoffset.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/getuseritemspageoffset -->

# GetUserItemsPageOffset

Retrieves the page of user's inventory from the server based on the encoded context. If includeDef is true, response includes associated itemDef with each user item, with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | GET_USER_ITEMS_PAGE_OFFSET |

## Method Parameters
Parameter | Description
--------- | -----------
context | The context string returned from the server from a previous call to SysGetCatalogItemsPage or SysGetCatalogItemsPageOffset. 
pageOffset | The positive or negative page offset to fetch. Uses the last page retrieved using the context string to determine a starting point. 
includeDef | If true, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0";
int pageOffset = 1;
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.GetUserItemsPageOffset(context, pageOffset, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0";
int pageOffset = 1;
bool includeDef = true;
_bc->getUserItemsService()->getUserItemsPageOffset(context, pageOffset, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *context = @"eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0";
int pageOffset = 1;
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] getUserItemsPageOffset:context
                 pageOffset:pageOffset
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0";
int pageOffset = 1;
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().getUserItemsPageOffset(context, pageOffset, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0";
var pageOffset = 1;
var includeDef = true;

_bc.userItems.getUserItemsPageOffset(context, pageOffset, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0";
var  pageOffset = 1;
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.getUserItemsPageOffset(context:context, pageOffset:pageOffset, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0"
local pageOffset = 1
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getUserItemsPageOffset(context, pageOffset, includeDef, callback)
```

**GDScript:**

```gdscript
var context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0"
var page_offset = 1
var include_def = true

var result = await _bc.user_items_service.get_user_items_page_offset(context, page_offset, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0"
local pageOffset = 1
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:getUserItemsPageOffset(context, pageOffset, includeDef, callback)
```

**Cloud Code:**

```cfscript
var context = "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0";
var pageOffset = 1;
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.getUserItemsPageOffset(context, pageOffset, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "GET_USER_ITEMS_PAGE_OFFSET",
    "data": {
        "context": "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjp7IiRyZWdleCI6Ii4qaWxkLioiLCIkb3B0",
        "pageOffset": 1,
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "context": "eyJzZWFyY2hDcml0ZXJpYSI6eyJnYW1lSWQiOiIyMzQwMyIsInBsYXllcklkIjoiZW4iLCJnaWZ0ZWRUbyI6bnVsbH0sInNvcnRDcml0ZXJpYSI6eyJjcmVhdGVkQXQiOjEsInVwZGF0ZWRBdCI6LTF9LCJwYWdpbmF0aW9uIjp7InJvd3NQZXJQYWdlIjo1MCwicGFnZU51bWJlciI6Mn0sIm9wdGlvbnMiOm51bGx9",
        "results": {
            "count": 0,
            "page": 2,
            "items": [],
            "moreAfter": false,
            "moreBefore": false
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/giveuseritemto.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/giveuseritemto -->

# GiveUserItemTo

Gifts item to the specified player.

| Service | Operation |
| ------- | --------- |
| userItems | GIVE_USER_ITEM_TO |

## Method Parameters

| Parameter | Description                                                                                                                                                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| profileId | The ID of the recipient's user profile.                                                                                                                                           |
| itemId    | The ID uniquely identifying the user item to be transferred.                                                                                                                      |
| version   | The version of the user item being transferred.                                                                                                                                   |
| quantity  | The quantity of the user item to transfer.                                                                                                                                        |
| immediate | Flag set to true if item is to be immediately transferred, otherwise false to have the sender sents an event and transfers item(s) only when recipient calls receiveUserItemFrom. |

## Usage

**C#:**

```csharp
string profileId = "a-user-profileId";
string itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
bool immediate = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.GiveUserItemTo(profileId, itemId, version, quantity, immediate, successCallback, failureCallback);
```

**C++:**

```cpp
const char *profileId = "a-user-profileId";
const char *itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
bool immediate = true;
_bc->getUserItemsService()->giveUserItemTo(profileId, itemId, version, quantity, immediate, this);
```

**Obj-C:**

```objectivec
NSString *profileId = @"a-user-profileId";
NSString *itemId = @"aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
bool immediate = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] giveUserItemTo:profileId
                     itemId:itemId
                    version:version
                   quantity:quantity
                  immediate:immediate
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String profileId = "a-user-profileId";
String itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
boolean immediate = true;
this; // implements IServerCallback

_bc.getUserItemsService().giveUserItemTo(profileId, itemId, version, quantity, immediate, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var profileId = "a-user-profileId";
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var quantity = 1;
var immediate = true;

_bc.userItems.giveUserItemTo(profileId, itemId, version, quantity, immediate, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  profileId = "a-user-profileId";
var  itemId = "aaa-bbb-ccc-ddd";
var  version = 1;
var  quantity = 1;
var  immediate = true;

ServerResponse result = await _bc.userItemsService.giveUserItemTo(profileId:profileId, itemId:itemId, version:version, quantity:quantity, immediate:immediate);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local profileId = "a-user-profileId"
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local quantity = 1
local immediate = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:giveUserItemTo(profileId, itemId, version, quantity, immediate, callback)
```

**GDScript:**

```gdscript
var profile_id = "a-user-profileId"
var item_id = "aaa-bbb-ccc-ddd"
var version = 1
var quantity = 1
var immediate = true

var result = await _bc.user_items_service.give_user_item_to(profile_id, item_id, version, quantity, immediate)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local profileId = "a-user-profileId"
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local quantity = 1
local immediate = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:giveUserItemTo(profileId, itemId, version, quantity, immediate, callback)
```

**Cloud Code:**

```cfscript
var profileId = "a-user-profileId";
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var quantity = 1;
var immediate = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.giveUserItemTo(profileId, itemId, version, quantity, immediate);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "GIVE_USER_ITEM_TO",
    "data": {
        "profileId": "a-user-profileId",
        "itemId": "aaa-bbb-ccc-ddd",
        "version": 1,
        "quantity": 1,
        "immediate": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "item": {
            "itemId": "2f100f95-60cd-436e-b973-e33cbc6b3728",
            "defId": "medal_bronze_2",
            "quantity": 1,
            "usesLeft": null,
            "coolDownStart": -1,
            "recoveryStart": -1,
            "itemData": {},
            "giftedTo": "74516a07-4d56-4f0a-82b9-df941d451318",
            "giftedFrom": "8ce6e475-35a9-42f6-ba08-206bd07650ca",
            "blockId": null,
            "createdAt": 1566849320462,
            "updatedAt": 1566849606132,
            "version": 2,
            "maxUses": null,
            "coolDownUntil": -1,
            "recoveryUntil": -1,
            "itemDef": {}
        },
        "giftItemId": "b303c738-82bd-4ab2-9688-544d45104a85"
    },
    "status": 200
}
```

</details>
> **Tip:** 
> For **immediate**: _true_ gifting:
> 
> -   if the item was stackable and the sender has more quantity left, the “item” info in the response will indicate the status of that item (remaining quantity, etc.) after immediate gifting
> -   but if the senders item was deleted (not stackable or stackable and 0 quantity left) on the gifting, the “item” info will be empty to indicate this.
> 
> For **immediate**: _false_ gifting (can't be stackable):
> 
> -   the giftedTo field on the sender’s item would indicate the receiver’s profileId
> 

> **Note:** 
> -   If new item created — so for immediate and non-stackable — then the newly created item for the receiver would have the giftedFrom: **sendersProfileId** set.
> 
> -   If stackable item that receiver already has, just the receiver’s quantity of that stackable item will be incremented (no new user item created)
>


---

<!-- source: docs/api/2_capi/useritems/index.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems -->

# User Items

The **User Items** service, introduced in 4.2, is used to manage a collection of in-app items that users can be awarded, buy, sell, or trade (using virtual currency). Optionally, these items can be backed up to the blockchain.

Key concepts:

- Items are first defined in the **Item Catalog** 
- Defined items can be purchased or awarded to users, where they will be recorded as userItem instances.
- Using an item may consume it (or a portion of it - or none of it). Consumed items will automatically disappear from the user's user item inventory.
- Using an item may trigger a status effect (i.e. invulnerability for 60 seconds)
- Using an item may trigger a cool-down period (before the item can be used again) or a regeneration period (a period after which the item regenerates a "use.")

### API Summary

#### Read Items
* [GetUserItem](/api/capi/useritems/getuseritem) - Retrieves the identified user item from the server. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
* [GetUserItemsPage](/api/capi/useritems/getuseritemspage) - Retrieves the page of user's inventory from the server based on the context. If includeDef is true, response includes associated itemDef with each user item, with language fields limited to the current or default language.
* [GetUserItemsPageOffset](/api/capi/useritems/getuseritemspageoffset) - Retrieves the page of user's inventory from the server based on the encoded context. If includeDef is true, response includes associated itemDef with each user item, with language fields limited to the current or default language.
* [GetItemPromotionDetails](/api/capi/useritems/getitempromotiondetails) - Returns list of promotional details for the specified item definition, for promotions available to the current user.
* [GetItemsOnPromotion](/api/capi/useritems/getitemsonpromotion) - Returns all catalog items for which the current user has an eligible promotion, with optional support to filter on a specific 'category'. For each item, the most recently started promotion is considered the 'winning' promotion, if more than one promotion is active at the same time with a promotional price for same item. Optionally include the catalog item definition for each item and the promotion details for all 'winning' promotions.

#### Affect Item Owner

* [AwardUserItem](/api/capi/useritems/awarduseritem) - Allows item(s) to be awarded to a user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
* [AwardUserItemWithOptions](/api/capi/useritems/awarduseritemwithoptions) - Allows item(s) to be awarded to a user without collecting the purchase amount, with additional options.
* [DropUserItem](/api/capi/useritems/dropuseritem) - Allows a quantity of a specified user item to be dropped, without any recovery of the money paid for the item. If any quantity of the user item remains, it will be returned, potentially with the associated itemDef (with language fields limited to the current or default language).
* [SellUserItem](/api/capi/useritems/selluseritem) - Allows a quantity of a specified user item to be sold. If any quantity of the user item remains, it will be returned, potentially with the associated itemDef (with language fields limited to the current or default language), along with the currency refunded and currency balances.
* [GiveUserItemTo](/api/capi/useritems/giveuseritemto) - Gifts item to the specified player.
* [ReceiveUserItemFrom](/api/capi/useritems/receiveuseritemfrom) - Retrieves and transfers the gift item from the specified player, who must have previously called giveUserItemTo.
* [PurchaseUserItem](/api/capi/useritems/purchaseuseritem) - Purchases a quantity of an item from the specified store, if the user has enough funds. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
* [PurchaseUserItemWithOptions](/api/capi/useritems/purchaseuseritemwithoptions) - Purchases a quantity of an item from the specified store, if the user has enough funds and purchasing for listed buy price is not disabled (and no eligible promotion) for associated catalog item definition. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language. Additional 'optionsJson' to provide directives for processing, especially relevant for purchases involving stackable catalog items having a maxStackable.
* [SYS_AwardUserItemToUser](/api/capi/useritems/sysawarduseritemtouser) - Client cloud code only Sys API to allow item(s) to be awarded to the applicable user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
* [SYS_AwardUserItem](/api/capi/useritems/sysawarduseritem) - Client cloud code only call to allow item(s) to be awarded to the session user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
* [SYS_DropMyUserItems](/api/capi/useritems/sysdropmyuseritems) - Client cloud code only Sys API to drop the specified items from the session user's inventory without any recovery of the currency paid. Drops the full quantity of each item if dropMax is true, otherwise a quantity of 1.
* [SYS_DropAllMyUserItems](/api/capi/useritems/sysdropallmyuseritems) - Client cloud code only Sys API to drop every droppable item in the session user's inventory without any recovery of the currency paid.
* [OpenBundle](/api/capi/useritems/openbundle) - Allows a quantity of a specified bundle user item to be opened. Response indicates any items and currency awards configured for the associated bundle user item's BUNDLE type item definition, plus any 'items' awarded and any 'currencies' awarded, along with the resulting currency balances. If includeItemDef is true, the associated item definition will be included in the response for any user items awarded and for the bundle user item being opened (if any quantity of the bundle user item remains), with language fields limited to the current or default language.

#### Edit Item State
* [UseUserItem](/api/capi/useritems/useuseritem) - Uses the specified item, potentially consuming it.
* [UpdateUserItemData](/api/capi/useritems/updateuseritemdata) - Updates the item data on the specified user item.

#### Blockchain

* [PublishUserItemToBlockchain](/api/capi/useritems/publishuseritemtoblockchain) - Publishes the specified item to the item management attached blockchain. Results are reported asynchronously via an RTT event.
* [RemoveUserItemFromBlockchain](/api/capi/useritems/removeuseritemfromblockchain) - Removes the specified item from the item management attached blockchain. Results are reported asynchronously via an RTT event.
* [RefreshBlockchainUserItems](/api/capi/useritems/refreshblockchainuseritems) - Syncs the caller's user items with the item management attached blockchain. Results are reported asynchronously via an RTT event.


---

<!-- source: docs/api/2_capi/useritems/openbundle.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/openbundle -->

# OpenBundle
Allows a quantity of a specified bundle user item to be opened. Response indicates any items and currency awards configured for the associated bundle user item's BUNDLE type item definition, plus any 'items' awarded and any 'currencies' awarded, along with the resulting currency balances. If includeItemDef is true, the associated item definition will be included in the response for any user items awarded and for the bundle user item being opened (if any quantity of the bundle user item remains), with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | OPEN_BUNDLE |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the bundle user item.
version | The version of the bundle user item being sold. Accepts -1 if any version.
quantity | The quantity of the bundle user item to open.
includeDef | If true, the associated item definition will be included in the response for any user items awarded and if any quantity of the bundle user item remains.
optionsJson | Optional support for specifying 'blockIfExceedItemMaxStackable' indicating how to process awarding the bundle content items if the defId for any is for a stackable item with a max stackable quantity and the specified quantity to be awarded is too high. If true and the quantity is too high, the call is blocked and an error is returned. If false (default) and quantity is too high, the quantity is adjusted to the allowed maximum and the quantity not awarded is reported in response key 'itemsNotAwarded' - unless the adjusted quantity would be 0, in which case the call is blocked and an error is returned.

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
bool includeDef = True;
string optionsJson = "{\"blockIfExceedItemMaxStackable\": False}";

SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UseritemsService.OpenBundle(itemId, version, quantity, includeDef, optionsJson, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
bool includeDef = True;
const char *optionsJson = "{\"blockIfExceedItemMaxStackable\": False}";
_bc.getUseritemsService().openBundle(itemId, version, quantity, includeDef, optionsJson, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
BOOL includeDef = True;
NSString *optionsJson = @"{\"blockIfExceedItemMaxStackable\": False}";
BCCompletionBlock successBlock; // define callback
BCErrorCompletionBlock failureBlock; // define callback
[[_bc userItemsService] openBundle:
                       itemId:itemId
                      version:version
                     quantity:quantity
                   includeDef:includeDef
                  optionsJson:optionsJson
              completionBlock:successBlock
         errorCompletionBlock:failureBlock
                     cbObject:nil]
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
bool includeDef = True;
String optionsJson = "{\"blockIfExceedItemMaxStackable\": False}";
this; // implements IServerCallback
_bc.getUseritemsService.openBundle(itemId, version, quantity, includeDef, optionsJson, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
_bc.userItems.openBundle(itemId, version, quantity, includeDef, optionsJson, result =>
{
  var status = result.status;
  console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
ServerResponse result = await _bc.userItemsService.openBundle(itemId:itemId, version:version, quantity:quantity, includeDef:includeDef, optionsJson:optionsJson);

if (result.statusCode == 200) {
    print("Success");    
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local quantity = 1
local includeDef = True
local optionsJson = {
    blockIfExceedItemMaxStackable = false
}

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:openBundle(itemId, version, quantity, includeDef, optionsJson, callback)
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local quantity = 1
local includeDef = true
local optionsJson = { blockIfExceedItemMaxStackable = false }

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:openBundle(itemId, version, quantity, includeDef, optionsJson, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.openBundle(itemId, version, quantity, includeDef, optionsJson);
```

**Raw:**

```r
{
    "service":"userItems",
    "operation":"OPEN_BUNDLE",
    "data":{
        "itemId":"aaa-bbb-ccc-ddd",
        "version":1,
        "quantity":1,
        "includeDef":true,
        "optionsJson":{
            "blockIfExceedItemMaxStackable":false
        }
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "quantityOpened": 1,
        "itemsNotAwarded": {
            "s001": 6,
            "sword001": 8
        },
        "itemDef": {
            "defId": "s001b",
            "name": "s001b",
            "desc": "desp",
            "type": "BUNDLE",
            "category": "weapon",
            "tags": [
                "sword"
            ],
            "buyPriceDisabled": false,
            "buyPrice": {},
            "sellPrice": {},
            "image": null,
            "resourceGroup": null,
            "resourceTag": null,
            "meta": null,
            "pState": "PUBLISHED",
            "publishedAt": 1764001437452,
            "stackable": false,
            "maxStackable": null,
            "tradable": false,
            "blockchain": false,
            "autoOpen": false,
            "items": {
                "s001": {
                    "defId": "s001",
                    "quantity": 1
                },
                "sword001": {
                    "defId": "sword001",
                    "quantity": 1
                }
            }
        },
        "items": {}
    },
    "status": 200
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/publishuseritemtoblockchain.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/publishuseritemtoblockchain -->

# PublishUserItemToBlockchain

Publishes the specified item to the item management attached blockchain. Results are reported asynchronously via an RTT event.

| Service | Operation |
| ------- | --------- |
| userItems | PUBLISH_USER_ITEM_TO_BLOCKCHAIN |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the user item. 
version | The version of the user item being published. 

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
int version = 1;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.PublishUserItemToBlockchain(itemId, version, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
int version = 1;
_bc->getUserItemsService()->publishUserItemToBlockchain(itemId, version, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
int version = 1;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] publishUserItemToBlockchain:itemId
                    version:version
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
int version = 1;
this; // implements IServerCallback

_bc.getUserItemsService().publishUserItemToBlockchain(itemId, version, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;

_bc.userItems.publishUserItemToBlockchain(itemId, version, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  itemId = "aaa-bbb-ccc-ddd";
var  version = 1;

ServerResponse result = await _bc.userItemsService.publishUserItemToBlockchain(itemId:itemId, version:version);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:publishUserItemToBlockchain(itemId, version, callback)
```

**GDScript:**

```gdscript
var item_id = "aaa-bbb-ccc-ddd"
var version = 1

var result = await _bc.user_items_service.publish_user_item_to_blockchain(item_id, version)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:publishUserItemToBlockchain(itemId, version, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.publishUserItemToBlockchain(itemId, version);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "PUBLISH_USER_ITEM_TO_BLOCKCHAIN",
    "data": {
        "itemId": "aaa-bbb-ccc-ddd",
        "version": 1
    }
}
```


---

<!-- source: docs/api/2_capi/useritems/purchaseuseritem.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/purchaseuseritem -->

# PurchaseUserItem

Purchases a quantity of an item from the specified store, if the user has enough funds. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | PURCHASE_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
defId | The unique id of the item definition to purchase. 
quantity | The quantity of the item to purchase. 
shopId | The id identifying the store the item is being purchased from (not yet supported). Use null or empty string to specify the default shop price.
includeDef | If true, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string defId = "sword001";
int quantity = 1;
string shopId = "";
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.PurchaseUserItem(defId, quantity, shopId, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *defId = "sword001";
int quantity = 1;
const char *shopId = "";
bool includeDef = true;
_bc->getUserItemsService()->purchaseUserItem(defId, quantity, shopId, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *defId = @"sword001";
int quantity = 1;
NSString *shopId = @"";
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] purchaseUserItem:defId
                   quantity:quantity
                     shopId:shopId
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String defId = "sword001";
int quantity = 1;
String shopId = "";
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().purchaseUserItem(defId, quantity, shopId, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var defId = "sword001";
var quantity = 1;
var shopId = null;
var includeDef = true;

_bc.userItems.purchaseUserItem(defId, quantity, shopId, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  defId = "sword001";
var  quantity = 1;
var  shopId = null;
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.purchaseUserItem(defId:defId, quantity:quantity, shopId:shopId, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local defId = "sword001"
local quantity = 1
local shopId = nil
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:purchaseUserItem(defId, quantity, shopId, includeDef, callback)
```

**GDScript:**

```gdscript
var def_id = "sword001"
var quantity = 1
var shop_id = null
var include_def = true

var result = await _bc.user_items_service.purchase_user_item(def_id, quantity, shop_id, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local defId = "sword001"
local quantity = 1
local shopId = nil
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:purchaseUserItem(defId, quantity, shopId, includeDef, callback)
```

**Cloud Code:**

```cfscript
var defId = "sword001";
var quantity = 1;
var shopId = null;
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.purchaseUserItem(defId, quantity, shopId, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "PURCHASE_USER_ITEM",
    "data": {
        "defId": "sword001",
        "quantity": 1,
        "shopId": null,
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "items": {
            "8e12e907-3f54-4971-b84a-b685ce50b684": {
                "itemId": "8e12e907-3f54-4971-b84a-b685ce50b684",
                "defId": "boost_rapidfire",
                "quantity": 1,
                "usesLeft": null,
                "coolDownStart": -1,
                "recoveryStart": -1,
                "itemData": {},
                "giftedTo": null,
                "giftedFrom": null,
                "blockId": null,
                "createdAt": 1566850132554,
                "updatedAt": 1566850132554,
                "version": 1,
                "maxUses": null,
                "coolDownUntil": -1,
                "recoveryUntil": -1,
                "itemDef": {
                    "defId": "boost_rapidfire",
                    "name": "Rapid Fire",
                    "desc": "Rapid fire for the next match.",
                    "type": "ITEM",
                    "category": "boost",
                    "tags": null,
                    "buyPrice": {
                        "coins": 200
                    },
                    "sellPrice": {},
                    "image": null,
                    "resourceGroup": null,
                    "resourceTag": null,
                    "meta": {},
                    "pState": "PUBLISHED",
                    "publishedAt": 1566850042148,
                    "stackable": false,
                    "consumable": false,
                    "uses": null,
                    "coolDownSecs": 0,
                    "recoverySecs": 0,
                    "activatable": true,
                    "statusName": "boosted",
                    "activeSecs": 900000,
                    "tradable": false,
                    "blockchain": false,
                    "blockchainDefId": null
                }
            }
        },
        "currencySpent": {
            "coins": 200
        },
        "currencyBalances": {
            "createdAt": 1566850026783,
            "currencyMap": {
                "coins": {
                    "consumed": 200,
                    "balance": 2999800,
                    "purchased": 0,
                    "awarded": 3000000
                }
            },
            "playerId": "55ffc16e-f92b-44f3-98b0-68a7a4f24106",
            "updatedAt": 1566850132552
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/purchaseuseritemwithoptions.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/purchaseuseritemwithoptions -->

# PurchaseUserItemWithOptions
Purchases a quantity of an item from the specified store, if the user has enough funds and purchasing for listed buy price is not disabled (and no eligible promotion) for associated catalog item definition. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language. Additional 'optionsJson' to provide directives for processing, especially relevant for purchases involving stackable catalog items having a maxStackable (purchasing the catalog item directly or purchasing a BUNDLE type containing any such category items).

| Service | Operation |
| ------- | --------- |
| userItems | PURCHASE_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
defId | The unique id of the item definition to purchase.
quantity | The quantity of the item to purchase.
shopId | The id identifying the store the item is being purchased from, if applicable.
includeDef | If true, the associated item definition will be included in the response.
optionsJson | Optional support for specifying additional options, especially for purchases involving stackable items having a maxStackable limit. Option 'blockIfExceedItemMaxStackable' indicating how to process the purchase if the defId is for a stackable item with a max stackable quantity and the specified quantity being purchased is too high - If true and the quantity is too high, the call is blocked and an error is returned. If false (default) and quantity is too high, the quantity is adjusted to the allowed maximum and the quantity not purchased is reported in response key 'itemsNotPurchased' - unless the adjusted quantity would be 0, in which case the call is blocked and an error is returned. Option 'blockIfExceedContainedItemMaxStackable' (BUNDLE type only) - If true, fail the purchase if quantity of bundle content item would be in excess of its maxStackable IF the bundle were to be opened immediately (based on its currenct quantity). If false, just report the excess quantity for any item if the bundle were opened immediately.

## Usage

**C#:**

```csharp
// ITEM type
string defId = "StackableHealthPotion";
string optionsJson = "{\"blockIfExceedItemMaxStackable\": True}";

// BUNDLE type
// string defId = "BUNDLE001";
// string optionsJson = "{\"blockIfExceedItemMaxStackable\": True, \"blockIfExceedContainedItemMaxStackable\": False}";

int quantity = 1;
string shopId = "None";
bool includeDef = True;

SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UseritemsService.PurchaseUserItemWithOptions(defId, quantity, shopId, includeDef, optionsJson, successCallback, failureCallback);
```

**C++:**

```cpp
// ITEM type
const char *defId = "StackableHealthPotion";
const char *optionsJson = "{\"blockIfExceedItemMaxStackable\": True}";

// BUNDLE type
// const char *defId = "BUNDLE001";
// const char *optionsJson = "{\"blockIfExceedItemMaxStackable\": True, \"blockIfExceedContainedItemMaxStackable\": False}";

int quantity = 1;
const char *shopId = "None";
bool includeDef = True;
_bc.getUseritemsService().purchaseUserItemWithOptions(defId, quantity, shopId, includeDef, optionsJson, this);
```

**Obj-C:**

```objectivec
// ITEM type
NSString *defId = @"StackableHealthPotion";
NSString *optionsJson = @"{\"blockIfExceedItemMaxStackable\": True}";

// BUNDLE type
// NSString *defId = @"BUNDLE001";
// NSString *optionsJson = @"{\"blockIfExceedItemMaxStackable\": True, \"blockIfExceedContainedItemMaxStackable\": False}";

int quantity = 1;
NSString *shopId = @"None";
BOOL includeDef = True;
BCCompletionBlock successBlock; // define callback
BCErrorCompletionBlock failureBlock; // define callback
[[_bc userItemsService] purchaseUserItemWithOptions:
                        defId:defId
                     quantity:quantity
                       shopId:shopId
                   includeDef:includeDef
                  optionsJson:optionsJson
              completionBlock:successBlock
         errorCompletionBlock:failureBlock
                     cbObject:nil]
```

**Java:**

```java
// ITEM type
String defId = "StackableHealthPotion";
String optionsJson = "{\"blockIfExceedItemMaxStackable\": True}";

// BUNDLE type
// String defId = "BUNDLE001";
// String optionsJson = "{\"blockIfExceedItemMaxStackable\": True, \"blockIfExceedContainedItemMaxStackable\": False}";

int quantity = 1;
String shopId = "None";
bool includeDef = True;
this; // implements IServerCallback
_bc.getUseritemsService.purchaseUserItemWithOptions(defId, quantity, shopId, includeDef, optionsJson, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
// ITEM type
var defId = "StackableHealthPotion";
var optionsJson = {
    "blockIfExceedItemMaxStackable": true
};

// BUNDLE type
// var defId = "BUNDLE001";
// var optionsJson = {
//     "blockIfExceedItemMaxStackable": true,
//     "blockIfExceedContainedItemMaxStackable": false
// };

var quantity = 1;
var shopId = "None";
var includeDef = True;
_bc.userItems.purchaseUserItemWithOptions(defId, quantity, shopId, includeDef, optionsJson, result =>
{
  var status = result.status;
  console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
// ITEM type
var defId = "StackableHealthPotion";
var optionsJson = {
    "blockIfExceedItemMaxStackable": true
};

// BUNDLE type
// var defId = "BUNDLE001";
// var optionsJson = {
//     "blockIfExceedItemMaxStackable": true,
//     "blockIfExceedContainedItemMaxStackable": false
// };

var quantity = 1;
var shopId = "None";
var includeDef = True;
ServerResponse result = await _bc.userItemsService.purchaseUserItemWithOptions(defId:defId, quantity:quantity, shopId:shopId, includeDef:includeDef, optionsJson:optionsJson);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
-- ITEM type
local defId = "StackableHealthPotion"
local optionsJson = {
    blockIfExceedItemMaxStackable = true
}

-- BUNDLE type
-- local defId = "BUNDLE001"
-- local optionsJson = {
--     blockIfExceedItemMaxStackable = true,
--     blockIfExceedContainedItemMaxStackable = false
-- }

local quantity = 1
local shopId = "None"
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:purchaseUserItemWithOptions(defId, quantity, shopId, includeDef, optionsJson, callback)
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
local defId = "StackableHealthPotion"
local quantity = 1
local shopId = "None"
local includeDef = true
local optionsJson = { blockIfExceedItemMaxStackable = true }

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:purchaseUserItemWithOptions(defId, quantity, shopId, includeDef, optionsJson, callback)
```

**Cloud Code:**

```cfscript
// ITEM type
var defId = "StackableHealthPotion";
var optionsJson = {
    "blockIfExceedItemMaxStackable": true
};

// BUNDLE type
// var defId = "BUNDLE001";
// var optionsJson = {
//     "blockIfExceedItemMaxStackable": true,
//     "blockIfExceedContainedItemMaxStackable": false
// };

var quantity = 1;
var shopId = "None";
var includeDef = True;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.purchaseUserItemWithOptions(defId, quantity, shopId, includeDef, optionsJson);
```

**Raw:**

```r
// ITEM type
{
    "service":"userItems",
    "operation":"PURCHASE_USER_ITEM",
    "data":{
        "defId":"StackableHealthPotion",
        "quantity":1,
        "shopId":null,
        "includeDef":true,
        "optionsJson":{
            "blockIfExceedItemMaxStackable":true
        }
    }
}

// BUNDLE type
{
    "service":"userItems",
    "operation":"PURCHASE_USER_ITEM",
    "data":{
        "defId":"BUNDLE001",
        "quantity":1,
        "shopId":null,
        "includeDef":true,
        "optionsJson":{
            "blockIfExceedItemMaxStackable":true,
            "blockIfExceedContainedItemMaxStackable":false
        }
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "quantity": -7,
        "itemsNotAwarded": {
            "sword001": 8
        },
        "items": {
            "3f980b72-e9b0-421c-a23b-09f4a297432f": {
                "itemId": "3f980b72-e9b0-421c-a23b-09f4a297432f",
                "defId": "sword001",
                "type": "ITEM",
                "quantity": 2,
                "itemData": {},
                "giftedTo": null,
                "giftedFrom": null,
                "createdAt": 1763999328116,
                "updatedAt": 1764001716414,
                "version": 10,
                "usesLeft": null,
                "coolDownStart": -1,
                "recoveryStart": -1,
                "maxUses": null,
                "coolDownUntil": -1,
                "recoveryUntil": -1,
                "itemDef": {
                    "defId": "sword001",
                    "name": "crimson sword",
                    "desc": "a sword whose blade is forged in...",
                    "type": "ITEM",
                    "category": "sword",
                    "tags": [
                        "sword",
                        "crimson",
                        "pointy"
                    ],
                    "buyPriceDisabled": false,
                    "buyPrice": {
                        "coins": 200
                    },
                    "sellPrice": {
                        "coins": 200
                    },
                    "image": null,
                    "resourceGroup": "equipment.asset",
                    "resourceTag": "sword001",
                    "meta": null,
                    "pState": "PUBLISHED",
                    "publishedAt": 1763999316395,
                    "stackable": true,
                    "maxStackable": 2,
                    "tradable": false,
                    "blockchain": false,
                    "consumable": false,
                    "uses": null,
                    "coolDownSecs": 0,
                    "recoverySecs": 0,
                    "activatable": false,
                    "statusName": null,
                    "activeSecs": null,
                    "maxActiveSecs": null,
                    "statusBehaviour": null
                }
            }
        },
        "currencies": {},
        "currencySpent": {
            "coins": -1400
        },
        "currencyBalances": {
            "createdAt": 1761045719074,
            "currencyMap": {
                "bar": {
                    "consumed": 0,
                    "balance": 220,
                    "purchased": 0,
                    "awarded": 0,
                    "revoked": 0
                },
                "bucks": {
                    "consumed": 0,
                    "balance": 0,
                    "purchased": 0,
                    "awarded": 0,
                    "revoked": 0
                },
                "gems": {
                    "consumed": 0,
                    "balance": 0,
                    "purchased": 0,
                    "awarded": 0,
                    "revoked": 0
                },
                "coins": {
                    "consumed": 0,
                    "balance": 1400,
                    "purchased": 0,
                    "awarded": 0,
                    "revoked": 0
                }
            },
            "playerId": "bbe26c21-02ab-4eb8-a7f0-13d09434cd1b",
            "updatedAt": 1764001716408
        }
    },
    "status": 200
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/receiveuseritemfrom.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/receiveuseritemfrom -->

# ReceiveUserItemFrom

Retrieves and transfers the gift item from the specified player, who must have previously called giveUserItemTo.

| Service | Operation |
| ------- | --------- |
| userItems | RECEIVE_USER_ITEM_FROM |

## Method Parameters
Parameter | Description
--------- | -----------
profileId | The profile ID of the user who is giving the item. 
itemId | The ID uniquely identifying the user item to be transferred. 

## Usage

**C#:**

```csharp
string profileId = "a-user-profileId";
string itemId = "aaa-bbb-ccc-ddd";
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.ReceiveUserItemFrom(profileId, itemId, successCallback, failureCallback);
```

**C++:**

```cpp
const char *profileId = "a-user-profileId";
const char *itemId = "aaa-bbb-ccc-ddd";
_bc->getUserItemsService()->receiveUserItemFrom(profileId, itemId, this);
```

**Obj-C:**

```objectivec
NSString *profileId = @"a-user-profileId";
NSString *itemId = @"aaa-bbb-ccc-ddd";
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] receiveUserItemFrom:profileId
                     itemId:itemId
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String profileId = "a-user-profileId";
String itemId = "aaa-bbb-ccc-ddd";
this; // implements IServerCallback

_bc.getUserItemsService().receiveUserItemFrom(profileId, itemId, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var profileId = "a-user-profileId";
var itemId = "aaa-bbb-ccc-ddd";

_bc.userItems.receiveUserItemFrom(profileId, itemId, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  profileId = "a-user-profileId";
var  itemId = "aaa-bbb-ccc-ddd";

ServerResponse result = await _bc.userItemsService.receiveUserItemFrom(profileId:profileId, itemId:itemId);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local profileId = "a-user-profileId"
local itemId = "aaa-bbb-ccc-ddd"

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:receiveUserItemFrom(profileId, itemId, callback)
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
local profileId = "a-user-profileId"
local itemId = "aaa-bbb-ccc-ddd"

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:receiveUserItemFrom(profileId, itemId, callback)
```

**Cloud Code:**

```cfscript
var profileId = "a-user-profileId";
var itemId = "aaa-bbb-ccc-ddd";
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.receiveUserItemFrom(profileId, itemId);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "RECEIVE_USER_ITEM_FROM",
    "data": {
        "profileId": "a-user-profileId",
        "itemId": "aaa-bbb-ccc-ddd"
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "item": {
            "itemId": "692ac167-ed6a-4539-9513-c7149d7166c2",
            "defId": "boost_rapidfire",
            "quantity": 1,
            "usesLeft": null,
            "coolDownStart": -1,
            "recoveryStart": -1,
            "itemData": {},
            "giftedTo": null,
            "giftedFrom": null,
            "blockId": null,
            "createdAt": 1566852144140,
            "updatedAt": 1566852144140,
            "version": 1,
            "maxUses": null,
            "coolDownUntil": -1,
            "recoveryUntil": -1,
            "itemDef": {}
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/refreshblockchainuseritems.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/refreshblockchainuseritems -->

# RefreshBlockchainUserItems

Syncs the caller's user items with the item management attached blockchain. Results are reported asynchronously via an RTT event.

| Service | Operation |
| ------- | --------- |
| userItems | REFRESH_BLOCKCHAIN_USER_ITEMS |

## Usage

**C#:**

```csharp
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.RefreshBlockchainUserItems(successCallback, failureCallback);
```

**C++:**

```cpp
_bc->getUserItemsService()->refreshBlockchainUserItems(this);
```

**Obj-C:**

```objectivec
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] refreshBlockchainUserItems:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
this; // implements IServerCallback

_bc.getUserItemsService().refreshBlockchainUserItems(this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript

_bc.userItems.refreshBlockchainUserItems(result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart

ServerResponse result = await _bc.userItemsService.refreshBlockchainUserItems();

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:refreshBlockchainUserItems(callback)
```

**GDScript:**

```gdscript
var result = await _bc.user_items_service.refresh_blockchain_user_items()

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:refreshBlockchainUserItems(callback)
```

**Cloud Code:**

```cfscript
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.refreshBlockchainUserItems();
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "REFRESH_BLOCKCHAIN_USER_ITEMS",
    "data": {}
}
```


---

<!-- source: docs/api/2_capi/useritems/removeuseritemfromblockchain.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/removeuseritemfromblockchain -->

# RemoveUserItemFromBlockchain
Removes the specified item from the item management attached blockchain. Results are reported asynchronously via an RTT event.

| Service | Operation |
| ------- | --------- |
| userItems | REMOVE_USER_ITEM_FROM_BLOCKCHAIN |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the user item.
version | The version of the user item being removed.

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
int version = 1;

SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UseritemsService.RemoveUserItemFromBlockchain(itemId, version, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
int version = 1;
_bc.getUseritemsService().removeUserItemFromBlockchain(itemId, version, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
int version = 1;
BCCompletionBlock successBlock; // define callback
BCErrorCompletionBlock failureBlock; // define callback
[[_bc userItemsService] RemoveUserItemFromBlockchain:
                       itemId:itemId
                      version:version
              completionBlock:successBlock
         errorCompletionBlock:failureBlock
                     cbObject:nil]
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
int version = 1;
this; // implements IServerCallback
_bc.getUseritemsService.RemoveUserItemFromBlockchain(itemId, version, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}

```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
_bc.userItems.RemoveUserItemFromBlockchain(itemId, version, result =>
{
  var status = result.status;
  console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  itemId = "aaa-bbb-ccc-ddd";
var  version = 1;

ServerResponse result = await _bc.userItemsService.RemoveUserItemFromBlockchain(itemId:itemId, version:version);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:removeUserItemFromBlockchain(itemId, version, callback)
```

**GDScript:**

```gdscript
var item_id = "aaa-bbb-ccc-ddd"
var version = 1

var result = await _bc.user_items_service.remove_user_item_from_blockchain(item_id, version)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:removeUserItemFromBlockchain(itemId, version, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.RemoveUserItemFromBlockchain(itemId, version);
```

**Raw:**

```r
{
    "service":"userItems",
    "operation":"REMOVE_USER_ITEM_FROM_BLOCKCHAIN",
    "data":{
        "itemId":"aaa-bbb-ccc-ddd",
        "version":1
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "status": 200,
    "data": null
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/selluseritem.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/selluseritem -->

# SellUserItem

Allows a quantity of a specified user item to be sold. If any quantity of the user item remains, it will be returned, potentially with the associated itemDef (with language fields limited to the current or default language), along with the currency refunded and currency balances.

| Service | Operation |
| ------- | --------- |
| userItems | SELL_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the user item. 
version | The version of the user item being sold. 
quantity | The quantity of the user item to sell. 
shopId | The id identifying the store the item is being purchased from (not yet supported). Use null or empty string to specify the default shop price.
includeDef | If true and any quantity of the user item remains, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
string shopId = "";
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.SellUserItem(itemId, version, quantity, shopId, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
const char *shopId = "";
bool includeDef = true;
_bc->getUserItemsService()->sellUserItem(itemId, version, quantity, shopId, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
NSString *shopId = @"";
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] sellUserItem:itemId
                    version:version
                   quantity:quantity
                     shopId:shopId
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
int version = 1;
int quantity = 1;
String shopId = "";
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().sellUserItem(itemId, version, quantity, shopId, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var quantity = 1;
var shopId = null;
var includeDef = true;

_bc.userItems.sellUserItem(itemId, version, quantity, shopId, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  itemId = "aaa-bbb-ccc-ddd";
var  version = 1;
var  quantity = 1;
var  shopId = null;
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.sellUserItem(itemId:itemId, version:version, quantity:quantity, shopId:shopId, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local quantity = 1
local shopId = nil
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:sellUserItem(itemId, version, quantity, shopId, includeDef, callback)
```

**GDScript:**

```gdscript
var item_id = "aaa-bbb-ccc-ddd"
var version = 1
var quantity = 1
var shop_id = null
var include_def = true

var result = await _bc.user_items_service.sell_user_item(item_id, version, quantity, shop_id, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local quantity = 1
local shopId = nil
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:sellUserItem(itemId, version, quantity, shopId, includeDef, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var quantity = 1;
var shopId = null;
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.sellUserItem(itemId, version, quantity, shopId, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "SELL_USER_ITEM",
    "data": {
        "itemId": "aaa-bbb-ccc-ddd",
        "version": 1,
        "quantity": 1,
        "shopId": null,
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "item": {},
        "currencyRefunded": {
            "coins": 400
        },
        "currencyBalances": {
            "createdAt": 1566850026783,
            "currencyMap": {
                "coins": {
                    "consumed": 200,
                    "balance": 3000200,
                    "purchased": 0,
                    "awarded": 3000400
                }
            },
            "playerId": "55ffc16e-f92b-44f3-98b0-68a7a4f24106",
            "updatedAt": 1566850242013
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/sysawarduseritem.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/sysawarduseritem -->

# SysAwardUserItem
Client cloud code only call to allow item(s) to be awarded to the session user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | SYS_AWARD_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
defId | The unique id of the item definition to award.
quantity | The quantity of the item to award.
includeDef | If true, the associated item definition will be included in the response.
optionsJson | Optional support for specifying 'blockIfExceedItemMaxStackable' indicating how to process the award if the defId is for a stackable item with a max stackable quantity and the specified quantity to award is too high. If true and the quantity is too high, the call is blocked and an error is returned. If false (default) and quantity is too high, the quantity is adjusted to the allowed maximum and the quantity not awarded is reported in response key 'itemsNotAwarded' - unless the adjusted quantity would be 0, in which case the call is blocked and an error is returned.

## Usage

**C#:**

```csharp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**C++:**

```cpp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Obj-C:**

```objectivec
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Java:**

```java
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**JavaScript:**

```javascript
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Dart:**

```dart
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Roblox:**

```lua
-- N/A
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
-- Cloud Code only. To view example, switch to the Cloud Code tab
```

**Cloud Code:**

```cfscript
var defId = "sword001";
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.sysAwardUserItem(defId, quantity, includeDef, optionsJson);
```

**Raw:**

```r
{
    "service":"userItems",
    "operation":"SYS_AWARD_USER_ITEM",
    "data":{
        "defId":"sword001",
        "quantity":1,
        "includeDef":true,
        "optionsJson":{
            "blockIfExceedItemMaxStackable":false
        }
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "quantity": 1,
        "items": {
            "5e3d9c33-174c-4826-9b52-d911d56c7671": {
                "itemId": "5e3d9c33-174c-4826-9b52-d911d56c7671",
                "defId": "aa",
                "type": "ITEM",
                "quantity": 1,
                "itemData": {},
                "giftedTo": null,
                "giftedFrom": null,
                "createdAt": 1764001974250,
                "updatedAt": 1764001974250,
                "version": 1,
                "usesLeft": null,
                "coolDownStart": -1,
                "recoveryStart": -1,
                "maxUses": null,
                "coolDownUntil": -1,
                "recoveryUntil": -1,
                "itemDef": {
                    "defId": "aa",
                    "name": "apple",
                    "desc": null,
                    "type": "ITEM",
                    "category": "fruit",
                    "tags": null,
                    "buyPriceDisabled": false,
                    "buyPrice": {},
                    "sellPrice": {},
                    "image": "https://api.braincloudservers.com/files/portal/g/23782/metadata/itemDefinitions/aa.png",
                    "resourceGroup": null,
                    "resourceTag": null,
                    "meta": {},
                    "pState": "PUBLISHED",
                    "publishedAt": 1603486352114,
                    "stackable": false,
                    "maxStackable": null,
                    "tradable": false,
                    "blockchain": false,
                    "consumable": false,
                    "uses": null,
                    "coolDownSecs": 0,
                    "recoverySecs": 0,
                    "activatable": false,
                    "statusName": null,
                    "activeSecs": null,
                    "maxActiveSecs": null,
                    "statusBehaviour": null
                }
            }
        }
    },
    "status": 200
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/sysawarduseritemtouser.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/sysawarduseritemtouser -->

# SysAwardUserItemToUser
Client cloud code only Sys API to allow item(s) to be awarded to the applicable user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.

| Service | Operation |
| ------- | --------- |
| userItems | SYS_AWARD_USER_ITEM_TO_USER |

## Method Parameters
Parameter | Description
--------- | -----------
profileId | The profile id of the user being awarded the user item.
defId | The unique id of the item definition to award.
quantity | The quantity of the item to award.
includeDef | If true, the associated item definition will be included in the response.
optionsJson | Optional support for specifying 'blockIfExceedItemMaxStackable' indicating how to process the award if the defId is for a stackable item with a max stackable quantity and the specified quantity to award is too high. If true and the quantity is too high, the call is blocked and an error is returned. If false (default) and quantity is too high, the quantity is adjusted to the allowed maximum and the quantity not awarded is reported in response key 'itemsNotAwarded' - unless the adjusted quantity would be 0, in which case the call is blocked and an error is returned.

## Usage

**C#:**

```csharp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**C++:**

```cpp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Obj-C:**

```objectivec
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Java:**

```java
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**JavaScript:**

```javascript
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Dart:**

```dart
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Roblox:**

```lua
-- N/A
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
-- Cloud Code only. To view example, switch to the Cloud Code tab
```

**Cloud Code:**

```cfscript
var profileId = "user-profile-id";
var defId = "sword001";
var quantity = 1;
var includeDef = True;
var optionsJson = {
    "blockIfExceedItemMaxStackable": false
};
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.sysAwardUserItemToUser(profileId, defId, quantity, includeDef, optionsJson);
```

**Raw:**

```r
{
    "service":"userItems",
    "operation":"SYS_AWARD_USER_ITEM_TO_USER",
    "data":{
        "profileId":"user-profile-id",
        "defId":"sword001",
        "quantity":1,
        "includeDef":true,
        "optionsJson":{
            "blockIfExceedItemMaxStackable":false
        }
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "quantity": 1,
        "items": {
            "ad2a0f81-1efc-4c76-a8f4-608c6efb488d": {
                "itemId": "ad2a0f81-1efc-4c76-a8f4-608c6efb488d",
                "defId": "aa",
                "type": "ITEM",
                "quantity": 1,
                "itemData": {},
                "giftedTo": null,
                "giftedFrom": null,
                "createdAt": 1764002065367,
                "updatedAt": 1764002065367,
                "version": 1,
                "usesLeft": null,
                "coolDownStart": -1,
                "recoveryStart": -1,
                "maxUses": null,
                "coolDownUntil": -1,
                "recoveryUntil": -1,
                "itemDef": {
                    "defId": "aa",
                    "name": "apple",
                    "desc": null,
                    "type": "ITEM",
                    "category": "fruit",
                    "tags": null,
                    "buyPriceDisabled": false,
                    "buyPrice": {},
                    "sellPrice": {},
                    "image": "https://api.braincloudservers.com/files/portal/g/23782/metadata/itemDefinitions/aa.png",
                    "resourceGroup": null,
                    "resourceTag": null,
                    "meta": {},
                    "pState": "PUBLISHED",
                    "publishedAt": 1603486352114,
                    "stackable": false,
                    "maxStackable": null,
                    "tradable": false,
                    "blockchain": false,
                    "consumable": false,
                    "uses": null,
                    "coolDownSecs": 0,
                    "recoverySecs": 0,
                    "activatable": false,
                    "statusName": null,
                    "activeSecs": null,
                    "maxActiveSecs": null,
                    "statusBehaviour": null
                }
            }
        }
    },
    "status": 200
}
```

</details>


---

<!-- source: docs/api/2_capi/useritems/sysdropallmyuseritems.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/sysdropallmyuseritems -->

# SysDropAllMyUserItems

Client Cloud Code only. Drops every droppable item in the session user's inventory, without any recovery of the currency paid for them.

Items published to the blockchain (have a `blockItemId`) and items that have been given away and are awaiting pickup (have `giftedTo`) are not dropped.

> **Caution:** This permanently deletes the user's items and cannot be undone.

One `DroppedItem` analytics event is recorded for each item definition dropped, with the quantities of that definition's deleted items summed. Items whose item definition has been revoked or deleted are dropped but not reported.

> **Note:** Each user item deleted counts as one bulk API call. Nothing is counted if the user had no droppable items.

| Service | Operation |
| ------- | --------- |
| userItems | SYS_DROP_ALL_MY_USER_ITEMS |

## Method Parameters

This method takes no parameters.

## Usage

**C#:**

```csharp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**C++:**

```cpp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Obj-C:**

```objectivec
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Java:**

```java
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**JavaScript:**

```javascript
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Dart:**

```dart
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Roblox:**

```lua
-- N/A
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
-- Cloud Code only. To view example, switch to the Cloud Code tab
```

**Cloud Code:**

```cfscript
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.sysDropAllMyUserItems();
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "SYS_DROP_ALL_MY_USER_ITEMS",
    "data": {}
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "deletedCount": 12
    },
    "status": 200
}
```

</details>

`deletedCount` is the number of user item entries that were deleted. A stackable item counts as one entry, whatever its quantity.

<details>
<summary>Common Error Codes</summary>

### Status Codes

Code | Name | Description
---- | ---- | -----------
40616 | CLOUD_CODE_ONLY_METHOD | The method was called directly from a client. It can only be called from client-session Cloud Code.

</details>


---

<!-- source: docs/api/2_capi/useritems/sysdropmyuseritems.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/sysdropmyuseritems -->

# SysDropMyUserItems

Client Cloud Code only. Drops the specified items from the session user's inventory, without any recovery of the currency paid for them.

If `dropMax` is `true`, the full quantity of each item is dropped. If `false`, a quantity of 1 of each item is dropped.

Items that cannot be dropped are skipped rather than failing the whole call — for example, an item that is not found in the user's inventory, an item published to the blockchain (has a `blockItemId`), or an item that has been given away and is awaiting pickup (has `giftedTo`). Their IDs are returned in `skippedItemIds`.

> **Note:** By default, at most **10** item IDs can be passed per call. The limit is set by the app property `userItemsDropItemsMaxItemIds` — contact support if you need it adjusted.
> 
> Each item ID passed counts as one bulk API call, whether or not the item was actually dropped.

| Service | Operation |
| ------- | --------- |
| userItems | SYS_DROP_MY_USER_ITEMS |

## Method Parameters
Parameter | Description
--------- | -----------
itemIds | Array of user item IDs to drop from the session user's inventory.
dropMax | If `true`, the full quantity of each item is dropped. If `false`, a quantity of 1 of each item is dropped.

## Usage

**C#:**

```csharp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**C++:**

```cpp
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Obj-C:**

```objectivec
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Java:**

```java
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**JavaScript:**

```javascript
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Dart:**

```dart
// Cloud Code only. To view example, switch to the Cloud Code tab
```

**Roblox:**

```lua
-- N/A
```

**GDScript:**

```gdscript
N/A
```

**Lua:**

```lua
-- Cloud Code only. To view example, switch to the Cloud Code tab
```

**Cloud Code:**

```cfscript
var itemIds = ["aaa-bbb-ccc-ddd", "eee-fff-ggg-hhh"];
var dropMax = false;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.sysDropMyUserItems(itemIds, dropMax);
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "SYS_DROP_MY_USER_ITEMS",
    "data": {
        "itemIds": [
            "aaa-bbb-ccc-ddd",
            "eee-fff-ggg-hhh"
        ],
        "dropMax": false
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "items": [
            {
                "itemId": "aaa-bbb-ccc-ddd",
                "defId": "potion001",
                "type": "ITEM",
                "quantity": 4,
                "itemData": {},
                "giftedTo": null,
                "giftedFrom": null,
                "createdAt": 1764001974250,
                "updatedAt": 1791360000000,
                "version": 3,
                "usesLeft": null,
                "coolDownStart": -1,
                "recoveryStart": -1,
                "maxUses": null,
                "coolDownUntil": -1,
                "recoveryUntil": -1
            }
        ],
        "skippedItemIds": [
            "eee-fff-ggg-hhh"
        ]
    },
    "status": 200
}
```

</details>

`items` lists the dropped items that still have some quantity remaining. Items that were dropped completely are not included. `skippedItemIds` is only present when one or more items could not be dropped.

<details>
<summary>Common Error Codes</summary>

### Status Codes

Code | Name | Description
---- | ---- | -----------
40358 | MISSING_REQUIRED_PARAMETER | `itemIds` or `dropMax` was not specified.
40660 | INVALID_PARAMETER_VALUE | More item IDs were passed than the app allows (10 by default).
40616 | CLOUD_CODE_ONLY_METHOD | The method was called directly from a client. It can only be called from client-session Cloud Code.

</details>


---

<!-- source: docs/api/2_capi/useritems/updateuseritemdata.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/updateuseritemdata -->

# UpdateUserItemData

Updates the item data on the specified user item.

| Service | Operation |
| ------- | --------- |
| userItems | UPDATE_USER_ITEM_DATA |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the user item. 
version | The version of the user item being updated. 
newItemData | New item data to replace existing user item data. 

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
int version = 1;
string newItemData = "{\"condition\":77,\"bonus\":1}";
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.UpdateUserItemData(itemId, version, newItemData, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
int version = 1;
const char *newItemData = "{\"condition\":77,\"bonus\":1}";
_bc->getUserItemsService()->updateUserItemData(itemId, version, newItemData, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
int version = 1;
NSString *newItemData = "{\"condition\":77,\"bonus\":1}";
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] updateUserItemData:itemId
                    version:version
                newItemData:newItemData
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
int version = 1;
String newItemData = "{\"condition\":77,\"bonus\":1}";
this; // implements IServerCallback

_bc.getUserItemsService().updateUserItemData(itemId, version, newItemData, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var newItemData = {
  "condition": 77,
  "bonus": 1
};

_bc.userItems.updateUserItemData(itemId, version, newItemData, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  itemId = "aaa-bbb-ccc-ddd";
var  version = 1;
var  newItemData = {
  "condition": 77,
  "bonus": 1
};

ServerResponse result = await _bc.userItemsService.updateUserItemData(itemId:itemId, version:version, newItemData:newItemData);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local newItemData = {
  condition = 77,
  bonus = 1
}

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:updateUserItemData(itemId, version, newItemData, callback)
```

**GDScript:**

```gdscript
var item_id = "aaa-bbb-ccc-ddd"
var version = 1
var new_item_data = {
  "condition": 77,
  "bonus": 1
}

var result = await _bc.user_items_service.update_user_item_data(item_id, version, new_item_data)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local newItemData = { condition = 77, bonus = 1 }

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:updateUserItemData(itemId, version, newItemData, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var newItemData = {
  "condition": 77,
  "bonus": 1
};
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.updateUserItemData(itemId, version, newItemData);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "UPDATE_USER_ITEM_DATA",
    "data": {
        "itemId": "aaa-bbb-ccc-ddd",
        "version": 1,
        "newItemData": {
            "condition": 77,
            "bonus": 1
        }
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "item": {
            "itemId": "bf74cc8a-3987-4bf7-8e35-683917e14ab8",
            "defId": "medal_bronze_1",
            "quantity": 1,
            "usesLeft": null,
            "coolDownStart": -1,
            "recoveryStart": -1,
            "itemData": {
                "condition": 77,
                "bonus": 1
            },
            "giftedTo": null,
            "giftedFrom": null,
            "blockId": null,
            "createdAt": 1566851160771,
            "updatedAt": 1566851174886,
            "version": 2,
            "maxUses": null,
            "coolDownUntil": -1,
            "recoveryUntil": -1,
            "itemDef": {}
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/2_capi/useritems/useuseritem.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/capi/useritems/useuseritem -->

# UseUserItem

Uses the specified item, potentially consuming it.

| Service | Operation |
| ------- | --------- |
| userItems | USE_USER_ITEM |

## Method Parameters
Parameter | Description
--------- | -----------
itemId | The unique id of the user item. 
version | The version of the user item being used. 
newItemData | Optional item data to replace existing user item data. Specify null to leave item data unchanged. Specify empty map to clear item data. 
includeDef | If true, the associated item definition will be included in the response. 

## Usage

**C#:**

```csharp
string itemId = "aaa-bbb-ccc-ddd";
int version = 1;
string newItemData = "{\"condition\":77,\"bonus\":1}";
bool includeDef = true;
SuccessCallback successCallback = (response, cbObject) =>
{
    Debug.Log(string.Format("Success | {0}", response));
};
FailureCallback failureCallback = (status, code, error, cbObject) =>
{
    Debug.Log(string.Format("Failed | {0}  {1}  {2}", status, code, error));
};

_bc.UserItemsService.UseUserItem(itemId, version, newItemData, includeDef, successCallback, failureCallback);
```

**C++:**

```cpp
const char *itemId = "aaa-bbb-ccc-ddd";
int version = 1;
const char *newItemData = "{\"condition\":77,\"bonus\":1}";
bool includeDef = true;
_bc->getUserItemsService()->useUserItem(itemId, version, newItemData, includeDef, this);
```

**Obj-C:**

```objectivec
NSString *itemId = @"aaa-bbb-ccc-ddd";
int version = 1;
NSString *newItemData = "{\"condition\":77,\"bonus\":1}";
bool includeDef = true;
BCCompletionBlock successBlock;      // define callback
BCErrorCompletionBlock failureBlock; // define callback

[[_bc userItemsService] useUserItem:itemId
                    version:version
                newItemData:newItemData
                 includeDef:includeDef
            completionBlock:successBlock
       errorCompletionBlock:failureBlock
                   cbObject:nil];
```

**Java:**

```java
String itemId = "aaa-bbb-ccc-ddd";
int version = 1;
String newItemData = "{\"condition\":77,\"bonus\":1}";
boolean includeDef = true;
this; // implements IServerCallback

_bc.getUserItemsService().useUserItem(itemId, version, newItemData, includeDef, this);

public void serverCallback(ServiceName serviceName, ServiceOperation serviceOperation, JSONObject jsonData)
{
    System.out.print(String.format("Success | %s", jsonData.toString()));
}
public void serverError(ServiceName serviceName, ServiceOperation serviceOperation, int statusCode, int reasonCode, String jsonError)
{
    System.out.print(String.format("Failed | %d %d %s", statusCode,  reasonCode, jsonError.toString()));
}
```

**JavaScript:**

```javascript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var newItemData = {
  "condition": 77,
  "bonus": 1
};
var includeDef = true;

_bc.userItems.useUserItem(itemId, version, newItemData, includeDef, result =>
{
    var status = result.status;
    console.log(status + " : " + JSON.stringify(result, null, 2));
});
```

**Dart:**

```dart
var  itemId = "aaa-bbb-ccc-ddd";
var  version = 1;
var  newItemData = {
  "condition": 77,
  "bonus": 1
};
var  includeDef = true;

ServerResponse result = await _bc.userItemsService.useUserItem(itemId:itemId, version:version, newItemData:newItemData, includeDef:includeDef);

if (result.statusCode == 200) {
    print("Success");
} else {
    print("Failed ${result.error['status_message'] ?? result.error}");
}
```

**Roblox:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local newItemData = {
  condition = 77,
  bonus = 1
}
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:useUserItem(itemId, version, newItemData, includeDef, callback)
```

**GDScript:**

```gdscript
var item_id = "aaa-bbb-ccc-ddd"
var version = 1
var new_item_data = {
  "condition": 77,
  "bonus": 1
}
var include_def = true

var result = await _bc.user_items_service.use_user_item(item_id, version, new_item_data, include_def)

if result.status == 200:
	print("Success")
else:
	print("Failed: %s" % result.status_message)
```

**Lua:**

```lua
local itemId = "aaa-bbb-ccc-ddd"
local version = 1
local newItemData = { condition = 77, bonus = 1 }
local includeDef = true

local callback = function(success, response)
    if success then
        print("Success")
    else
        print("Failed | " .. tostring(response.status_message))
    end
end

_bc.userItems:useUserItem(itemId, version, newItemData, includeDef, callback)
```

**Cloud Code:**

```cfscript
var itemId = "aaa-bbb-ccc-ddd";
var version = 1;
var newItemData = {
  "condition": 77,
  "bonus": 1
};
var includeDef = true;
var userItemsProxy = bridge.getUserItemsServiceProxy();

var postResult = userItemsProxy.useUserItem(itemId, version, newItemData, includeDef);
if (postResult.status == 200) {
    // Success!
}
```

**Raw:**

```r
{
    "service": "userItems",
    "operation": "USE_USER_ITEM",
    "data": {
        "itemId": "aaa-bbb-ccc-ddd",
        "version": 1,
        "newItemData": {
            "condition": 77,
            "bonus": 1
        },
        "includeDef": true
    }
}
```

<details>
<summary>JSON Response</summary>

```json
{
    "data": {
        "used": true,
        "statusEffects": {
            "activeStart": 1566851245914,
            "statusName": "boosted",
            "details": {},
            "activeUntil": 1567751245914
        },
        "item": {
            "itemId": "6ff179ce-6689-4fad-9d97-f94df35ea287",
            "defId": "boost_rapidfire",
            "quantity": 1,
            "usesLeft": null,
            "coolDownStart": -1,
            "recoveryStart": -1,
            "itemData": {
                "condition": 77,
                "bonus": 1
            },
            "giftedTo": null,
            "giftedFrom": null,
            "blockId": null,
            "createdAt": 1566851211540,
            "updatedAt": 1566851245917,
            "version": 2,
            "maxUses": null,
            "coolDownUntil": -1,
            "recoveryUntil": -1,
            "itemDef": {
                "defId": "boost_rapidfire",
                "name": "Rapid Fire",
                "desc": "Rapid fire for the next match.",
                "type": "ITEM",
                "category": "boost",
                "tags": null,
                "buyPrice": {
                    "coins": 200
                },
                "sellPrice": {
                    "coins": 400
                },
                "image": null,
                "resourceGroup": null,
                "resourceTag": null,
                "meta": {},
                "pState": "PUBLISHED",
                "publishedAt": 1566850042148,
                "stackable": false,
                "consumable": false,
                "uses": null,
                "coolDownSecs": 0,
                "recoverySecs": 0,
                "activatable": true,
                "statusName": "boosted",
                "activeSecs": 900000,
                "tradable": true,
                "blockchain": false,
                "blockchainDefId": null
            }
        }
    },
    "status": 200
}
```
</details>


---

<!-- source: docs/api/4_s2s/useritems/index.md -->
<!-- url: https://docs-internal.braincloudservers.com/api/s2s/useritems -->

# User Items

The **User Items** service, introduced in 4.2, is used to manage a collection of in-app items that users can be awarded, buy, sell, or trade (using virtual currency). Optionally, these items can be backed up to the blockchain.

Key concepts:

- Items are first defined in the **Item Catalog** 
- Defined items can be purchased or awarded to users, where they will be recorded as userItem instances.
- Using an item may consume it (or a portion of it - or none of it). Consumed items will automatically disappear from the user's user item inventory.
- Using an item may trigger a status effect (i.e. invulnerability for 60 seconds)
- Using an item may trigger a cool-down period (before the item can be used again) or a regeneration period (a period after which the item regenerates a "use.")

### API Summary

* [SYS_AwardUserItemToUser](/api/capi/useritems/sysawarduseritemtouser) - Client cloud code only Sys API to allow item(s) to be awarded to the applicable user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
* [SYS_AwardUserItem](/api/capi/useritems/sysawarduseritem) - Client cloud code only call to allow item(s) to be awarded to the session user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.

> **Tip:** All the client APIs that the names beigin with <strong>"Sys"</strong> <em>are</em> also available to S2S.
> For the usages of the S2S user APIs (if they are not listed at this section),
> refer to brainCloud client [useritems](/api/capi/useritems) APIs.