> ## 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.
# Create Store Refresh Popup
> Creates a Store Refresh popup offer. Triggered when a player refreshes the web store.
```bash Create Store Refresh Popup theme={"system"}
curl -X POST \
'https://api.appcharge.com/v2/offer' \
-H 'Content-Type: application/json' \
-H 'x-publisher-token: ' \
--data '{
"type": "PopUp",
"subType": "StoreRefresh",
"active": true,
"publisherOfferId": "store-refresh-offer-1",
"name": "Store Refresh Offer 1",
"displayName": "Limited time deal",
"description": "Shown periodically when the store refreshes.",
"segments": [],
"productsSequence": [
{
"index": 1,
"products": [
{
"publisherProductId": "green_diamond",
"quantity": 1,
"priority": "Main"
},
{
"publisherProductId": "pink_diamond",
"quantity": 2,
"priority": "Main"
}
],
"priceInUsdCents": 0,
"playerAvailability": 10,
"hidePlayerAvailability": true
}
],
"priority": 5,
"offerExternalUiId": "Real_Store_Refresh",
"displayRule": {
"frequency": 3,
"cooldownInMinutes": 1
},
"schedule": {
"permanent": false,
"timeFrames": [
{
"startTime": "2026-05-02T00:00:00.000Z",
"endTime": "2026-05-04T23:59:59.000Z",
"notes": "Initial weekend rollout"
},
{
"startTime": "2026-05-10T00:00:00.000Z",
"endTime": "2026-05-12T23:59:59.000Z"
}
]
},
"productSale": {
"sale": 30,
"type": "percentage"
},
"priceDiscount": {
"discount": 25,
"type": "percentage"
},
"badges": [
{
"publisherBadgeId": "best_value"
}
]
}'
```
```json Create Store Refresh Popup theme={"system"}
{
"publisherId": "35nb7861ec9924a6b69a0fe59",
"publisherOfferId": "store-refresh-offer",
"name": "Store Refresh Offer",
"displayName": "Limited time deal",
"description": "Shown periodically when the store refreshes",
"type": "PopUp",
"subType": "StoreRefresh",
"active": true,
"segments": [],
"offerUi": {
"offerUiId": "68b41c5aa1c5b1a284737e9b",
"active": true,
"offerUiType": "PopUp",
"name": "Real_Store_Refresh",
"description": "description",
"externalId": "Real_Store_Refresh"
},
"productsSequence": [
{
"index": 1,
"products": [
{
"product": {
"publisherProductId": "green_diamond",
"name": "Green Diamond",
"type": "Quantity",
"priority": "Main",
"displayName": "Green Diamond"
}
},
{
"product": {
"publisherProductId": "pink_diamond",
"name": "Pink Diamond",
"type": "Quantity",
"priority": "Main",
"displayName": "Pink Diamond"
}
}
],
"priceInUsdCents": 0,
"playerAvailability": 10,
"hidePlayerAvailability": true
}
],
"priority": 5,
"displayRule": {
"frequency": 3,
"cooldownInMinutes": 1
},
"schedule": {
"permanent": false,
"timeFrames": [
{
"startTime": "2026-05-02T00:00:00.000Z",
"endTime": "2026-05-04T23:59:59.000Z",
"notes": "Initial weekend rollout"
},
{
"startTime": "2026-05-10T00:00:00.000Z",
"endTime": "2026-05-12T23:59:59.000Z"
}
]
},
"productSale": {
"sale": 30,
"type": "percentage"
},
"priceDiscount": {
"discount": 25,
"type": "percentage"
},
"badges": [
{
"publisherBadgeId": "best_value"
}
],
"createdAt": "2026-05-01T14:16:09.499Z",
"updatedAt": "2026-05-01T14:16:09.499Z",
"offerId": "68b5aaa9b73fceb9ffc26f9b"
}
```
## OpenAPI
````yaml openapi-store-refresh.json POST /v2/offer
openapi: 3.0.1
info:
title: Store Refresh Popup API
description: API for managing Store Refresh Popups.
version: '1.0'
servers:
- url: https://api-sandbox.appcharge.com
security: []
paths:
/v2/offer:
post:
tags:
- Store Refresh Popups
summary: Create a new Store Refresh Popup
description: >-
Creates a Store Refresh popup offer. Triggered when a player refreshes
the web store.
operationId: createStoreRefreshPopup
parameters:
- name: x-publisher-token
in: header
required: true
description: Publisher token used for authentication.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateStoreRefreshPopupDto'
responses:
'201':
description: Store refresh popup created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/StoreRefreshPopupDtoResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
components:
schemas:
CreateStoreRefreshPopupDto:
type: object
required:
- publisherOfferId
- name
- type
- subType
- active
- segments
- productsSequence
- priority
- displayRule
properties:
publisherOfferId:
type: string
description: >-
Store Refresh Popup ID. This is the offer's **External ID** value in
the Publisher Dashboard.
example: store-refresh-offer-1
name:
type: string
description: Store Refresh Popup name. Must be at least 3 characters.
example: Store Refresh Offer 1
displayName:
type: string
description: >-
Store Refresh Popup display name. If not provided, the name will be
used.
example: Limited time deal
description:
type: string
description: Store Refresh Popup description.
example: Shown periodically when the store refreshes.
type:
type: string
description: Offer type - In this case 'PopUp'.
enum:
- PopUp
default: PopUp
example: PopUp
subType:
type: string
description: Offer sub type - In this case 'StoreRefresh'.
enum:
- StoreRefresh
default: StoreRefresh
example: StoreRefresh
active:
type: boolean
description: Whether the Store Refresh Popup is active.
example: true
priority:
type: integer
description: >-
Priority level of the Store Refresh Popup. The priority starts from
1, where 1 is the highest priority.
example: 5
offerUiId:
type: string
description: >-
Offer Design ID generated by Appcharge. This is the design's **ID**
value in the Publisher Dashboard. Required if `offerExternalUiId` is
not provided.
example: 68b41c5aa1c5b1a284737e9b
offerExternalUiId:
type: string
description: >-
Offer Design ID. This is the design's **External ID** value in the
Publisher Dashboard. Required if `offerUiId` is not provided.
example: Real_Store_Refresh
segments:
type: array
description: List of player segments that this Store Refresh Popup applies to.
example:
- vip_players
items:
type: string
productsSequence:
$ref: '#/components/schemas/StoreRefreshProductsSequence'
displayRule:
$ref: '#/components/schemas/StoreRefreshDisplayRule'
schedule:
$ref: '#/components/schemas/Schedule'
productSale:
$ref: '#/components/schemas/ProductSale'
priceDiscount:
$ref: '#/components/schemas/PriceDiscount'
badges:
$ref: '#/components/schemas/Badges'
publisherSectionId:
type: string
description: The publisher section ID.
publisherTabId:
type: string
description: Tab ID in the web store.
example:
type: PopUp
subType: StoreRefresh
active: true
publisherOfferId: store-refresh-offer
name: Store Refresh Offer
displayName: Limited time deal
description: Shown periodically when the store refreshes
segments: []
productsSequence:
- index: 1
products:
- publisherProductId: green_diamond
quantity: 1
priority: Main
- publisherProductId: pink_diamond
quantity: 2
priority: Main
priceInUsdCents: 0
playerAvailability: 10
hidePlayerAvailability: true
priority: 5
offerExternalUiId: Real_Store_Refresh
displayRule:
frequency: 3
cooldownInMinutes: 1
schedule:
permanent: false
timeFrames:
- startTime: '2026-05-02T00:00:00.000Z'
endTime: '2026-05-04T23:59:59.000Z'
notes: Initial weekend rollout
- startTime: '2026-05-10T00:00:00.000Z'
endTime: '2026-05-12T23:59:59.000Z'
productSale:
sale: 30
type: percentage
priceDiscount:
discount: 25
type: percentage
badges:
- publisherBadgeId: best_value
StoreRefreshPopupDtoResponse:
type: object
properties:
publisherId:
type: string
description: Publisher ID.
offerId:
type: string
description: Store Refresh Popup ID.
publisherOfferId:
type: string
description: >-
Store Refresh Popup ID provided by the publisher. This is the
offer's **External ID** value in the Publisher Dashboard.
name:
type: string
description: Store Refresh Popup name.
displayName:
type: string
description: >-
Store Refresh Popup display name. If not provided, the name will be
used.
description:
type: string
description: Store Refresh Popup description.
type:
type: string
description: Offer type.
subType:
type: string
description: Offer sub type - In this case 'StoreRefresh'.
active:
type: boolean
description: Whether the Store Refresh Popup is active.
priority:
type: integer
description: Priority level of the Store Refresh Popup.
offerUi:
type: object
description: UI configuration for the Store Refresh Popup.
properties:
offerUiId:
type: string
description: >-
Offer Design ID generated by Appcharge. This is the design's
**ID** value in the Publisher Dashboard.
example: 68b41c5aa1c5b1a284737e9b
offerExternalUiId:
type: string
description: >-
Offer Design ID. This is the design's **External ID** value in
the Publisher Dashboard.
example: Real_Store_Refresh
active:
type: boolean
description: Whether the Store Refresh Popup design is active.
offerUiType:
type: string
description: Offer design type.
name:
type: string
description: >-
Store Refresh Popup design name, as configured in the Publisher
Dashboard.
description:
type: string
description: >-
Store Refresh Popup design description, as configured in the
Publisher Dashboard.
segments:
type: array
description: List of player segments that this Store Refresh Popup applies to.
items:
type: string
productsSequence:
$ref: '#/components/schemas/StoreRefreshProductsSequence'
displayRule:
$ref: '#/components/schemas/StoreRefreshDisplayRule'
schedule:
$ref: '#/components/schemas/Schedule'
productSale:
$ref: '#/components/schemas/ProductSale'
priceDiscount:
$ref: '#/components/schemas/PriceDiscount'
badges:
$ref: '#/components/schemas/Badges'
createdAt:
type: string
description: Date the Store Refresh Popup was created.
format: date-time
updatedAt:
type: string
description: Date the Store Refresh Popup was updated.
format: date-time
ErrorResponse:
type: object
properties:
message:
type: string
requestUrl:
type: string
body:
type: string
StoreRefreshProductsSequence:
type: array
description: Sequence of products included in the Store Refresh Popup.
items:
type: object
properties:
index:
type: integer
description: Order of the product sequence in the Store Refresh Popup.
example: 1
products:
type: array
description: List of products in the Store Refresh Popup.
items:
type: object
required:
- publisherProductId
- quantity
- priority
properties:
publisherProductId:
type: string
description: Product ID.
example: green_diamond
quantity:
type: integer
description: Product quantity in the Store Refresh Popup.
example: 1
priority:
type: string
description: >-
Specifies the display priority of a product within the Store
Refresh Popup.
enum:
- Main
- Sub
example: Main
priceInUsdCents:
type: integer
description: >-
Product sequence price in cents. The value must be either 0
(free), or have a minimum 80 cents.
example: 99
playerAvailability:
type: number
description: >-
Amount of times the player can purchase the Store Refresh Popup.
Must be a minimum of 1.
example: 10
hidePlayerAvailability:
type: boolean
description: >-
Whether to hide the availability text based on the
`playerAvailability` property value in the web store. If `false`,
and if `playerAvailability` is set to `5`, the web store displays
`Available 5/5`. When a player purchases the offer, the displayed
availability decreases, for example to `Available 4/5`. Set to
`true` to hide the availability text in the UI.
default: false
example: true
required:
- index
- products
- priceInUsdCents
StoreRefreshDisplayRule:
type: object
required:
- frequency
- cooldownInMinutes
description: Rules that control how often the Store Refresh Popup is displayed.
properties:
frequency:
type: integer
description: Number of store refreshes required before the popup is displayed.
example: 3
cooldownInMinutes:
type: integer
description: >-
Number of minutes that must pass before the popup can be shown
again.
example: 1
Schedule:
type: object
required:
- timeFrames
- permanent
description: Schedule for when the Store Refresh Popup is available.
properties:
permanent:
type: boolean
description: Whether the Store Refresh Popup is permanent.
example: false
timeFrames:
type: array
description: >-
Time frame for the scheduled popup. Leave blank if permanent is set
to true. If permanent is false, at least 1 time frame is required.
When specifying multiple timeFrames, the startTime and endTime of
each must not overlap.
items:
type: object
required:
- startTime
- endTime
properties:
startTime:
type: string
description: Scheduled popup start time.
format: date-time
example: '2026-05-02T00:00:00.000Z'
endTime:
type: string
description: Scheduled popup end time. Can't be a past date.
format: date-time
example: '2026-05-04T23:59:59.000Z'
notes:
type: string
description: Notes about the scheduled popup.
example: Initial weekend rollout
ProductSale:
type: object
description: >-
Sale details for the product quantity. The sale will only be applied on
the first product.
properties:
sale:
type: integer
description: Sale amount.
example: 30
type:
type: string
description: Sale type.
default: percentage
enum:
- percentage
example: percentage
PriceDiscount:
type: object
description: >-
Price discount applied to the Store Refresh Popup. Relevant only for
paid offers.
properties:
discount:
type: integer
description: Discount amount.
example: 25
type:
type: string
description: Discount type.
default: percentage
enum:
- percentage
example: percentage
Badges:
type: array
description: List of badges associated with the Store Refresh Popup.
example:
- publisherBadgeId: best_value
items:
type: object
properties:
publisherBadgeId:
type: string
description: Badge ID.
example: best_value
required:
- publisherBadgeId
````