Content
Introduction
In this guide you’ll learn:
How to configure Game Products and Shop Products
How to configure a shop in your game
How to configure payments
Table of Contents
Payments in Hawk
Payments is the section that allows you to configure in-app purchases (IAP) in your game.
There are two main types of in-app purchases that can be made in Tripledot’s games:
Consumables: assets that provide further progress in a game like gems, coins, chips, etc. Consumable in‑app purchases are depleted as they’re used and can be purchased again. An example of consumable assets are extra chips in Blackjack, coins in Woodoku, etc.
Non-consumables: non-consumables are premium features that are purchased once and don’t expire. Examples include additional filters in a photo app, characters' new clothes/weapons in a game, etc. The main check here is to ensure that non-consumable purchase is saved through updates and reinstall, and cannot be purchased multiple times. An example of a non-consumable asset would be being able to pay so that no ads are shown in Blackjack.
However, please note that Hawk does not make any difference in practical terms regarding these two types of IAPs.
Game Products and Shop Products in Hawk
Game Products and Store Products are the core of the Payments system in Hawk.
Game Products are the actual bundles of items to sell in your shop. Store products are the bundles with the price point to sell in the device app store, and all of them are composed of Game Items , which are created in Game Server.
Configuring Game Items
Game Items, which are the consumable elements that can be bundled in Store Products and purchased in the App Store, are configured in Game Server.
In your game, navigate to Game Items, and click [New].
Add a name to your item and select the type of item. Click [Save] when you’re done.
Once the items have been created in Game Server, it’s time to configure them in Hawk.
About Game Items
The type of items that can be configured are determined by the Client.
Game Items are created in Game Server because they are part of the core logic of the games, and are game-specific. Hawk, on the other side, as a Live Ops system, it can only operate with these items, but not create them.
Game Items are synchronised with Hawk every hour, but this can be manually forced by clicking [Synchronize] in Hawk > Payments > Game Items
Creating Game Products
As mentioned above, a Game Product is the bundle of Game Items that can be sold as an offer in the game. These bundles are created in Hawk , and can have more than one type of item inside (this depends on the configuration of your game).
To configure Game Products, follow these steps:
In Hawk, navigate to your Game, and select Payments > Game Products. In this page you’ll be able to see the existing products, and where are they being used. Game Products can be used in more than one store, and the display name is localisable.
Click [+ Add Game Product] to create a new bundle. Add a new name, select a localisation key (if required, called Display Name Key in Hawk), and select a Product Image.
Then, click [+Add] to create your bundle of items. From the dropdown, select your item, and type in the amount. Click [+Add] again to add more items.
About Localisation Keys and Product Images
The display name of the Game Product can be localised, however, the contents are not localisable. Localisation Keys are created and synchronised from Game Server. Read this page to know more.
Product Images are created in Hawk. To add a new image, navigate to Payments > Product Images , and upload a new image.
Configuring Store Products
Store Products are the abstract entity of Game Products that is used on the device App Store, such as App Store for iOS or Google Play Store for Android. Store Items have the price point that will be used in the device App Store, and they are also used in Catalogs to determine the price of the items in the shop.
To create a new Store Product, follow the steps below:
In your game, navigate to Payments > Store Products. In this page you’ll be able to see the existing products, their prices and in which catalogs they’re being used. To create a new Product, click [+Add Store Product] on the upper right corner of the screen.
Then, add a price point, and the Store ID will be generate automatically following the naming convention. Click [Save] when you’re done.
Store Products Naming Convention
The naming convention for Store Products is the following: <denominator>_package_<game>
Example: 0.99_package_woodoku
Creating a Catalog in Hawk
Catalogs are where you configure the items to sell in your shop. Catalogs are A/B testable and can be targeted to different segments of users.
About Segments in Catalogs
Remember that Catalogs are created per segment. If you’d like to create a different shop for another segment, please create a new Catalog.
In Hawk, select your app from the dropdown menu, and then navigate to Payments > Catalogs. Click [+ Add Catalog] to create a new one.
Add a name to your catalog, assign a status and availability. Assign it to an existing segment and provide it with a priority.
Click the “Edit configuration” toggle to start configuring your shop. Once enabled, click [+Add] to add products.
Then, fill in the fields. A description of each of the fields can be found in the table below:
| Field | Description | Validations |
| ID Product | The product you will be selling in the store. The data in this field comes from Game Items | Dropdown with the game products to sell |
| Price Type | The type of item you are selling in the store. | - Store Product - In-game Currency - Ads - Free |
| Price | The price of the bundle in the App Store. This information comes from the items in Store Products. | Dropdown |
| Platform | The App Store where you want to sell your items. | - All - iOS - Android |
| Line Group | This field determines where in the shop your catalog will be located. Shop Items with the same Line Group will be presented in the same line to players. | Number |
| Label | Label to appear in the App Store, which are used to highlight a special offer or similar. They can be configured from Payments > Product Labels. | Dropdown with existing labels 
|
| Purchase restrictions | This field determines how many times can the item be purchased by the player. | - None: no restrictions apply - Purchase Limit: Integer value for the number of items that can be purchased/claimed - Purchase Cooldown: Time between two consecutive items are available for purchase/claim. Specify the time in hours and minutes. |
| Sale Type | This field determines the type of sale that applies to this shop. Not applicable for Ads or Free items. | - None: no special sale - More Value: more products for the same price. - Price Cut: lower price. If this is selected, a new dropdown will appear where you can select a new price. - Extra Amount: more items for the same price. 
|
| Sale Value | Value that is charged for the sale. | You can specify the sale value based on the sale type. It is to be specified as a % value for more value type and in float form for price cut and extra amount sale types. |
| Items Rounding Type | This field is enabled if “More value” is selected under sale type. The calculation is determined by the Client development Team. | - Round up - Round down - Math rounding: chooses the number closer to 0 or 1 as determined by the client dev team. |
Do you need support?
If you need support, you can obtain the Entity Variant ID from any Catalog. This will help the Hawk team identify better your issue.
Configuring Presets
Presets are specific reusable stores that are intended to be used for recurring or seasonal sales. These Presets will appear under Catalogs > Shop and even though they target the same segment of users, they offer a different set of products.
To configure a new Preset, navigate to Payments > Presets. In this section, you’ll be able to see the existing presets and in which catalog they’re being used. The short video below shows to create a preset.
Once the preset has been created, it will be available to use and configure in any Catalog:
Product Labels
Product Labels are the banners that appear in the shop pop-up to indicate a sale type, which are configurable inside Catalogs in Hawk. They are, however, created in the Product Labels in Hawk.
To create labels, follow the steps below:
Navigate to Payments > Product Labels. In this page you’ll be able to see a list of existing labels, their key, and edit them if needed.
Click [+ Add Label] on the upper right corner.
Add a name and a key for your label.
Under Label Key , select the localisation key from the dropdown. When you’re done, click [Save].
About Localisation of Labels
Labels can be localised and the localisation Keys are created and synchronised from Game Server, and synchronised via API.
Read this page to know how to create localisation keys.
Configuring Sections
Sections allow you to create different sections in the shop, such as expanded and collapsed views of the shop. This can be configured through Sections in Hawk.
1. In your app, navigate to Payments > Sections , and click [Add Section].
Add the name of the section and the key. Fill in as well the minimum and maximum number of items to display (not compulsory).
The new section will appear on the Catalog. To configure it, toggle [Edit Configuration].
Configuring Free Items and Cooldown Rules in the Catalog
Giving players occasional free rewards like hints or in-game items increases engagement and encourages them to return regularly.
In a game, you can configure an item to be claimed once every X hours/minutes or under a custom cooldown or usage limit.
The Price Type defines how a player can acquire an item in the store. This setting determines whether an item costs real money, in-game currency, an ad view, or is available for free.
To configure Free items and cooldown rules in the catalog, follow these steps:
In the Price Type dropdown, select the Free option.
Populate the Platform , Line Group , and Label fields as described in the table above.
You’ll see a Purchase Restriction column in the catalog table. This is where you define how often the item can be claimed.Click the gear icon opens a configuration panel where you can choose one of the following:
None: No restrictions. Item can be claimed freely (not allowed for free items).
Purchase Limit: Set how many times a player can claim the item (e.g.: 3). Refer to the Configuring Purchase Limits in the Catalog section for more details.
Purchase Cooldown: Set a cooldown timer (e.g.: 24h), so the item can be claimed once per period. (Not allowed for in-game currency & store product items)
You cannot enter 0 as a value for limit or cooldown.
What Happens When the Catalog Changes?
Scenario 1: Cooldown Adjusts When Item Persists Across Catalog Changes
This example shows how cooldown behaves when the player is switched between segments with different catalogs, but the item remains available throughout the journey:
Scenario:
Tuesday: Item "123" is claimed while in Catalog A, which has a 24h cooldown.
Thursday: Player moves to Segment B, with Catalog B where the same item has a 12h cooldown.
Friday: Item is available again and claimed. A new 12h cooldown begins per Catalog B's rule.
Monday: Segment switches to Catalog C, which still includes item "123" with a 12h cooldown.
Key Behaviour:
The item is preserved during all catalog transitions.
The cooldown adjusts relative to the new catalog’s rules.
Remaining cooldown time is recalculated when switching to a catalog where the item exists.
Scenario 2: Item Removed from the Catalog when the item does not exist in the new segment
Let us understand this scenario with the help of an example:
| Day | Event | Segment |
| --- | --- | --- |
| Tuesday | Item "123" claimed from Segment A (24h cooldown) | A |
| Wednesday and Thursday | Item is claimed after the cooldown. On Thursday the segment switches to B; There is a new catalog. Cooldown is now 12h, but existing 24h cooldown persists but with some recalculations and readjustments according to the new countdown. For example, if 2h has already passed since the last claim and the new cooldown is 12h, the item will become claimable again after 10h. | B |
| Friday | One more claim made, now using the 12h cooldown | B |
| Saturday | Claim is not made made again (12h rule continues) | B |
| Next Monday | Segment C removes the item entirely: cooldown now irrelevant | C |
Scenario 3: Item removed from a segment and reintroduced in the new segment
| Day | Event | Segment |
| --- | --- | --- |
| Tuesday | Item "123" claimed from Segment A (24h cooldown) | A |
| Wednesday | Item is available after the cooldown. It is claimed. | B |
| Thursday | Segment switches to B; During the cooldown, the item is removed from segment A. Cooldown recalculates to the cooldown of the new segment.(12h) | B |
| Friday | Claim is made again (12h rule continues) | B |
| Saturday onwards | Cycles of cooldown and item availability continue | B |
Scenario 4: Catalog Configuration Changes Cooldown Mid-Lifecycle
| Day | Event | Segment |
| --- | --- | --- |
| Tuesday | Item "123" claimed from Segment A (24h cooldown) | A |
| Wednesday | Item is available after the cooldown. It is claimed. | A |
| Thursday | Configuration changes and the new cooldown is 12h. Item is available to be claimed after 12h. | A |
| Friday | Claim is made made again (12h rule continues) | A |
| Saturday | Cycle of cooldown and item availability continue | A |
| Sunday | Segment changes during mid-lifecycle of the cooldown. The new segment’s catalog does not have item "123". This item will no longer be served regardless of the remaining cooldown. | C |
Key Takeaways
Cooldowns Are Claim-Based, Not Segment-Based
The cooldown is tied to the moment of the last successful claim, not to catalog changes or segment transitions.
The server tracks cooldowns on a per-player, per-item basis.
Cooldown Persists Across Catalog Changes (If Item Remains)
If the item remains available in the catalog after a change, any existing cooldown continues, but the server may recalculate the remaining cooldown based on the new cooldown configuration.
In both cases, if the item still exists:
The cooldown doesn’t restart.
Instead, the server adjusts the remaining time based on how much time has passed since the last claim and the new cooldown value from the updated catalog.
Cooldown Persists Across Catalog Changes (If Item Remains)
- If the item remains in the catalog after a segment change:
New Cooldown Config Applies After Next Claim
- If the cooldown configuration changes while the item stays in the catalog:
Cooldown Resets if Item Is Removed and Re-Added
- If the item is removed from one segment and introduced in another
Cooldown Becomes Irrelevant When Item Is Removed
- If the item is completely removed from the catalog:
Catalog changes can happen through:
Segment transitions (e.g., user moves from Segment A to Segment B)
Variant switches in an A/B experiment (e.g., different catalog versions for the same segment)
Configuring Purchase Limits in the Catalog
As a Hawk user, you can configure purchase limits for game products to simplify client-side logic by managing purchase restrictions within Hawk. This feature allows you to define purchase limits on game products and ensures that these limits are enforced without additional client-side complexity.
To configure the purchase limits:
Navigate to the Payments Section.
From the left-hand menu, click on Catalogs under the Payments section.
A list of existing catalogs will appear on the screen.
Select a catalog to edit or add a new catalog.
The catalog's detailed configuration panel will appear at the bottom of the screen.
Scroll down to the Entity Variant ID section, where you'll see various configuration settings for products.
Switch on the Edit Configuration toggle.
In the product table under the Expanded View , locate the column labeled Purchase Restrictions.
Find the relevant product in the list (identified by its ID and Product name).
Select the Purchase Limit option and input the number of times the product can be purchased by a player.
Optional: Configure Additional Fields (If Needed).
Price Type: Select the type of price (Store product, etc.).
Price: Enter the price for the product.
Platform: Select the platforms where the product will be available (All, iOS, Android, etc.).
Label: Set a label for the product (e.g., Best Value).
Sale Type & Sale Value: If any discounts or sales are applied to the product, you can configure them here.After setting the Purchase Limit and other configurations as needed, scroll to the bottom and click the Save button.
The updated purchase limit settings will now be applied to the selected catalog.
Purchase Limit: Different Scenarios.
Scenario: A game product in the catalog has a purchase limit set to 1.
When the player purchases the game product,
Then the player will not be able to purchase the item again (the purchase limit has been reached). Once the purchase limit is reached, the server will no longer serve the game product in the store response.
Note: If the purchase limit is set to None , there are no restrictions, and the player can purchase the item multiple times.
Adjusting Purchase Limits in a Live Entity
S cenario A: Increasing Purchase Limit
Context: A game product in the catalog has a purchase limit.
When the player has already purchased the maximum quantity of the product based on the purchase limit,
And the purchase limit is increased,
Then the product will become available in the store for the player to purchase again.
Scenario B: Decreasing Purchase Limit
Context: A game product in the catalog has a purchase limit, and the player still has the availability to purchase the game product.
When the purchase limit is decreased,
Then the player will no longer see the product in the store (if the new limit has already been met or exceeded).
Catalog Product ID Attribute
Context: Game products in the catalog now include a new attribute,
catalog_product_id, which is a unique identifier for each item across different catalogs.Action: The
catalog_product_idwill be passed as an optional parameter with thepurchase_successtrigger to identify the specific product.
Tracking Purchases with Limitations
Hawk will track how many purchases a player has made for specific game products with purchase limitations.
Player Page Updates
In the Purchases section, a new table will be available to view purchase limits. The table will show:
Game products currently available to the player with a purchase limit.
Historical game products with a purchase limit were served to the player.
Handling Segment and Catalog Switching
Scenario: A game product is restricted by a purchase limit across different player segments.
Context: A game product (X) is in catalog A, which is assigned to segment A, and it has a purchase limit set to 1.
When the player, belonging to segment A, purchases game product X,
And the product is no longer available to the player due to the purchase limit being reached,
And the player switches segments to segment B (served by catalog B),
And later switches back to segment A (served by catalog A),
Then game product X will still not be available in catalog A for the player, as the purchase limit has already been reached.
Live Entity Adjustments: Changes to purchase limits in the live entity will dynamically affect the product availability in the store for players.
Unique Product Tracking: The
catalog_product_idensures each product is tracked uniquely across various catalogs, preventing overlap or misidentification in cross-segment product offerings.
🔍 Frequently Asked Questions
About Payments Database
All the information about Payment Intents/Payment Success can be found in Looker. For further information, please contact the BI/DS&E teams.
In Redash, you can also access to the information for transactions and intents. To do so, please look for:
gs_payments_transactionsgs_payments_intentsHow does a user qualify to receive Catalogs?
Chunks 3
**Introduction**
In this guide you’ll learn:
- How to configure Game Products and Shop Products
- How to configure a shop in your game
- How to configure payments
**Table of Contents**
* * *
## Payments in Hawk
Payments is the section that allows you to configure in-app purchases (IAP) in your game.
There are two main types of in-app purchases that can be made in Tripledot’s games:
- **Consumables:** assets that provide further progress in a game like gems, coins, chips, etc. Consumable in‑app purchases are depleted as they’re used and can be purchased again. An example of consumable assets are extra chips in Blackjack, coins in Woodoku, etc.
- **Non-consumables:** non-consumables are premium features that are purchased once and don’t expire. Examples include additional filters in a photo app, characters' new clothes/weapons in a game, etc. The main check here is to ensure that non-consumable purchase is saved through updates and reinstall, and cannot be purchased multiple times. An example of a non-consumable asset would be being able to pay so that no ads are shown in Blackjack.
However, please note that Hawk does not make any difference in practical terms regarding these two types of IAPs.
## Game Products and Shop Products in Hawk
Game Products and Store Products are the core of the Payments system in Hawk.
Game Products are the actual bundles of items to sell in your shop. Store products are the bundles with the price point to sell in the device app store, and all of them are composed of **Game Items** , which are created in **Game Server.**
### Configuring Game Items
Game Items, which are the consumable elements that can be bundled in Store Products and purchased in the App Store, **are configured in Game Server. **
1. In your game, navigate to Game Items, and click **[New]**.
2. Add a name to your item and select the type of item. Click **[Save]** when you’re done.
Once the items have been created in Game Server, it’s time to configure them in Hawk.
**About Game Items**
- The type of items that can be configured are determined by the Client.
- Game Items are created in Game Server because they are part of the core logic of the games, and are game-specific. Hawk, on the other side, as a Live Ops system, it can only operate with these items, but not create them.
- Game Items are synchronised with Hawk every hour, but this can be manually forced by clicking **[Synchronize]** in **Hawk \> Payments \> Game Items**
### Creating Game Products
As mentioned above, a **Game Product is the bundle of Game Items** that can be sold as an offer in the game. These bundles are **created in Hawk** , and can have more than one type of item inside (this depends on the configuration of your game).
To configure Game Products, follow these steps:
1. In Hawk, navigate to your Game, and select **Payments \> Game Products**. In this page you’ll be able to see the existing products, and where are they being used. Game Products can be used in more than one store, and the display name is localisable.
2. Click **[+ Add Game Product]** to create a new bundle. Add a new name, select a localisation key (if required, called Display Name Key in Hawk), and select a Product Image.
3. Then, click **[+Add]** to create your bundle of items. From the dropdown, select your item, and type in the amount. Click **[+Add]** again to add more items.
**About Localisation Keys and Product Images**
- The display name of the Game Product can be localised, however, the contents are not localisable. Localisation Keys are created and synchronised from Game Server. Read [this page](/wiki/spaces/KB/pages/3230760961/Managing+Localisations+in+Harmony) to know more.
- Product Images are created in Hawk. To add a new image, navigate to **Payments \> Product Images** , and upload a new image.
### Configuring Store Products
Store Products are the abstract entity of Game Products that is used on the device App Store, such as App Store for iOS or Google Play Store for Android. Store Items have the price point that will be used in the device App Store, and they are also used in Catalogs to determine the price of the items in the shop.
To create a new Store Product, follow the steps below:
1. In your game, navigate to **Payments \> Store Products**. In this page you’ll be able to see the existing products, their prices and in which catalogs they’re being used. To create a new Product, click **[+Add Store Product]** on the upper right corner of the screen.
2. Then, add a price point, and the Store ID will be generate automatically following the naming convention. Click **[Save]** when you’re done.
**Store Products Naming Convention**
The naming convention for Store Products is the following: `_package_`
Example: `0.99_package_woodoku`
## Creating a Catalog in Hawk
Catalogs are where you configure the items to sell in your shop. Catalogs are A/B testable and can be targeted to different segments of users.
**About Segments in Catalogs**
Remember that **Catalogs are created per segment**. If you’d like to create a different shop for another segment, please create a new Catalog.
1. In Hawk, select your app from the dropdown menu, and then navigate to **Payments \> Catalogs.** Click **[+ Add Catalog]** to create a new one.
2. Add a name to your catalog, assign a status and availability. Assign it to an existing segment and provide it with a priority.
3. Click the **“Edit configuration”** toggle to start configuring your shop. Once enabled, click **[+Add]** to add products.
4. Then, fill in the fields. A description of each of the fields can be found in the table below:
| **Field** | **Description** | **Validations** |
| **ID Product** | The product you will be selling in the store. The data in this field comes from Game Items | Dropdown with the game products to sell |
| **Price Type** | The type of item you are selling in the store. | - Store Product - In-game Currency - Ads - Free |
| **Price** | The price of the bundle in the App Store. This information comes from the items in Store Products. | Dropdown |
| **Platform** | The App Store where you want to sell your items. | - All - iOS - Android |
| **Line Group** | This field determines where in the shop your catalog will be located. Shop Items with the same Line Group will be presented in the same line to players. | Number |
| **Label** | Label to appear in the App Store, which are used to highlight a special offer or similar. They can be configured from **Payments \> Product Labels.** | Dropdown with existing labels  |
| **Purchase restrictions** | This field determines how many times can the item be purchased by the player. | - **None:** no restrictions apply - **Purchase Limit:** Integer value for the number of items that can be purchased/claimed - **Purchase Cooldown:** Time between two consecutive items are available for purchase/claim. Specify the time in hours and minutes. |
| **Sale Type** | This field determines the type of sale that applies to this shop. Not applicable for Ads or Free items. | - **None:** no special sale - **More Value:** more products for the same price. - **Price Cut:** lower price. If this is selected, a new dropdown will appear where you can select a new price. - **Extra Amount:** more items for the same price.  |
| **Sale Value** | Value that is charged for the sale. | You can specify the sale value based on the sale type. It is to be specified as a % value for more value type and in float form for price cut and extra amount sale types. |
| **Items Rounding Type** | This field is enabled if “More value” is selected under sale type. The calculation is determined by the Client development Team. | - **Round up** - **Round down** - **Math rounding:** chooses the number closer to 0 or 1 as determined by the client dev team. |
**Do you need support?**
If you need support, you can obtain the Entity Variant ID from any Catalog. This will help the Hawk team identify better your issue.
## Configuring Presets
Presets are specific **reusable stores** that are intended to be used for recurring or seasonal sales. These Presets will appear under **Catalogs \> Shop** and even though they target the same segment of users, they offer a different set of products.
To configure a new Preset, navigate to **Payments \> Presets**. In this section, you’ll be able to see the existing presets and in which catalog they’re being used. The short video below shows to create a preset.
Once the preset has been created, it will be available to use and configure in any Catalog:
Product Labels
Product Labels are the banners that appear in the shop pop-up to indicate a sale type, which are configurable inside Catalogs in Hawk. They are, however, created in the Product Labels in Hawk.
To create labels, follow the steps below:
1. Navigate to **Payments \> Product Labels**. In this page you’ll be able to see a list of existing labels, their key, and edit them if needed.
2. Click **[+ Add Label]** on the upper right corner.
3. Add a name and a key for your label.
4. Under **Label Key** , select the localisation key from the dropdown. When you’re done, click **[Save].**
**About Localisation of Labels**
Labels can be localised and the localisation Keys are created and synchronised from Game Server, and synchronised via API.
Read [this page](/wiki/spaces/KB/pages/3230760961/Managing+Localisations+in+Harmony) to know how to create localisation keys.
## Configuring Sections
Sections allow you to create different sections in the shop, such as expanded and collapsed views of the shop. This can be configured through Sections in Hawk.
1. In your app, navigate to **Payments \> Sections** , and click **[Add Section]**.
2. Add the name of the section and the key. Fill in as well the minimum and maximum number of items to display (not compulsory).
3. The new section will appear on the Catalog. To configure it, toggle **[Edit Configuration].**
* * *
## Configuring Free Items and Cooldown Rules in the Catalog
Giving players occasional free rewards like hints or in-game items increases engagement and encourages them to return regularly.
In a game, you can configure an item to be claimed once every X hours/minutes or under a custom cooldown or usage limit.
The Price Type defines how a player can acquire an item in the store. This setting determines whether an item costs real money, in-game currency, an ad view, or is available for free.
To configure Free items and cooldown rules in the catalog, follow these steps:
1. In the **Price Type** dropdown, select the **Free** option.
2. Populate the **Platform** , **Line Group** , and **Label** fields as described in the [table](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/2916810950#ec89fc41-9bd6-4624-807d-a5657f53a587) above.
You’ll see a **Purchase Restriction** column in the catalog table. This is where you define how often the item can be claimed.
3. Click the gear icon opens a configuration panel where you can choose one of the following:
**None:** No restrictions. Item can be claimed freely (not allowed for free items).
**Purchase Limit:** Set how many times a player can claim the item (e.g.: 3). Refer to the [Configuring Purchase Limits in the Catalog](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/2916810950/Payments+and+Shop+Configuration+in+Hawk#Configuring-Purchase-Limits-in-the-Catalog) section for more details.
**Purchase Cooldown:** Set a cooldown timer (e.g.: 24h), so the item can be claimed once per period. (Not allowed for in-game currency & store product items)
You cannot enter 0 as a value for limit or cooldown.
### What Happens When the Catalog Changes?
**Scenario 1: Cooldown Adjusts When Item Persists Across Catalog Changes**
This example shows how cooldown behaves when the player is switched between segments with different catalogs, but the item remains available throughout the journey:
**Scenario:**
- Tuesday: Item "123" is claimed while in Catalog A, which has a 24h cooldown.
- Thursday: Player moves to Segment B, with Catalog B where the same item has a 12h cooldown.
- Friday: Item is available again and claimed. A new 12h cooldown begins per Catalog B's rule.
- Monday: Segment switches to Catalog C, which still includes item "123" with a 12h cooldown.
**Key Behaviour:**
- The item is preserved during all catalog transitions.
- The cooldown adjusts relative to the new catalog’s rules.
- Remaining cooldown time is recalculated when switching to a catalog where the item exists.
**Scenario 2: Item Removed from the Catalog when the item does not exist in the new segment**
Let us understand this scenario with the help of an example:
| **Day** | **Event** | **Segment** |
| --- | --- | --- |
| Tuesday | Item "123" claimed from Segment A (24h cooldown) | A |
| Wednesday and Thursday | Item is claimed after the cooldown. On Thursday the segment switches to B; There is a new catalog. Cooldown is now 12h, but existing 24h cooldown persists but with some recalculations and readjustments according to the new countdown. For example, if 2h has already passed since the last claim and the new cooldown is 12h, the item will become claimable again after 10h. | B |
| Friday | One more claim made, now using the 12h cooldown | B |
| Saturday | Claim is not made made again (12h rule continues) | B |
| Next Monday | Segment C removes the item entirely: cooldown now irrelevant | C |
**Scenario 3: Item removed from a segment and reintroduced in the new segment**
| **Day** | **Event** | **Segment** |
| --- | --- | --- |
| Tuesday | Item "123" claimed from Segment A (24h cooldown) | A |
| Wednesday | Item is available after the cooldown. It is claimed. | B |
| Thursday | Segment switches to B; During the cooldown, the item is removed from segment A. Cooldown recalculates to the cooldown of the new segment.(12h) | B |
| Friday | Claim is made again (12h rule continues) | B |
| Saturday onwards | Cycles of cooldown and item availability continue | B |
**Scenario 4:** Catalog Configuration Changes Cooldown Mid-Lifecycle
| **Day** | **Event** | **Segment** |
| --- | --- | --- |
| Tuesday | Item "123" claimed from Segment A (24h cooldown) | A |
| Wednesday | Item is available after the cooldown. It is claimed. | A |
| Thursday | Configuration changes and the new cooldown is 12h. Item is available to be claimed after 12h. | A |
| Friday | Claim is made made again (12h rule continues) | A |
| Saturday | Cycle of cooldown and item availability continue | A |
| Sunday | Segment changes during mid-lifecycle of the cooldown. The new segment’s catalog does not have item "123". This item will no longer be served regardless of the remaining cooldown. | C |
**Key Takeaways**
**Cooldowns Are Claim-Based, Not Segment-Based**
The cooldown is tied to the moment of the last successful claim, not to catalog changes or segment transitions.
The server tracks cooldowns on a per-player, per-item basis.
**Cooldown Persists Across Catalog Changes (If Item Remains)**
If the item remains available in the catalog after a change, any existing cooldown continues, but the server may recalculate the remaining cooldown based on the new cooldown configuration.
In both cases, if the item still exists:
- The cooldown doesn’t restart.
- Instead, the server adjusts the remaining time based on how much time has passed since the last claim and the new cooldown value from the updated catalog.
**Cooldown Persists Across Catalog Changes (If Item Remains)**
- If the item remains in the catalog after a segment change:
**New Cooldown Config Applies After Next Claim**
- If the cooldown configuration changes while the item stays in the catalog:
**Cooldown Resets if Item Is Removed and Re-Added**
- If the item is removed from one segment and introduced in another
**Cooldown Becomes Irrelevant When Item Is Removed**
- If the item is completely removed from the catalog:
**Catalog changes can happen through:**
- Segment transitions (e.g., user moves from Segment A to Segment B)
- Variant switches in an A/B experiment (e.g., different catalog versions for the same segment)
* * *
Configuring Purchase Limits in the Catalog
As a Hawk user, you can configure purchase limits for game products to simplify client-side logic by managing purchase restrictions within Hawk. This feature allows you to define purchase limits on game products and ensures that these limits are enforced without additional client-side complexity.
To configure the purchase limits:
1. Navigate to the **Payments** Section.
2. From the left-hand menu, click on **Catalogs** under the Payments section.
3. A list of existing catalogs will appear on the screen.
4. Select a catalog to edit or add a new catalog.
5. The catalog's detailed configuration panel will appear at the bottom of the screen.
6. Scroll down to the **Entity Variant ID** section, where you'll see various configuration settings for products.
7. Switch on the **Edit Configuration** toggle.
8. In the product table under the **Expanded View** , locate the column labeled **Purchase Restrictions**.
9. Find the relevant product in the list (identified by its ID and Product name).
10. Select the **Purchase Limit** option and input the number of times the product can be purchased by a player.
11. Optional: Configure Additional Fields (If Needed).
**Price Type:** Select the type of price (Store product, etc.).
**Price:** Enter the price for the product.
**Platform:** Select the platforms where the product will be available (All, iOS, Android, etc.).
**Label:** Set a label for the product (e.g., Best Value).
**Sale Type & Sale Value:** If any discounts or sales are applied to the product, you can configure them here.
12. After setting the **Purchase Limit** and other configurations as needed, scroll to the bottom and click the **Save** button.
13. The updated purchase limit settings will now be applied to the selected catalog.
### Purchase Limit: Different Scenarios.
**Scenario:** A game product in the catalog has a purchase limit set to 1.
- When the player purchases the game product,
- Then the player will not be able to purchase the item again (the purchase limit has been reached). Once the purchase limit is reached, the server will no longer serve the game product in the store response.
- **Note:** If the purchase limit is set to **None** , there are no restrictions, and the player can purchase the item multiple times.
**Adjusting Purchase Limits in a Live Entity**
S **cenario A:** Increasing Purchase Limit
- Context: A game product in the catalog has a purchase limit.
- When the player has already purchased the maximum quantity of the product based on the purchase limit,
- And the purchase limit is increased,
- Then the product will become available in the store for the player to purchase again.
**Scenario B:** Decreasing Purchase Limit
- Context: A game product in the catalog has a purchase limit, and the player still has the availability to purchase the game product.
- When the purchase limit is decreased,
- Then the player will no longer see the product in the store (if the new limit has already been met or exceeded).
### Catalog Product ID Attribute
- Context: Game products in the catalog now include a new attribute, `catalog_product_id`, which is a unique identifier for each item across different catalogs.
- Action: The `catalog_product_id` will be passed as an optional parameter with the `purchase_success` trigger to identify the specific product.
### **Tracking Purchases with Limitations**
Hawk will track how many purchases a player has made for specific game products with purchase limitations.
### **Player Page Updates**
In the **Purchases** section, a new table will be available to view purchase limits. The table will show:
- Game products currently available to the player with a purchase limit.
- Historical game products with a purchase limit were served to the player.
### Handling Segment and Catalog Switching
**Scenario:** A game product is restricted by a purchase limit across different player segments.
- Context: A game product (X) is in catalog A, which is assigned to segment A, and it has a purchase limit set to 1.
- When the player, belonging to segment A, purchases game product X,
- And the product is no longer available to the player due to the purchase limit being reached,
- And the player switches segments to segment B (served by catalog B),
- And later switches back to segment A (served by catalog A),
- Then game product X will still not be available in catalog A for the player, as the purchase limit has already been reached.
- **Live Entity Adjustments:** Changes to purchase limits in the live entity will dynamically affect the product availability in the store for players.
- **Unique Product Tracking:** The `catalog_product_id` ensures each product is tracked uniquely across various catalogs, preventing overlap or misidentification in cross-segment product offerings.
* * *
## 🔍 Frequently Asked Questions
**About Payments Database**
All the information about Payment Intents/Payment Success can be found in Looker. For further information, please contact the BI/DS&E teams.
In Redash, you can also access to the information for transactions and intents. To do so, please look for:
- `gs_payments_transactions`
- `gs_payments_intents`
- **How does a user qualify to receive Catalogs?**