> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appcharge.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Personalize Web Store Callback
> > **Note:** This is a callback API. Appcharge calls this endpoint on your server when specific events occur.
Notifies your system to personalize the web store for a player.
Appcharge calls this endpoint when:
- A player logs in to your web store.
- A player completes a purchase.
- Every 5 minutes after the player’s last sync.
Your server responds with the most current player data and all available offers for the player. Appcharge then updates the web store for the player accordingly.
```bash Personalize Web Store theme={"system"}
curl -X POST \
'https://{YOUR_PERSONALIZE_WEBSTORE_ENDPOINT}' \
-H 'Content-Type: application/json' \
-H 'x-publisher-token: ' \
-H 'signature: ' \
-d '{
"playerId": "vip2247691"
}'
```
```json Personalize Web Store theme={"system"}
{
"version": 2,
"logo": "game_logo_main",
"status": "valid",
"sessionMetadata": {
"abTestGroup": "variant_A",
"locale": "en-US",
"campaignId": "summer_2025"
},
"profileFrameId": "diamond_frame",
"playerLevelName": "Diamond Tier",
"bannerExternalId": "welcome_banner_01",
"playerLevel": {
"assetId": "level_diamond",
"text": "15% OFF",
"endsIn": 1735689600000
},
"playerLevelBanners": [
{
"assetId": "seasonal_banner",
"designId": "banner_design_01",
"text": [
{
"id": "title",
"content": "Summer Sale"
},
{
"id": "subtitle",
"content": "Up to 50% off"
}
],
"endsIn": 1735689600000
}
],
"offersOrder": "priceLowToHigh",
"sectionsOrder": [
"featured",
"daily_deals",
"bundles"
],
"segments": [
"vip_players",
"high_spenders",
"active_users"
],
"focus": {
"publisherBundleId": "mega_bundle"
},
"attributes": {
"player_tier": "diamond",
"monetization_persona": "whale",
"last_purchase_days": 3
},
"storeTheme": {
"bgImageMobile": "mobile_bg_2",
"bgImageDesktop": "desktop_bg_2",
"logo": "store_logo_2",
"profileFrameImage": "profile_frame_2",
"bannerImage": "banner_2",
"playerLevelImage": "player_level_2"
},
"balances": [
{
"publisherProductId": "gold_coins",
"quantity": 15420
},
{
"publisherProductId": "gems",
"quantity": 850
},
{
"publisherProductId": "energy",
"quantity": 95
}
],
"offers": [
{
"publisherOfferId": "starter_pack_01",
"offerDesignOverride": {
"offerDesignSubtitleTextOverride": "Perfect for new players"
},
"offerDescriptionOverride": "Everything you need to get started! A great value bundle with essential resources.",
"priceDiscount": {
"priceBeforeDiscount": 999,
"discount": 25,
"type": "percentage"
},
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "gold_coins",
"quantity": 5000,
"priority": "Main",
"traits": [
{
"assetId": "rarity_common",
"text": "Rarity: Common"
},
{
"assetId": "bonus_starter",
"text": "Starter Bonus: +50%"
}
]
},
{
"publisherProductId": "gems",
"quantity": 100,
"priority": "Sub"
},
{
"publisherProductId": "energy",
"quantity": 50,
"priority": "Sub"
}
]
}
]
},
{
"publisherOfferId": "progress_bar_1",
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "coins",
"quantity": "500"
}
]
},
{
"index": 2,
"products": [
{
"publisherProductId": "coins",
"quantity": "700"
}
]
},
{
"index": 3,
"products": [
{
"publisherProductId": "coins",
"quantity": "800"
}
]
}
]
},
{
"publisherOfferId": "weekend_special",
"offerDesignOverride": {
"offerDesignSubtitleTextOverride": "Limited time weekend deal"
},
"offerDescriptionOverride": "Don't miss out on this exclusive weekend offer with premium rewards!",
"priceDiscount": {
"priceBeforeDiscount": 4999,
"discount": 40,
"type": "percentage"
},
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "gems",
"quantity": 1200,
"priority": "Main",
"traits": [
{
"assetId": "rarity_rare",
"text": "Rarity: Rare"
},
{
"assetId": "bonus_weekend",
"text": "Weekend Bonus: +100%"
},
{
"assetId": "time_limited",
"text": "Time Limited"
}
]
},
{
"publisherProductId": "gold_coins",
"quantity": 25000,
"priority": "Sub"
},
{
"publisherProductId": "energy",
"quantity": 200,
"priority": "Sub"
}
],
"progressBarPoints": [
{
"publisherBarId": "progress_bar_1",
"points": 200
}
]
}
]
},
{
"publisherOfferId": "mega_bundle",
"offerDesignOverride": {
"offerDesignSubtitleTextOverride": "Best value for your money"
},
"offerDescriptionOverride": "Our most popular bundle! Get the best value with this mega pack of resources.",
"priceDiscount": {
"priceBeforeDiscount": 9999,
"discount": 50,
"type": "percentage"
},
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "gold_coins",
"quantity": 100000,
"priority": "Main",
"traits": [
{
"assetId": "rarity_epic",
"text": "Rarity: Epic"
},
{
"assetId": "bonus_mega",
"text": "Mega Bonus: +200%"
},
{
"assetId": "best_value",
"text": "Best Value"
}
]
},
{
"publisherProductId": "gems",
"quantity": 5000,
"priority": "Sub"
},
{
"publisherProductId": "energy",
"quantity": 500,
"priority": "Sub"
}
],
"progressBarPoints": [
{
"publisherBarId": "progress_bar_1",
"points": 200
}
]
}
]
},
{
"publisherOfferId": "daily_deal_gems",
"offerDescriptionOverride": "Today's special: Premium gems at a discount!",
"priceDiscount": {
"priceBeforeDiscount": 1999,
"discount": 30,
"type": "percentage"
},
"offerDesignOverride": {
"offerDesignSubtitleTextOverride": "Refreshes daily"
},
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "gems",
"quantity": 500,
"priority": "Main",
"traits": [
{
"assetId": "daily_special",
"text": "Daily Special"
}
]
},
{
"publisherProductId": "gold_coins",
"quantity": 10000,
"priority": "Sub"
},
{
"publisherProductId": "energy",
"quantity": 75,
"priority": "Sub"
}
]
}
]
},
{
"publisherOfferId": "energy_boost",
"offerDescriptionOverride": "Need more energy? This pack will keep you going!",
"priceDiscount": {
"priceBeforeDiscount": 499,
"discount": 20,
"type": "percentage"
},
"offerDesignOverride": {
"offerDesignSubtitleTextOverride": "Energy pack"
},
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "energy",
"quantity": 150,
"priority": "Main",
"traits": [
{
"assetId": "instant_boost",
"text": "Instant Boost"
}
]
},
{
"publisherProductId": "gold_coins",
"quantity": 2500,
"priority": "Sub"
}
]
}
]
},
{
"publisherOfferId": "vip_exclusive",
"offerDescriptionOverride": "Exclusive VIP bundle with premium rewards!",
"priceDiscount": {
"priceBeforeDiscount": 19999,
"discount": 35,
"type": "percentage"
},
"offerDesignOverride": {
"offerDesignSubtitleTextOverride": "VIP members only"
},
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "gems",
"quantity": 15000,
"priority": "Main",
"traits": [
{
"assetId": "rarity_legendary",
"text": "Rarity: Legendary"
},
{
"assetId": "vip_exclusive",
"text": "VIP Exclusive"
}
]
},
{
"publisherProductId": "gold_coins",
"quantity": 250000,
"priority": "Sub"
},
{
"publisherProductId": "energy",
"quantity": 1000,
"priority": "Sub"
}
]
}
]
}
]
}
```
## OpenAPI
````yaml openapi-personalize-webstore-callback.json POST /{YOUR_PERSONALIZE_WEBSTORE_ENDPOINT}
openapi: 3.0.0
info:
title: Personalize Web Store Callback
version: 1.0.0
servers: []
security: []
paths:
/{YOUR_PERSONALIZE_WEBSTORE_ENDPOINT}:
post:
tags:
- Personalization
summary: Sync player information
description: >-
This is a callback API. Appcharge calls this endpoint on your
server when specific events occur.
Notifies your system to personalize the web store for a player.
Appcharge calls this endpoint when: - A player logs in to your web store.
- A player completes a purchase.
- Every 5 minutes after the player’s last sync.
Your server responds with the most current player data and all available offers for the player. Appcharge then updates the web store for the player accordingly.
operationId: personalize-webstore
parameters:
- in: header
name: x-publisher-token
schema:
type: string
description: Publisher token.
- name: signature
in: header
description: The signed payload.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
playerId:
type: string
description: >-
Player ID (the same value as the `publisherPlayerId`
property returned in the [Authenticate Player
Callback](/../../api-reference/webstore/player-authentication/authenticate-player-callback)).
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
required:
- status
- sessionMetadata
properties:
version:
type: integer
description: The used version. In this case, the value is ‘2’
example: 2
logo:
type: string
description: >-
Logo ID provided when a file is uploaded to the Assets
Library. Use this to display a logo in your web store.
example: MY_LOGO_ASSET_ID
status:
type: string
enum:
- valid
- invalid
description: Web store personalization request status.
example: valid
sessionMetadata:
type: object
description: >-
Container for storing any pertinent information related to
the player's session. If enabled, this is sent back in the
[Grant Award
Callback](/../../api-reference/checkout/awards/grant-award-callback)
as well.
profileFrameId:
type: string
description: >-
Corresponds to the profile frame picture ID uploaded to
the asset library in Appcharge's dashboard. Displayed
above the player's profile picture.
example: profileFrame123
playerLevelName:
type: string
description: >-
Aligns with the player level picture name/ID uploaded to
the asset library in Appcharge's dashboard. Displayed
alongside the footer.
example: playerLevelName
bannerExternalId:
type: string
description: >-
Aligns with the banner asset ID uploaded to the asset
library in Appcharge’s dashboard. Displayed at the top of
the screen.
example: playerLevelAssetId
playerLevel:
type: object
description: Presents discounts related to the player’s level.
required:
- assetId
properties:
assetId:
type: string
description: >-
The ID of the asset relevant to the player’s level,
uploaded to the asset library in Appcharge’s
dashboard.
example: playerLevel1
text:
type: string
description: Text to be displayed on top of the asset.
example: 10%
endsIn:
type: number
description: >-
Epoch timestamp in milliseconds indicating when the
level discount will end.
example: 1728283121000
playerLevelBanners:
type: array
description: >-
List of banners to display to players based on their game
level.
items:
type: object
required:
- assetId
- designId
properties:
assetId:
type: string
description: The banner ID in the Asset Library.
designId:
type: string
description: >-
ID provided by Appcharge specifying the banner type
and design.
text:
type: array
description: List of text objects for displaying the banner text.
items:
type: object
properties:
id:
type: string
description: >-
The text ID that specifies the text’s
placement in the banner.
content:
type: string
description: The text displayed in the banner.
endsIn:
type: number
description: >-
Unix timestamp indicating when the banner expires.
For example, `1720051200` represents July 4, 2024.
offersOrder:
type: string
enum:
- publisherOrder
- priceHighToLow
- priceLowToHigh
default: priceLowToHigh
description: Defines the order of offers.
sectionsOrder:
type: array
items:
type: string
description: >-
An array of publisher’s section ids that defines the order
of sections for the store.
segments:
type: array
items:
type: string
description: The list of segments associated with the player.
focus:
type: object
properties:
publisherBundleId:
type: string
description: The id of the bundle to focus on in the web store.
example: bundle123
description: Customize which offer you want to focus on.
attributes:
type: object
description: >-
A set of custom key-value pairs that you can define to tag
players for segmentation and A/B testing. These attributes
can then be used to filter players in the Publisher
Dashboard.
Example:
{
"BF_test": "test",
"monetization_persona": "non_payer"
}
storeTheme:
type: object
description: Information about the web store theme.
properties:
bgImageMobile:
type: string
description: >-
Name of the background image for mobile devices in the
Assets Library of the Publisher Dashboard.
example: mobile_bg_2
bgImageDesktop:
type: string
description: >-
Name of the background image for desktop devices in
the Assets Library of the Publisher Dashboard.
example: desktop_bg_2
logo:
type: string
description: >-
Name of the logo image in the Assets Library of the
Publisher Dashboard.
example: store_logo_2
profileFrameImage:
type: string
description: >-
Name of the profile frame image in the Assets Library
of the Publisher Dashboard.
example: profile_frame_2
bannerImage:
type: string
description: >-
Name of the banner image in the Assets Library of the
Publisher Dashboard.
example: banner_2
playerLevelImage:
type: string
description: >-
Name of the player level image in the Assets Library
of the Publisher Dashboard.
example: player_level_2
balances:
type: array
items:
type: object
required:
- publisherProductId
- quantity
properties:
publisherProductId:
type: string
description: The publisher's product id.
example: product123
quantity:
type: integer
description: >-
The quantity of the product. Should be greater than
or equal to 0 and less than or equal to 24 digits
long.
example: 5
description: A list of product balances of the player.
offers:
type: array
items:
type: object
required:
- publisherOfferId
- productsSequence
properties:
publisherOfferId:
type: string
description: The publisher's offer id.
example: offer123
endsIn:
type: number
description: >-
[Epoch](https://www.epoch101.com/) timestamp in
milliseconds indicating how much time remains on the
countdown timer for the offer displayed in the web
store, regardless of its schedule.
example: '1743077489'
offerDescriptionOverride:
type: string
description: >-
The description that will be displayed instead of
the current offer description in the store UI.
offerDesignOverride:
type: object
properties:
offerDesignSubtitleTextOverride:
type: string
description: >-
The text that will be displayed instead of the
current subtitle in the offer UI.
offerDesignId:
type: string
description: >-
This is the offerExternalUiId, which is used to
override the offer UI for the store.
offerBackgroundImageOverride:
type: string
description: >-
Image URL used to override the current
background image. Appcharge saves and uses this
URL as-is and doesn't download, copy, upload, or
host the image. The image must remain available
at the provided URL.
We recommend uploading image files instead of
using external URLs when possible. Appcharge
hosts uploaded files on its CDN.
productSale:
type: object
description: >-
Details on the product sale. This field is not
applicable for Rolling Offers. To define a product
sale for Rolling Offers, refer to the 'productSale'
field within 'productsSequence'.
properties:
amountBeforeSale:
type: integer
description: Offer amount in USD before sale is applied.
sale:
type: integer
description: Sale amount in percentage.
type:
type: string
description: >-
Will be 'percentage' by default. Optional values
are 'percentage', 'multiplier', 'fixed_amount'.
priceDiscount:
type: object
description: >-
Used to define the discount for the offer price.
This field is not applicable for Rolling Offers. To
define an offer discount for Rolling Offers, refer
to the 'priceDiscount' field within
'productsSequence'.
required:
- discount
- type
properties:
priceBeforeDiscount:
type: integer
description: >-
The original price of the offer before discount.
Copied to FE without any logic on Appcharge’s
side. The minimum should be 0.
example: 100
discount:
type: integer
description: The discount percentage, min of 0
example: 20
type:
type: string
enum:
- percentage
description: >-
The type of discount, currently only
"percentage" is supported.
example: percentage
badges:
type: array
description: >-
A list of badges in the offer. If you do not want to
have badges, then it should be sent as an empty
array. This field is not applicable for Rolling
Offers. To define badges for Rolling Offers, refer
to the ‘badges’ field within ‘productsSequence’.
items:
type: object
required:
- publisherBadgeId
- position
properties:
publisherBadgeId:
type: string
description: The publisher's badge id.
example: badge123
position:
type: string
enum:
- right
- left
- center
description: >-
This field is outdated. The position of the
badge should be set from Dashboard only.
example: center
ribbonTextOverride:
type: string
description: >-
A text that will override the ribbon's text
provided in publisherBadgeId. Only relevant
when the badge sent in publisherBadgeId is
from type 'Ribbon'.
dynamicOfferUi:
type: object
required:
- salePercentage
description: >-
Details of the dynamic user interface for the offer.
**Deprecated**
properties:
badges:
type: array
description: A list of badges in the offer.
items:
type: object
required:
- publisherBadgeId
- position
properties:
publisherBadgeId:
type: string
description: The publisher's badge id.
example: badge123
position:
type: string
enum:
- right
- left
- center
description: >-
This field is outdated. The position of
the badge should be set from Dashboard
only.
example: center
ribbonTextOverride:
type: string
description: >-
A text that will override the ribbon's
text provided in publisherBadgeId. Only
relevant when the badge sent in
publisherBadgeId is from type 'Ribbon'.
salePercentage:
type: integer
description: Sale amount in percentage.
amountBeforeSale:
type: integer
description: Offer amount in USD before sale is applied.
salePercentageDisplayType:
type: string
description: >-
Will be 'percentage' by default. Optional values
are 'percentage', 'multiplier', 'fixed_amount'.
offerDesignId:
type: string
description: >-
This is the offerExternalUiId, which is used to
override the offer UI for the store.
productsSequence:
type: array
description: >-
The sequence of the products included in the offer.
Rolling offers should be the same amount of
sequences as the amount of sub offers configured in
the Publisher Dashboard.
items:
type: object
required:
- index
- products
properties:
index:
type: integer
minimum: 1
description: >-
The position of this offer or sub-offer within
the parent offer. Each index should be a
positive integer starting from 1.
**Note:** For the Progress Bar offer, this property defines the mission order.
productSale:
type: object
description: >-
Details on the product sale. This field is
only relevant for Rolling Offers. To define a
product sale for other offer types, refer to
the corresponding 'productSale' field at the
root level within 'offers'.
properties:
amountBeforeSale:
type: integer
description: >-
Offer amount in USD before sale is
applied.
sale:
type: integer
description: Sale amount in percentage.
type:
type: string
description: >-
Will be 'percentage' by default. Optional
values are 'percentage', 'multiplier',
'fixed_amount'.
priceDiscount:
type: object
description: >-
Used to define the discount for the offer
price. This is only relevant for Rolling
Offers. To define a price discount for other
offer types, refer to the corresponding
'priceDiscount' field at the root level within
the 'offers' object.
required:
- discount
- type
properties:
priceBeforeDiscount:
type: integer
description: >-
The original price of the offer before
discount. Copied to FE without any logic
on Appcharge’s side. The minimum should be
0.
example: 100
discount:
type: integer
description: The discount percentage, min of 0
example: 20
type:
type: string
enum:
- percentage
description: >-
The type of discount, currently only
"percentage" is supported.
example: percentage
badges:
type: array
description: >-
A list of badges in the offer. If you do not
want to have badges, then it should be sent as
an empty array. This field is only relevant
for Rolling Offers. To define badges for other
offer types, refer to the 'badges' field at
the root level within the 'offers' object.
items:
type: object
required:
- publisherBadgeId
- position
properties:
publisherBadgeId:
type: string
description: The publisher's badge id.
example: badge123
position:
type: string
enum:
- right
- left
- center
description: >-
This field is outdated. The position of
the badge should be set from Dashboard
only.
example: center
ribbonTextOverride:
type: string
description: >-
A text that will override the ribbon's
text provided in publisherBadgeId. Only
relevant when the badge sent in
publisherBadgeId is from type 'Ribbon'.
progressBarPoints:
type: array
description: >-
The contribution of this offer toward the
progress bar. A points ribbon is displayed
with the number of points for offers that
define this field.
**Note:** Currently you can only have 1 progress bar object.
items:
type: object
properties:
publisherBarId:
type: string
description: The publisher's external bar ID.
example: progress-bar-1
points:
type: integer
description: >-
Number of points awarded toward the
progress bar when this offer is
purchased or claimed.
example: 1000
products:
type: array
description: |-
The products in a given offer.
**Note:** For the Progress Bar offer, this property defines the reward received when completing the given mission.
items:
type: object
required:
- publisherProductId
- quantity
properties:
publisherProductId:
type: string
description: The product Id.
example: product123
quantity:
type: integer
description: >-
The quantity of the product. Should be
minimum 0 and equal to or less than 24
digits long.
example: 2
priority:
type: string
description: >-
Specifies the display priority of a
product within the offer.
enum:
- Main
- Sub
x-enum-descriptions:
- Main: >-
Primary display, with more prominent
placement in supported templates.
- Sub: >-
Secondary display, with less prominent
placement in supported templates.
traits:
type: array
description: >-
A list of visual or descriptive features
associated with the product. Useful for
distinguishing variants, bonuses, or
unique characteristics of the product.
items:
type: object
required:
- assetId
- text
properties:
assetId:
type: string
description: >-
The asset ID of the trait, located in
the Asset Library.
example: burn_damage_icon
text:
type: string
description: >-
The label or descriptor associated with
the trait.
example: Burn Damage
rarityProductInfo:
type: object
description: Details about the rarity of the product.
properties:
stars:
type: integer
description: >-
The number of icons (stars) representing
the rarity of the product. Displayed
next to the product and inside the
tooltip.
example: 5
tooltip:
oneOf:
- type: array
description: >-
Assets representing products and the
player's probability of receiving them.
items:
type: object
required:
- sectionName
- products
properties:
sectionName:
type: string
description: >-
The section representing each product
type available in the tooltip.
example: Special Offers
products:
type: array
items:
type: object
required:
- publisherProductId
- text
properties:
publisherProductId:
type: string
description: The publisher's product ID.
example: Coin
text:
type: string
description: The text associated with the product.
example: 20%
- type: object
description: >-
A general description tooltip for the
product.
required:
- tooltipText
- rarityText
properties:
tooltipText:
type: string
description: The text of the tooltip.
example: Rare Item
rarityText:
type: string
description: >-
The text that appears next to the
product and inside the tooltip, before
the rarity icons (stars).
example: Legendary
````