GS2-Inventory Transaction Actions

Specification of verify/consume/acquire transaction actions

VerifyAction

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).

Whether the action allows 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
Set #{userId} to replace the currently logged in user 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

Definition	Description
“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.

Whether the action allows 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
Set #{userId} to replace the currently logged in user 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

Definition	Description
“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.

Whether the action allows 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
Set #{userId} to replace the currently logged in user 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

Definition	Description
“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.

Whether the action allows 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
Set #{userId} to replace the currently logged in user 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

Definition	Description
“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.

Whether the action allows 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
Set #{userId} to replace the currently logged in user 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

Definition	Description
“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",
})

ConsumeAction

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.

Whether the action allows quantity specification: YES

Whether the action is reversible: YES

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: NO

Whether the action is reversible: YES

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: YES

Whether the action is reversible: YES

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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",
})

AcquireAction

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.

Whether the action allows quantity specification: YES

Whether the action is reversible: NO

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: YES

Whether the action is reversible: NO

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: YES

Whether the action is reversible: YES

	Type	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: NO

Whether the action is reversible: NO

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: NO

Whether the action is reversible: NO

	Type	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: NO

Whether the action is reversible: NO

	Type	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: NO

Whether the action is reversible: YES

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: NO

Whether the action is reversible: NO

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: YES

Whether the action is reversible: YES

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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.

Whether the action allows quantity specification: YES

Whether the action is reversible: NO

	Type	Required	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 Set `#{userId}` to replace the currently logged in user 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",
})