GS2-Inventory Transaction Actions

Specification of verify/consume/acquire transaction actions
Tags:

Verify Action

Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId

Verify current max inventory capacity by specifying a user ID

Verifies that the specified user’s current maximum inventory capacity satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. The verification uses the buffed capacity value (reflecting any active buff effects from GS2-Buff).

Supports quantity specification: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
inventoryName string
✓
 ~ 128 chars Inventory Model Name
The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits.
verifyType string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
✓
 Type of verification
DefinitionDescription
“less”Current max inventory capacity is less than the specified value
“lessEqual”Current max inventory capacity is less than or equal to the specified value
“greater”Current max inventory capacity is greater than the specified value
“greaterEqual”Current max inventory capacity is greater than or equal to the specified value
“equal”Current max inventory capacity is equal to the specified value
“notEqual”Current max inventory capacity is not equal to the specified value
currentInventoryMaxCapacity int
✓
 0 ~ 2147483646 Current max inventory capacity
multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "inventoryName": "[string]Inventory Model Name",
        "verifyType": "[string]Type of verification",
        "currentInventoryMaxCapacity": "[int]Current max inventory capacity",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  inventoryName: "[string]Inventory Model Name"
  verifyType: "[string]Type of verification"
  currentInventoryMaxCapacity: "[int]Current max inventory capacity"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").verify.verify_inventory_current_max_capacity_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    inventoryName="[string]Inventory Model Name",
    verifyType="[string]Type of verification",
    currentInventoryMaxCapacity="[int]Current max inventory capacity",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:VerifyItemSetByUserId

Verify the quantity of Item Sets in possession by specifying the user ID

Verifies that the specified user’s total item count satisfies the given condition. The count is summed across all item sets of the specified item type. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual.

Supports quantity specification: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
inventoryName string
✓
 ~ 128 chars Inventory Model name
Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
itemName string
✓
 ~ 128 chars Item Model Name
The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set.
verifyType string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
✓
 Type of verification
DefinitionDescription
“less”Possession quantity is less than the specified value
“lessEqual”Possession quantity is less than or equal to the specified value
“greater”Possession quantity is greater than the specified value
“greaterEqual”Possession quantity is greater than or equal to the specified value
“equal”Possession quantity is equal to the specified value
“notEqual”Possession quantity is not equal to the specified value
itemSetName string ~ 36 chars Name identifying the item set
count long
✓
 0 ~ 9223372036854775805 Quantity in possession
multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:VerifyItemSetByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "inventoryName": "[string]Inventory Model name",
        "itemName": "[string]Item Model Name",
        "verifyType": "[string]Type of verification",
        "itemSetName": "[string]Name identifying the item set",
        "count": "[long]Quantity in possession",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:VerifyItemSetByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  inventoryName: "[string]Inventory Model name"
  itemName: "[string]Item Model Name"
  verifyType: "[string]Type of verification"
  itemSetName: "[string]Name identifying the item set"
  count: "[long]Quantity in possession"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").verify.verify_item_set_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    inventoryName="[string]Inventory Model name",
    itemName="[string]Item Model Name",
    verifyType="[string]Type of verification",
    itemSetName="[string]Name identifying the item set",
    count="[long]Quantity in possession",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:VerifyReferenceOfByUserId

Verify the reference source by specifying the user ID

Verifies the state of a reference on an item set for the specified user. Supports four verification types: not_entry (reference not yet registered), already_entry (reference already registered), empty (no references at all), and not_empty (at least one reference exists). If the condition is not met, an error is returned.

Supports quantity specification: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model Name
The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
itemName string
✓
 ~ 128 chars Item Model Name
The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set.
itemSetName string
✓
 UUID ~ 36 chars Name identifying the Item Set
Maintains a unique name for each item set.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set.
referenceOf string
✓
 ~ 1024 chars Reference
A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted.
verifyType string (enum)
enum {
  “not_entry”,
  “already_entry”,
  “empty”,
  “not_empty”
}
✓
 Type of verification
DefinitionDescription
“not_entry”That the specified reference is not yet registered.
“already_entry”That the specified reference is already registered.
“empty”The number of elements registered as references is zero.
“not_empty”At least one element registered as a reference source
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:VerifyReferenceOfByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model Name",
        "userId": "[string]User ID",
        "itemName": "[string]Item Model Name",
        "itemSetName": "[string]Name identifying the Item Set",
        "referenceOf": "[string]Reference",
        "verifyType": "[string]Type of verification",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:VerifyReferenceOfByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model Name"
  userId: "[string]User ID"
  itemName: "[string]Item Model Name"
  itemSetName: "[string]Name identifying the Item Set"
  referenceOf: "[string]Reference"
  verifyType: "[string]Type of verification"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").verify.verify_reference_of_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model Name",
    userId="[string]User ID",
    itemName="[string]Item Model Name",
    itemSetName="[string]Name identifying the Item Set",
    referenceOf="[string]Reference",
    verifyType="[string]Type of verification",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:VerifySimpleItemByUserId

Verify the quantity of possessions in simple items by specifying a user ID

Verifies that the specified user’s simple item count satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual.

Supports quantity specification: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
inventoryName string
✓
 ~ 128 chars Simple Inventory Model name
Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
itemName string
✓
 ~ 128 chars Simple Item Model Name
The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to.
verifyType string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
✓
 Type of verification
DefinitionDescription
“less”Possession quantity is less than the specified value
“lessEqual”Possession quantity is less than or equal to the specified value
“greater”Possession quantity is greater than the specified value
“greaterEqual”Possession quantity is greater than or equal to the specified value
“equal”Possession quantity is equal to the specified value
“notEqual”Possession quantity is not equal to the specified value
count long
✓
 0 ~ 9223372036854775805 Quantity in possession
multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:VerifySimpleItemByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "inventoryName": "[string]Simple Inventory Model name",
        "itemName": "[string]Simple Item Model Name",
        "verifyType": "[string]Type of verification",
        "count": "[long]Quantity in possession",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:VerifySimpleItemByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  inventoryName: "[string]Simple Inventory Model name"
  itemName: "[string]Simple Item Model Name"
  verifyType: "[string]Type of verification"
  count: "[long]Quantity in possession"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").verify.verify_simple_item_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    inventoryName="[string]Simple Inventory Model name",
    itemName="[string]Simple Item Model Name",
    verifyType="[string]Type of verification",
    count="[long]Quantity in possession",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:VerifyBigItemByUserId

Verify possession quantity of Big Items by specifying a user ID

Verifies that the specified user’s big item count satisfies the specified condition. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. The comparison is performed using arbitrary-precision arithmetic on string-based counts. If the condition is not met, an error is returned; if met, the request succeeds.

Supports quantity specification: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
inventoryName string
✓
 ~ 128 chars Big Inventory Model name
Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
itemName string
✓
 ~ 128 chars Big Item Model Name
The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to.
verifyType string (enum)
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
✓
 Type of verification
DefinitionDescription
“less”Possession quantity is less than the specified value
“lessEqual”Possession quantity is less than or equal to the specified value
“greater”Possession quantity is greater than the specified value
“greaterEqual”Possession quantity is greater than or equal to the specified value
“equal”Possession quantity is equal to the specified value
“notEqual”Possession quantity is not equal to the specified value
count string
✓
 ~ 1024 chars Quantity in possession
Integer value strings up to 1024 digits
multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:VerifyBigItemByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "inventoryName": "[string]Big Inventory Model name",
        "itemName": "[string]Big Item Model Name",
        "verifyType": "[string]Type of verification",
        "count": "[string]Quantity in possession",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:VerifyBigItemByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  inventoryName: "[string]Big Inventory Model name"
  itemName: "[string]Big Item Model Name"
  verifyType: "[string]Type of verification"
  count: "[string]Quantity in possession"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").verify.verify_big_item_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    inventoryName="[string]Big Inventory Model name",
    itemName="[string]Big Item Model Name",
    verifyType="[string]Type of verification",
    count="[string]Quantity in possession",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})

Consume Action

Gs2Inventory:ConsumeItemSetByUserId

Consume Item Sets by specifying the user ID

Reduces the quantity of the specified item in the given user’s inventory. If itemSetName is specified, consumption targets that specific stack only. Without it, items are consumed across all stacks of that item type. When an item set’s count reaches zero, it is automatically deleted. Returns an Insufficient error if the user does not have enough items.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model Name
The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
itemName string
✓
 ~ 128 chars Item Model Name
The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set.
consumeCount long
✓
 1 ~ 9223372036854775805 Consumption quantity
itemSetName string ~ 36 chars Name identifying the Item Set
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:ConsumeItemSetByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model Name",
        "userId": "[string]User ID",
        "itemName": "[string]Item Model Name",
        "consumeCount": "[long]Consumption quantity",
        "itemSetName": "[string]Name identifying the Item Set",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:ConsumeItemSetByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model Name"
  userId: "[string]User ID"
  itemName: "[string]Item Model Name"
  consumeCount: "[long]Consumption quantity"
  itemSetName: "[string]Name identifying the Item Set"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").consume.consume_item_set_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model Name",
    userId="[string]User ID",
    itemName="[string]Item Model Name",
    consumeCount="[long]Consumption quantity",
    itemSetName="[string]Name identifying the Item Set",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:ConsumeSimpleItemsByUserId

Consume Simple Items by specifying a user ID

Reduces the quantity of items in the specified user’s simple inventory using a batch of consume counts. Multiple items can be consumed in a single atomic operation — if any item has insufficient quantity, the entire operation fails.

Supports quantity specification: NO

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Simple Inventory Model name
Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
consumeCounts List<ConsumeCount>
✓
 1 ~ 100 items List of consumption quantities of Simple Items
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:ConsumeSimpleItemsByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Simple Inventory Model name",
        "userId": "[string]User ID",
        "consumeCounts": [
            {
                "itemName": "[string]Simple Item Model Name",
                "count": "[long]Consumption quantity"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:ConsumeSimpleItemsByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Simple Inventory Model name"
  userId: "[string]User ID"
  consumeCounts: 
    - itemName: "[string]Simple Item Model Name"
      count: "[long]Consumption quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").consume.consume_simple_items_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Simple Inventory Model name",
    userId="[string]User ID",
    consumeCounts={
        {
            itemName="[string]Simple Item Model Name",
            count="[long]Consumption quantity"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:ConsumeBigItemByUserId

Consume Big Items by specifying a user ID

Subtracts the specified quantity from the specified user’s big item count using arbitrary-precision arithmetic. The consumeCount must be a valid integer string up to 1024 digits. If the current count is insufficient, an Insufficient error is returned and no deduction is made. A GS2-Script can be configured to execute custom logic when big items are consumed via the namespace settings.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Big Inventory Model name
Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
itemName string
✓
 ~ 128 chars Big Item Model name
Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
consumeCount string
✓
 ~ 1024 chars Consumption quantity of a Big Item
Integer value strings up to 1024 digits
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:ConsumeBigItemByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Big Inventory Model name",
        "userId": "[string]User ID",
        "itemName": "[string]Big Item Model name",
        "consumeCount": "[string]Consumption quantity of a Big Item",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:ConsumeBigItemByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Big Inventory Model name"
  userId: "[string]User ID"
  itemName: "[string]Big Item Model name"
  consumeCount: "[string]Consumption quantity of a Big Item"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").consume.consume_big_item_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Big Inventory Model name",
    userId="[string]User ID",
    itemName="[string]Big Item Model name",
    consumeCount="[string]Consumption quantity of a Big Item",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2Inventory:AddCapacityByUserId

Add inventory capacity size by specifying a user ID

Incrementally increases the user’s inventory capacity by the specified amount. The resulting capacity cannot exceed the inventory model’s maxCapacity. If the inventory does not yet exist, it is automatically created with initialCapacity before adding the specified value.

Supports quantity specification: YES

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model Name
The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
addCapacityValue int
✓
 1 ~ 2147483646 Capacity size to be added
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:AddCapacityByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model Name",
        "userId": "[string]User ID",
        "addCapacityValue": "[int]Capacity size to be added",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:AddCapacityByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model Name"
  userId: "[string]User ID"
  addCapacityValue: "[int]Capacity size to be added"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.add_capacity_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model Name",
    userId="[string]User ID",
    addCapacityValue="[int]Capacity size to be added",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:SetCapacityByUserId

Set inventory capacity size by specifying a user ID

Sets the user’s inventory capacity to the specified absolute value. Returns both the inventory state before and after the update, allowing you to compare old and new capacity values. The new capacity value cannot exceed the inventory model’s maxCapacity.

Supports quantity specification: YES

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model Name
The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
newCapacityValue int
✓
 1 ~ 2147483646 New maximum capacity for inventory
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:SetCapacityByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model Name",
        "userId": "[string]User ID",
        "newCapacityValue": "[int]New maximum capacity for inventory",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:SetCapacityByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model Name"
  userId: "[string]User ID"
  newCapacityValue: "[int]New maximum capacity for inventory"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.set_capacity_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model Name",
    userId="[string]User ID",
    newCapacityValue="[int]New maximum capacity for inventory",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:AcquireItemSetByUserId

Acquire Item Sets by specifying the user ID

Adds items to the user’s inventory. If an existing item set has room (below the stacking limit), items are added to it; otherwise, a new item set is created if multiple stacks are allowed. An optional expiresAt can set an expiration time for newly created item sets. Items with an expiration time already in the past are treated as empty. When createNewItemSet is true, a new item set is always created even if existing sets have room. If the total quantity exceeds the inventory capacity, the overflow count is returned, and overflow items may be forwarded to GS2-Inbox depending on the namespace configuration.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model name
Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
itemName string
✓
 ~ 128 chars Item Model Name
The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
acquireCount long
✓
 1 ~ 9223372036854775805 Acquisition quantity
expiresAt long 0 Expiration time
Unix time, milliseconds
createNewItemSet bool false Even if there is room in an existing Item Set, you can create a new Item Set
itemSetName string ~ 36 chars Name identifying the Item Set
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:AcquireItemSetByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model name",
        "itemName": "[string]Item Model Name",
        "userId": "[string]User ID",
        "acquireCount": "[long]Acquisition quantity",
        "expiresAt": "[long]Expiration time",
        "createNewItemSet": "[bool]Even if there is room in an existing Item Set, you can create a new Item Set",
        "itemSetName": "[string]Name identifying the Item Set",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:AcquireItemSetByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model name"
  itemName: "[string]Item Model Name"
  userId: "[string]User ID"
  acquireCount: "[long]Acquisition quantity"
  expiresAt: "[long]Expiration time"
  createNewItemSet: "[bool]Even if there is room in an existing Item Set, you can create a new Item Set"
  itemSetName: "[string]Name identifying the Item Set"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.acquire_item_set_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model name",
    itemName="[string]Item Model Name",
    userId="[string]User ID",
    acquireCount="[long]Acquisition quantity",
    expiresAt="[long]Expiration time",
    createNewItemSet="[bool]Even if there is room in an existing Item Set, you can create a new Item Set",
    itemSetName="[string]Name identifying the Item Set",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:AcquireItemSetWithGradeByUserId

Acquire one Item Set while setting the grade to GS2-Grade by specifying the user ID

Acquires exactly one item and simultaneously sets a grade value on it via GS2-Grade. This is used for items that have a quality/rank system where each individual item has a different grade value (e.g., equipment with varying stats). A new item set is always created (createNewItemSet behavior), and the grade is set through GS2-Grade’s SetGradeByUserId after the item acquisition.

Supports quantity specification: NO

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model name
Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
itemName string
✓
 ~ 128 chars Item Model Name
The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
gradeModelId string
✓
 ~ 1024 chars Grade Model GRN
gradeValue long
✓
 1 ~ 9223372036854775805 Grade value to set
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:AcquireItemSetWithGradeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model name",
        "itemName": "[string]Item Model Name",
        "userId": "[string]User ID",
        "gradeModelId": "[string]Grade Model GRN",
        "gradeValue": "[long]Grade value to set",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:AcquireItemSetWithGradeByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model name"
  itemName: "[string]Item Model Name"
  userId: "[string]User ID"
  gradeModelId: "[string]Grade Model GRN"
  gradeValue: "[long]Grade value to set"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.acquire_item_set_with_grade_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model name",
    itemName="[string]Item Model Name",
    userId="[string]User ID",
    gradeModelId="[string]Grade Model GRN",
    gradeValue="[long]Grade value to set",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:AddReferenceOfByUserId

Add a reference by specifying a user ID

Registers a reference string on the specified item set for the specified user. References associate the item set with an external entity (e.g., an equipment slot or character). When protectReferencedItem is enabled on the inventory model, items with references cannot be consumed or deleted, preventing accidental loss of equipped items.

Supports quantity specification: NO

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model Name
The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
itemName string
✓
 ~ 128 chars Item Model Name
The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set.
itemSetName string
✓
 UUID ~ 36 chars Name identifying the Item Set
Maintains a unique name for each item set.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set.
referenceOf string
✓
 ~ 1024 chars Reference
A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted.
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:AddReferenceOfByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model Name",
        "userId": "[string]User ID",
        "itemName": "[string]Item Model Name",
        "itemSetName": "[string]Name identifying the Item Set",
        "referenceOf": "[string]Reference",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:AddReferenceOfByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model Name"
  userId: "[string]User ID"
  itemName: "[string]Item Model Name"
  itemSetName: "[string]Name identifying the Item Set"
  referenceOf: "[string]Reference"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.add_reference_of_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model Name",
    userId="[string]User ID",
    itemName="[string]Item Model Name",
    itemSetName="[string]Name identifying the Item Set",
    referenceOf="[string]Reference",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:DeleteReferenceOfByUserId

Delete the reference source by specifying the user ID

Removes a specific reference string from the specified item set for the specified user. After removal, if protectReferencedItem is enabled and no other references remain, the item becomes eligible for consumption or deletion again.

Supports quantity specification: NO

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Inventory Model Name
The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to.
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
itemName string
✓
 ~ 128 chars Item Model Name
The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set.
itemSetName string
✓
 UUID ~ 36 chars Name identifying the Item Set
Maintains a unique name for each item set.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set.
referenceOf string
✓
 ~ 1024 chars Reference
A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted.
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:DeleteReferenceOfByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Inventory Model Name",
        "userId": "[string]User ID",
        "itemName": "[string]Item Model Name",
        "itemSetName": "[string]Name identifying the Item Set",
        "referenceOf": "[string]Reference",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:DeleteReferenceOfByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Inventory Model Name"
  userId: "[string]User ID"
  itemName: "[string]Item Model Name"
  itemSetName: "[string]Name identifying the Item Set"
  referenceOf: "[string]Reference"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.delete_reference_of_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Inventory Model Name",
    userId="[string]User ID",
    itemName="[string]Item Model Name",
    itemSetName="[string]Name identifying the Item Set",
    referenceOf="[string]Reference",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:AcquireSimpleItemsByUserId

Acquire Simple Items by specifying a user ID

Adds items to the user’s simple inventory using a batch of acquire counts. Multiple items can be acquired in a single atomic operation — the acquireCounts array specifies the item name and quantity for each item to acquire. Unlike regular item sets, simple items have no capacity limits, stacking limits, or expiration.

Supports quantity specification: NO

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Simple Inventory Model name
Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
acquireCounts List<AcquireCount>
✓
 1 ~ 100 items List of acquisition quantities for Simple Items
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:AcquireSimpleItemsByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Simple Inventory Model name",
        "userId": "[string]User ID",
        "acquireCounts": [
            {
                "itemName": "[string]Simple Item Model Name",
                "count": "[long]Acquisition quantity"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:AcquireSimpleItemsByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Simple Inventory Model name"
  userId: "[string]User ID"
  acquireCounts: 
    - itemName: "[string]Simple Item Model Name"
      count: "[long]Acquisition quantity"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.acquire_simple_items_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Simple Inventory Model name",
    userId="[string]User ID",
    acquireCounts={
        {
            itemName="[string]Simple Item Model Name",
            count="[long]Acquisition quantity"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:SetSimpleItemsByUserId

Set the quantity of simple items by specifying a user ID

Sets the absolute quantities of multiple simple items in a single atomic operation. The counts array specifies the item name and target quantity for each item. This overwrites the current quantities entirely, unlike acquire/consume which are relative operations.

Supports quantity specification: NO

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Simple Inventory Model name
Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
counts List<HeldCount>
✓
 1 ~ 100 items List of quantity of Simple Items in possession
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:SetSimpleItemsByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Simple Inventory Model name",
        "userId": "[string]User ID",
        "counts": [
            {
                "itemName": "[string]Simple Item Model Name",
                "count": "[long]Number of items held"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:SetSimpleItemsByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Simple Inventory Model name"
  userId: "[string]User ID"
  counts: 
    - itemName: "[string]Simple Item Model Name"
      count: "[long]Number of items held"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.set_simple_items_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Simple Inventory Model name",
    userId="[string]User ID",
    counts={
        {
            itemName="[string]Simple Item Model Name",
            count="[long]Number of items held"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:AcquireBigItemByUserId

Acquire Big Item by specifying a user ID

Adds the specified quantity to the user’s big item count using arbitrary-precision arithmetic. The acquireCount must be a valid integer string up to 1024 digits; an invalid format will result in an error. If the item does not yet exist, it will be automatically created. A GS2-Script can be configured to execute custom logic when big items are acquired via the namespace settings.

Supports quantity specification: YES

Whether the action is reversible: YES

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Big Inventory Model name
Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
itemName string
✓
 ~ 128 chars Big Item Model name
Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
acquireCount string
✓
 ~ 1024 chars Acquisition quantity for a Big Item
Integer value strings up to 1024 digits
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:AcquireBigItemByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Big Inventory Model name",
        "userId": "[string]User ID",
        "itemName": "[string]Big Item Model name",
        "acquireCount": "[string]Acquisition quantity for a Big Item",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:AcquireBigItemByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Big Inventory Model name"
  userId: "[string]User ID"
  itemName: "[string]Big Item Model name"
  acquireCount: "[string]Acquisition quantity for a Big Item"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.acquire_big_item_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Big Inventory Model name",
    userId="[string]User ID",
    itemName="[string]Big Item Model name",
    acquireCount="[string]Acquisition quantity for a Big Item",
    timeOffsetToken="[string]Time offset token",
})

Gs2Inventory:SetBigItemByUserId

Set the Big Item by specifying a user ID

Sets the big item count to the specified absolute value, replacing the current count entirely. The count must be a valid integer string up to 1024 digits. If the item does not yet exist, it will be automatically created. Unlike acquire/consume which perform relative operations, this sets the exact value directly.

Supports quantity specification: YES

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description
namespaceName string
✓
 ~ 128 chars Namespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
inventoryName string
✓
 ~ 128 chars Big Inventory Model name
Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId string
✓
 ~ 128 chars User ID
Specify #{userId} to substitute the currently logged-in user’s ID.
itemName string
✓
 ~ 128 chars Big Item Model name
Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
count string
✓
 ~ 1024 chars Quantity of Big Item
Integer value strings up to 1024 digits
timeOffsetToken string ~ 1024 chars Time offset token 
{
    "action": "Gs2Inventory:SetBigItemByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "inventoryName": "[string]Big Inventory Model name",
        "userId": "[string]User ID",
        "itemName": "[string]Big Item Model name",
        "count": "[string]Quantity of Big Item",
        "timeOffsetToken": "[string]Time offset token"
    }
}
action: Gs2Inventory:SetBigItemByUserId
request:
  namespaceName: "[string]Namespace name"
  inventoryName: "[string]Big Inventory Model name"
  userId: "[string]User ID"
  itemName: "[string]Big Item Model name"
  count: "[string]Quantity of Big Item"
  timeOffsetToken: "[string]Time offset token"
transaction.service("inventory").acquire.set_big_item_by_user_id({
    namespaceName="[string]Namespace name",
    inventoryName="[string]Big Inventory Model name",
    userId="[string]User ID",
    itemName="[string]Big Item Model name",
    count="[string]Quantity of Big Item",
    timeOffsetToken="[string]Time offset token",
})