> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Grade Transaction Actions

Specification of verify/consume/acquire transaction actions




## Verify Action



### Gs2Grade:VerifyGradeByUserId

Verify grade by User ID

Verifies that the specified user's grade value satisfies a specified condition (server-side operation).
Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual.
If the condition is not met, an error is returned with a descriptive message including the expected and actual values.
When multiplyValueSpecifyingQuantity is true, the verification threshold value is multiplied by the specified quantity.

**Quantity specification supported: NO**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| gradeName | string |  | ✓|  |  ~ 128 chars | Grade Model Name<br>The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. |
| verifyType | string (enum)<br>enum {<br>&nbsp;&nbsp;"less",<br>&nbsp;&nbsp;"lessEqual",<br>&nbsp;&nbsp;"greater",<br>&nbsp;&nbsp;"greaterEqual",<br>&nbsp;&nbsp;"equal",<br>&nbsp;&nbsp;"notEqual"<br>}<br> |  | ✓|  |  | Type of verification"less": Grade is less than the specified value / "lessEqual": Grade is less than or equal to the specified value / "greater": Grade is greater than the specified value / "greaterEqual": Grade is greater than or equal to the specified value / "equal": Grade is equal to the specified value / "notEqual": Grade is not equal to the specified value /  |
| propertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
| gradeValue | long |  | | 1 | 1 ~ 9223372036854775805 | Current Grade<br>The current grade value of this status. Used as an index into the grade model's grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. |
| multiplyValueSpecifyingQuantity | bool |  | | false |  | Whether to multiply the value used for verification when specifying the quantity |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Grade:VerifyGradeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "verifyType": "[string]Type of verification",
        "propertyId": "[string]Property ID",
        "gradeValue": "[long]Current Grade",
        "multiplyValueSpecifyingQuantity": "[bool]Whether to multiply the value used for verification when specifying the quantity",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:VerifyGradeByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  verifyType: "[string]Type of verification"
  propertyId: "[string]Property ID"
  gradeValue: "[long]Current Grade"
  multiplyValueSpecifyingQuantity: "[bool]Whether to multiply the value used for verification when specifying the quantity"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("grade").verify.verify_grade_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    verifyType="[string]Type of verification",
    propertyId="[string]Property ID",
    gradeValue="[long]Current Grade",
    multiplyValueSpecifyingQuantity="[bool]Whether to multiply the value used for verification when specifying the quantity",
    timeOffsetToken="[string]Time offset token",
})
```


---

### Gs2Grade:VerifyGradeUpMaterialByUserId

Verify grade up material by User ID

Verifies whether a material property ID is valid for grading up the specified property for the specified user (server-side operation).
The verification builds a regex pattern from the grade entry's PropertyIdRegex and GradeUpPropertyIdRegex, then checks if the material property ID matches.
Supports two verification types: 'match' (material must match the pattern) and 'notMatch' (material must not match the pattern).

**Quantity specification supported: NO**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| gradeName | string |  | ✓|  |  ~ 128 chars | Grade Model Name<br>The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. |
| verifyType | string (enum)<br>enum {<br>&nbsp;&nbsp;"match",<br>&nbsp;&nbsp;"notMatch"<br>}<br> |  | ✓|  |  | Type of verification"match": Grade is equal to the specified value / "notMatch": Grade is not equal to the specified value /  |
| propertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
| materialPropertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Grade:VerifyGradeUpMaterialByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "verifyType": "[string]Type of verification",
        "propertyId": "[string]Property ID",
        "materialPropertyId": "[string]Property ID",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:VerifyGradeUpMaterialByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  verifyType: "[string]Type of verification"
  propertyId: "[string]Property ID"
  materialPropertyId: "[string]Property ID"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("grade").verify.verify_grade_up_material_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    verifyType="[string]Type of verification",
    propertyId="[string]Property ID",
    materialPropertyId="[string]Property ID",
    timeOffsetToken="[string]Time offset token",
})
```


---

## Consume Action



### Gs2Grade:SubGradeByUserId

Subtract grade by User ID

Subtracts the specified grade value from the specified user's current grade for the given grade model and property (server-side operation).
After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status.
The rank cap value is determined by the grade entry matching the new grade level.
Returns the updated grade status along with the Experience Namespace name and the updated Experience status.

**Quantity specification supported: YES**

**Reversible action: YES**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| gradeName | string |  | ✓|  |  ~ 128 chars | Grade Model Name<br>The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. |
| propertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
| gradeValue | long |  | | 0 | 0 ~ 9223372036854775805 | Lost Grade |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Grade:SubGradeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "gradeValue": "[long]Lost Grade",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:SubGradeByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  gradeValue: "[long]Lost Grade"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("grade").consume.sub_grade_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    gradeValue="[long]Lost Grade",
    timeOffsetToken="[string]Time offset token",
})
```


---

## Acquire Action



### Gs2Grade:AddGradeByUserId

Add grade by User ID

Adds the specified grade value to the user's current grade for the given grade model and property.
After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status.
The rank cap value is determined by the grade entry matching the new grade level.
Returns the updated grade status along with the Experience Namespace name and the updated Experience status.

**Quantity specification supported: YES**

**Reversible action: YES**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| gradeName | string |  | ✓|  |  ~ 128 chars | Grade Model Name<br>The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. |
| propertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
| gradeValue | long |  | | 0 | 0 ~ 9223372036854775805 | Gained Grade |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Grade:AddGradeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "gradeValue": "[long]Gained Grade",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:AddGradeByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  gradeValue: "[long]Gained Grade"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("grade").acquire.add_grade_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    gradeValue="[long]Gained Grade",
    timeOffsetToken="[string]Time offset token",
})
```


---

### Gs2Grade:ApplyRankCapByUserId

Apply rank cap to GS2-Experience Status by User ID

Applies the rank cap corresponding to the current grade to the linked GS2-Experience status for the specified user (server-side operation).
Looks up the grade entry matching the current grade value to determine the rank cap value.
This is useful when the grade has been modified externally and the Experience rank cap needs to be synchronized.
Returns the updated grade status along with the Experience Namespace name and the updated Experience status.

**Quantity specification supported: NO**

**Reversible action: NO**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| gradeName | string |  | ✓|  |  ~ 128 chars | Grade Model Name<br>The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. |
| propertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Grade:ApplyRankCapByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:ApplyRankCapByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("grade").acquire.apply_rank_cap_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    timeOffsetToken="[string]Time offset token",
})
```


---

### Gs2Grade:MultiplyAcquireActionsByUserId

Multiply acquire actions by grade-based rate

Multiplies the quantities of the specified acquire actions by a rate multiplier determined by the user's current grade.
The rate multiplier is looked up from the grade model's acquireActionRates using the specified rateName and the current grade value.
The multiplied acquire actions are then executed as a transaction, enabling grade-based reward scaling (e.g., higher grades receive more resources).

**Quantity specification supported: NO**

**Reversible action: NO**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| gradeName | string |  | ✓|  |  ~ 128 chars | Grade Model Name<br>The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. |
| propertyId | string |  | ✓|  |  ~ 1024 chars | Property ID<br>A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. |
| rateName | string |  | ✓|  |  ~ 128 chars | Reward Addition Table Name<br>A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. |
| acquireActions | List&lt;AcquireAction&gt; |  | | [] | 0 ~ 100 items | List of Acquire Actions |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Grade:MultiplyAcquireActionsByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "gradeName": "[string]Grade Model Name",
        "propertyId": "[string]Property ID",
        "rateName": "[string]Reward Addition Table Name",
        "acquireActions": [
            {
                "action": "[string]Type of Acquire Action",
                "request": "[string]JSON string of the request used when executing the action"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Grade:MultiplyAcquireActionsByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  gradeName: "[string]Grade Model Name"
  propertyId: "[string]Property ID"
  rateName: "[string]Reward Addition Table Name"
  acquireActions: 
    - action: "[string]Type of Acquire Action"
      request: "[string]JSON string of the request used when executing the action"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("grade").acquire.multiply_acquire_actions_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    gradeName="[string]Grade Model Name",
    propertyId="[string]Property ID",
    rateName="[string]Reward Addition Table Name",
    acquireActions={
        {
            action="[string]Type of Acquire Action",
            request="[string]JSON string of the request used when executing the action"
        }
    },
    timeOffsetToken="[string]Time offset token",
})
```


---