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

# GS2-Showcase 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-Showcase adds to it.

The transaction actions of GS2-Showcase address one display state, identified by the combination of namespace, user, and showcase. It holds which items are on display and how many times each has been bought.

Operation | Repeated in one transaction | Across a nested transaction | Boundary that separates targets
--- | --- | --- | ---
Incrementing and decrementing a purchase count<br>`IncrementPurchaseCountByUserId` `DecrementPurchaseCountByUserId` | Any mix; combined per display item and the values added up. Different items do not affect each other | Added up | namespace, user, showcase
Redrawing a display<br>`ForceReDrawByUserId` | Combined; the redraw happens once | Fails | namespace, user, showcase

Purchase counts are written per display item, so counts for different items never collide. A count has to stay at or below the limit set on that item and cannot go below zero. It is judged against the total after combining, so an increment that fits on its own can still be rejected when combined with another one.

A redraw replaces the whole display, including which items appear, so it cannot sit alongside a purchase count change on the same showcase even though the counts live under it. Split the transaction.

### Take care with nested transactions

Purchase counts are safe across a nested transaction: they are applied together as one update whichever route they arrive by.

A redraw is not. A redraw arriving from the inside while a purchase count change is specified on the outside makes the transaction fail.

### If you want to avoid these restrictions

Redrawing a display and decrementing a purchase count are acquire actions; incrementing a purchase count is a consume action. Turning `acquireActionUseJobQueue` on clears a collision between a redraw and a decrement, but a redraw together with an increment needs `enableAtomicCommit` turned off.

### Concurrency and retries

Purchase count changes do not conflict however many concurrent requests overlap, as long as the result stays within range.

A redraw rewrites the display as a whole, so it returns a conflict (409) when another update to the same showcase overlaps. Nothing is wrong with the request, so retrying will succeed.

---



## Consume Action



### Gs2Showcase:IncrementPurchaseCountByUserId

Increment the number of times a Random Displayed Item has been purchased by specifying the user ID

Increments the purchase count for a specific Random Displayed Item in the Random Showcase for the specified user. Used for tracking purchase limits per rotation period.

**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 (.). |
| showcaseName | string |  | ✓|  |  ~ 128 chars | Random Showcase Name |
| displayItemName | string |  | ✓|  |  ~ 128 chars | Number of Random Displayed Item purchases name<br>The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| count | int |  | ✓|  | 0 ~ 100 | Number of purchase times to add |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Showcase:IncrementPurchaseCountByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "showcaseName": "[string]Random Showcase Name",
        "displayItemName": "[string]Number of Random Displayed Item purchases name",
        "userId": "[string]User ID",
        "count": "[int]Number of purchase times to add",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Showcase:IncrementPurchaseCountByUserId
request:
  namespaceName: "[string]Namespace name"
  showcaseName: "[string]Random Showcase Name"
  displayItemName: "[string]Number of Random Displayed Item purchases name"
  userId: "[string]User ID"
  count: "[int]Number of purchase times to add"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("showcase").consume.increment_purchase_count_by_user_id({
    namespaceName="[string]Namespace name",
    showcaseName="[string]Random Showcase Name",
    displayItemName="[string]Number of Random Displayed Item purchases name",
    userId="[string]User ID",
    count="[int]Number of purchase times to add",
    timeOffsetToken="[string]Time offset token",
})
```


---

## Acquire Action



### Gs2Showcase:DecrementPurchaseCountByUserId

Decrement the number of times a Random Displayed Item has been purchased by specifying the user ID

Decrements the purchase count for a specific Random Displayed Item in the Random Showcase. Used to reverse purchases or adjust purchase counters.

**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 (.). |
| showcaseName | string |  | ✓|  |  ~ 128 chars | Random Showcase Name |
| displayItemName | string |  | ✓|  |  ~ 128 chars | Number of Random Displayed Item purchases name<br>The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| count | int |  | ✓|  | 0 ~ 100 | Number of purchase times to subtract |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "action": "Gs2Showcase:DecrementPurchaseCountByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "showcaseName": "[string]Random Showcase Name",
        "displayItemName": "[string]Number of Random Displayed Item purchases name",
        "userId": "[string]User ID",
        "count": "[int]Number of purchase times to subtract",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Showcase:DecrementPurchaseCountByUserId
request:
  namespaceName: "[string]Namespace name"
  showcaseName: "[string]Random Showcase Name"
  displayItemName: "[string]Number of Random Displayed Item purchases name"
  userId: "[string]User ID"
  count: "[int]Number of purchase times to subtract"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("showcase").acquire.decrement_purchase_count_by_user_id({
    namespaceName="[string]Namespace name",
    showcaseName="[string]Random Showcase Name",
    displayItemName="[string]Number of Random Displayed Item purchases name",
    userId="[string]User ID",
    count="[int]Number of purchase times to subtract",
    timeOffsetToken="[string]Time offset token",
})
```


---

### Gs2Showcase:ForceReDrawByUserId

Re-draw the contents of the Random Showcase by User ID

Forces a redraw of the random showcase items for the specified user, resetting the current selection and triggering a new random item selection from the configured pool.

**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 (.). |
| showcaseName | string |  | ✓|  |  ~ 128 chars | Random Showcase Name |
| 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": "Gs2Showcase:ForceReDrawByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "showcaseName": "[string]Random Showcase Name",
        "userId": "[string]User ID",
        "timeOffsetToken": "[string]Time offset token"
    }
}
```

**YAML**
```yaml

action: Gs2Showcase:ForceReDrawByUserId
request:
  namespaceName: "[string]Namespace name"
  showcaseName: "[string]Random Showcase Name"
  userId: "[string]User ID"
  timeOffsetToken: "[string]Time offset token"
```

**GS2-Script**
```lua

transaction.service("showcase").acquire.force_re_draw_by_user_id({
    namespaceName="[string]Namespace name",
    showcaseName="[string]Random Showcase Name",
    userId="[string]User ID",
    timeOffsetToken="[string]Time offset token",
})
```


---