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

# GS2-SerialKey Transaction Actions

Specification of verify/consume/acquire transaction actions




## Verify Action



### Gs2SerialKey:VerifyCodeByUserId

Verify the validity of the Serial Code by User ID

Verifies a serial code for the specified user without consuming it. Supports verification against a specific campaign model name, and can check whether the code is active (unused) or inactive (already used).

**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. |
| code | string |  | ✓|  |  ~ 48 chars | Serial Code<br>The serial code string in the format "XXXXX-XXXX-XXXXX-XXXX-XXXX". Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. |
| campaignModelName | string |  | |  |  ~ 128 chars | Campaign name<br>The name of the campaign model this serial code belongs to. Campaign information is embedded within the serial code itself, so only the Namespace needs to be specified when using the code. |
| verifyType | string (enum)<br>enum {<br>"active",<br>"inactive"<br>}<br> |  | ✓|  |  | Verification type"active": Active / "inactive": Inactive /  |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2SerialKey:VerifyCodeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "code": "[string]Serial Code",
        "campaignModelName": "[string]Campaign name",
        "verifyType": "[string]Verification type",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2SerialKey:VerifyCodeByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  code: "[string]Serial Code"
  campaignModelName: "[string]Campaign name"
  verifyType: "[string]Verification type"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("serialKey").verify.verify_code_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    code="[string]Serial Code",
    campaignModelName="[string]Campaign name",
    verifyType="[string]Verification type",
    timeOffsetToken="[string]Time offset token",
})
```


---

## Consume Action



### Gs2SerialKey:UseByUserId

Use Serial Code by User ID

Marks a serial code as used by the specified user. Validates that the code exists and has not already been used.

**Quantity specification supported: NO**

**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. |
| code | string |  | ✓|  |  ~ 48 chars | Serial Code<br>The serial code string in the format "XXXXX-XXXX-XXXXX-XXXX-XXXX". Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2SerialKey:UseByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "code": "[string]Serial Code",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2SerialKey:UseByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  code: "[string]Serial Code"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("serialKey").consume.use_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    code="[string]Serial Code",
    timeOffsetToken="[string]Time offset token",
})
```


---

## Acquire Action



### Gs2SerialKey:RevertUseByUserId

Set Serial Code to Unused by User ID

Reverts a used serial code back to unused status. Validates that the code is currently in used state before reverting.

**Quantity specification supported: NO**

**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. |
| code | string |  | ✓|  |  ~ 48 chars | Serial Code<br>The serial code string in the format "XXXXX-XXXX-XXXXX-XXXX-XXXX". Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2SerialKey:RevertUseByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "code": "[string]Serial Code",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2SerialKey:RevertUseByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  code: "[string]Serial Code"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("serialKey").acquire.revert_use_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    code="[string]Serial Code",
    timeOffsetToken="[string]Time offset token",
})
```


---

### Gs2SerialKey:IssueOnce

Issue a serial code

Issues a single serial code immediately. The code is generated using AES encryption and base32 encoding in the format XXXXX-XXXX-XXXXX-XXXX-XXXXX. Unlike batch issuance jobs, this generates and returns a code synchronously.

**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 (.). |
| campaignModelName | string |  | ✓|  |  ~ 128 chars | Campaign Model name |
| metadata | string |  | |  |  ~ 2048 chars | Metadata<br>Arbitrary values can be set in the metadata.<br>Since they do not affect GS2’s behavior, they can be used to store information used in the game. |




**JSON**
```json
{
    "action": "Gs2SerialKey:IssueOnce",
    "request": {
        "namespaceName": "[string]Namespace name",
        "campaignModelName": "[string]Campaign Model name",
        "metadata": "[string]Metadata"
    }
}
```

**YAML**
```yaml

action: Gs2SerialKey:IssueOnce
request:
  namespaceName: "[string]Namespace name"
  campaignModelName: "[string]Campaign Model name"
  metadata: "[string]Metadata"
```

**GS2-Script**
```lua

transaction.service("serialKey").acquire.issue_once({
    namespaceName="[string]Namespace name",
    campaignModelName="[string]Campaign Model name",
    metadata="[string]Metadata",
})
```


---