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

# GS2-LoginReward Transaction Actions

Specification of verify/consume/acquire transaction actions




## Combining actions, and concurrency

The background common to every service is collected in [Combining Transaction Actions](). Read that first; the rest of this section is what GS2-LoginReward adds to it.

The transaction actions of GS2-LoginReward address one receive status, identified by the combination of namespace, user, and bonus model. It records which steps have been received, as one row holding the whole list.

Operation | Repeated in one transaction | Across a nested transaction | Boundary that separates targets
--- | --- | --- | ---
Marking a step as received<br>`MarkReceivedByUserId` | **Folded into one if the steps are identical; an error (400) if they differ** | Passes if identical; fails if they differ | namespace, user, bonus model
Unmarking a step<br>`UnmarkReceivedByUserId` | **Folded into one if the steps are identical; an error (400) if they differ** | Passes if identical; fails if they differ | namespace, user, bonus model
Discarding the receive status<br>`DeleteReceiveStatusByUserId` | Combined into one | Fails | namespace, user, bonus model

**Do not take several steps in one transaction.** The whole list of received steps lives in one row that is rewritten as a whole, so the boundary cannot be split per step. Two marks for different steps cannot be combined and are rejected with an error (400) while the transaction is put together. Two marks for the same step are folded into one. Issue one transaction per step.

Marking and unmarking are separate rows sharing a boundary, so a step cannot be marked and unmarked in one transaction. Taking a reward is expressed as a mark, and the reward is paid on the strength of that mark.

Discarding the receive status removes it whole rather than changing its contents, so it cannot sit alongside anything else on that status.

### Take care with nested transactions

A step marked from the inside collides with the same receive status touched from the outside, and the transaction fails. Both routes now behave the same way: whether within one transaction or across a nested one, marks for different steps are an error.

### If you want to avoid these restrictions

Marking is a consume action; unmarking and discarding the receive status are acquire actions. Turning `acquireActionUseJobQueue` on clears a collision between an unmark and a discard, but a collision with a mark needs `enableAtomicCommit` turned off. Neither setting makes several marks for different steps safe: they are rejected while the transaction is put together.

### Concurrency and retries

The receive status is rewritten as a whole with a revision check, so concurrent updates to the same status make the one confirmed later return a conflict (409). Nothing is wrong with the request, so retrying will succeed.

---



## Consume Action



### Gs2LoginReward:MarkReceivedByUserId

Mark as received by User ID

Manually marks a specific step as received for the specified user's bonus model.

**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 (.). |
| bonusModelName | string |  | ✓|  |  ~ 128 chars | Bonus Model Name<br>The name of the Login Bonus Model that this receive status is associated with.<br>Links the user's receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| stepNumber | int |  | ✓|  | 0 ~ 100 | Step Number |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2LoginReward:MarkReceivedByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "bonusModelName": "[string]Bonus Model Name",
        "userId": "[string]User ID",
        "stepNumber": "[int]Step Number",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2LoginReward:MarkReceivedByUserId
request:
  namespaceName: "[string]Namespace name"
  bonusModelName: "[string]Bonus Model Name"
  userId: "[string]User ID"
  stepNumber: "[int]Step Number"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("loginReward").consume.mark_received_by_user_id({
    namespaceName="[string]Namespace name",
    bonusModelName="[string]Bonus Model Name",
    userId="[string]User ID",
    stepNumber="[int]Step Number",
    timeOffsetToken="[string]Time offset token",
})
```


---

## Acquire Action



### Gs2LoginReward:DeleteReceiveStatusByUserId

Delete Receive Status by User ID

Deletes all receive status data for the specified user's bonus model, completely resetting the bonus progress.

**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 (.). |
| bonusModelName | string |  | ✓|  |  ~ 128 chars | Bonus Model Name<br>The name of the Login Bonus Model that this receive status is associated with.<br>Links the user's receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2LoginReward:DeleteReceiveStatusByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "bonusModelName": "[string]Bonus Model Name",
        "userId": "[string]User ID",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2LoginReward:DeleteReceiveStatusByUserId
request:
  namespaceName: "[string]Namespace name"
  bonusModelName: "[string]Bonus Model Name"
  userId: "[string]User ID"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("loginReward").acquire.delete_receive_status_by_user_id({
    namespaceName="[string]Namespace name",
    bonusModelName="[string]Bonus Model Name",
    userId="[string]User ID",
    timeOffsetToken="[string]Time offset token",
})
```


---

### Gs2LoginReward:UnmarkReceivedByUserId

Unmark as received by User ID

Reverses a previously marked step back to unreceived for the specified user's bonus model.
If the specified step was not marked as received, an error is returned.

**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 (.). |
| bonusModelName | string |  | ✓|  |  ~ 128 chars | Bonus Model Name<br>The name of the Login Bonus Model that this receive status is associated with.<br>Links the user's receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| stepNumber | int |  | ✓|  | 0 ~ 100 | Step Number |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2LoginReward:UnmarkReceivedByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "bonusModelName": "[string]Bonus Model Name",
        "userId": "[string]User ID",
        "stepNumber": "[int]Step Number",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2LoginReward:UnmarkReceivedByUserId
request:
  namespaceName: "[string]Namespace name"
  bonusModelName: "[string]Bonus Model Name"
  userId: "[string]User ID"
  stepNumber: "[int]Step Number"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("loginReward").acquire.unmark_received_by_user_id({
    namespaceName="[string]Namespace name",
    bonusModelName="[string]Bonus Model Name",
    userId="[string]User ID",
    stepNumber="[int]Step Number",
    timeOffsetToken="[string]Time offset token",
})
```


---