> ## 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 Special Offer
> Creates a special offer.
```bash Create Special Offer theme={"system"}
curl -X POST \
'https://api.appcharge.com/v2/offer' \
-H 'Content-Type: application/json' \
-H 'x-publisher-token: ' \
-d '{
"publisherOfferId": "special-offer-1",
"name": "My Special Offer",
"type": "SpecialOffer",
"active": true,
"segments": [
"New User"
],
"publisherTabId": "tab-1",
"productsSequence": [
{
"index": 1,
"playerAvailability": 12,
"hidePlayerAvailability": true,
"products": [
{
"priority": "Sub",
"publisherProductId": "6cb43621ccf1",
"quantity": "100",
}
]
"priceInUsdCents": 1000
}
],
"productSale": {
"type": "percentage",
"sale": 100
},
"priceDiscount": {
"type": "percentage",
"discount": 20
},
"displayName": "My Special Offer",
"description": "This is my special offer description.",
"offerUiId": "2bc77ff889b",
"offerExternalUiId": "2bc22377ff889cc",
"badges": [
{
"publisherBadgeId": "12ac77ff889b"
}
]
}'
```
```json Create Special Offer theme={"system"}
{
"publisherId": "35nb7861ec9924a6b69a0fe59",
"offerId": "226cff96123a8717",
"publisherOfferId": "special-offer-1",
"displayName": "My Special Offer",
"description": "This is my special offer description.",
"name": "My Special Offer",
"type": "SpecialOffer",
"active": true,
"segments": [
"New User"
],
"publisherTabId": "tab-1",
"offerUi": {
"offerUiId": "2bc77ff889b",
"active": true,
"offerUiType": "SpecialOffer",
"name": "specialOffer1",
"description": "description",
"backgroundImage": "https://media.appcharge.com/media/65cb7182__4dc30c81-e4aa-40e8-9033-84cb05721bd0",
"borderColor": {
"colorOne": "#ffffff",
"colorTwo": "",
"direction": ""
},
"borderWidth": 2,
"externalId": "specialOffer1"
},
"productsSequence": [
{
"index": 1,
"playerAvailability": 12,
"hidePlayerAvailability": true,
"products": [
{
"product": {
"publisherProductId": "6cb43621ccf1",
"name": "Coins",
"textFontColorHex": "#FFFFFF",
"type": "Quantity",
"prefix": "",
"suffix": "",
"priority": "Sub",
"images": [
{
"type": "product",
"url": "https://media.appcharge.com/media/45cb7861ec8924a6b69a0f59/download.jpeg"
},
{
"type": "productPrefix",
"url": ""
}
],
"createdAt": "2024-02-14T10:08:17.061Z",
"updatedAt": "2024-09-27T13:41:55.775Z",
"displayName": "coins",
"productId": "75cc91114cf653a9cc2dce2c"
},
"publisherProductId": "6cb43621ccf1",
"quantity": 1000,
"priority": "Main"
}
],
"priceInUsdCents": 980,
"badges": [],
"id": "68b4092c7a895e559a3ac8d9"
}
],
"productSale": {
"type": "percentage",
"sale": 100
},
"priceDiscount": {
"type": "percentage",
"discount": 20
},
"offerExternalUiId": "2bc22377ff889cc",
"badges": [
{
"publisherBadgeId": "12ac77ff889b"
}
],
"createdAt": "2025-04-06T10:00:44.528Z",
"updatedAt": "2025-04-06T10:00:44.528Z"
}
```
## OpenAPI
````yaml openapi-special-offers.json POST /v2/offer
openapi: 3.0.1
info:
title: Special Offer API
description: API for managing Special Offers.
version: '1.0'
servers:
- url: https://api-sandbox.appcharge.com
security: []
paths:
/v2/offer:
post:
tags:
- Special Offers
summary: Create a new special offer
description: Creates a special offer.
operationId: createSpecialOffer
parameters:
- name: x-publisher-token
in: header
required: true
description: The publisher token used for authentication.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpecialOfferDto'
responses:
'201':
description: Special offer created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SpecialOfferDtoResponse'
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
requestUrl:
type: string
body:
type: string
'401':
description: Unauthorized.
components:
schemas:
CreateSpecialOfferDto:
type: object
required:
- publisherOfferId
- name
- type
- active
- segments
- productsSequence
properties:
publisherOfferId:
type: string
description: >-
The special offer ID provided by the publisher. This is the offer's
**External ID** value in the Publisher Dashboard.
name:
type: string
description: The name of the special offer (at least 3 characters).
displayName:
type: string
description: If not specified, the special offer name will be used.
description:
type: string
description: The description of the offer (conditionally returned).
type:
type: string
description: The type of offer - In this case 'SpecialOffer'.
enum:
- SpecialOffer
default: SpecialOffer
active:
type: boolean
description: Whether the special offer is active.
offerUiId:
type: string
description: >-
Internal ID for the Offer UI (required if offerExternalUiId not
provided).
offerExternalUiId:
type: string
description: >-
The offer UI ID as configured by the publisher (if provided,
offerUiId is not required).
segments:
type: array
description: >-
List of player segments that this special offer applies to (e.g.,
["NewUser", "BigSpender"]). This is empty by default.
items:
type: string
publisherTabId:
type: string
description: Tab ID in the web store.
badges:
type: array
description: List of badges associated with the special offer.
items:
type: object
properties:
publisherBadgeId:
type: string
description: The ID as configured in the dashboard.
productSale:
type: object
description: >-
Sale details for products in the special offer. The sale will only
be applied on the first offer.
properties:
sale:
type: integer
description: The sale percentage applied to the product quanitity.
type:
type: string
description: The type of sale.
default: percentage
enum:
- percentage
- multiplier
- fixed_amount
priceDiscount:
type: object
description: Discount applied to the special offer price.
properties:
discount:
type: integer
description: The discount percentage applied.
type:
type: string
description: The type of discount applied.
default: percentage
enum:
- percentage
productsSequence:
type: array
description: >-
The sequence of products included in the special offer. Only one
Products Sequence is allowed.
items:
type: object
properties:
index:
type: integer
description: The order of the product in the special offer.
playerAvailability:
type: number
description: >-
The amount of times the player can purchase/ collect the
offer.
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 collects or
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
products:
type: array
description: List of products in the special offer.
items:
type: object
required:
- publisherProductId
- quantity
- priority
properties:
publisherProductId:
type: string
description: The unique ID of the product.
quantity:
type: integer
description: The quantity of the product in the special offer.
priority:
type: string
description: >-
Specifies the display priority of a product within the
special offer. Either `Main` or `Sub`.
priceInUsdCents:
type: integer
description: >-
The price of the product in cents. The value must be either 0
(free), or by minimum 80 cents.
progressBarPoints:
type: array
description: >-
List of Progress Bar offers to which this offer contributes
points.
items:
type: object
properties:
publisherBarId:
type: string
description: >-
The Progress Bar offer ID provided by the publisher.
This is the Progress Bar offer's **External ID** value
in the Publisher Dashboard.
points:
type: number
description: >-
The number of points this offer contributes to the
specified Progress Bar. This value is displayed in the
Points Ribbon shown on contributing offers.
required:
- index
- products
- priceInUsdCents
schedule:
type: object
required:
- timeFrames
- permanent
description: The schedule for when the special offer is available.
properties:
permanent:
type: boolean
description: Whether the special offer will be permanent.
timeFrames:
type: array
description: >-
Time frame for the scheduled offer. Leave blank if `permanent`
is set to `true`. If `permanent` is `false`, at least 1 time
frame is required. When specifying multiple time frames, the
`startTime` and `endTime` of each must not overlap.
items:
type: object
properties:
startTime:
type: string
description: Scheduled offer start time.
format: date-time
endTime:
type: string
description: Scheduled offer end time. Can't be a past date.
format: date-time
notes:
type: string
description: Notes about the scheduled offer.
required:
- startTime
- endTime
intervals:
type: string
description: >-
Defines the recurring intervals for the special offer. The
offer's availability resets at the start of each interval.
**Only relevant if the offer has Player Availability.**
publisherSectionId:
type: string
description: The publisher section ID.
SpecialOfferDtoResponse:
type: object
properties:
publisherId:
type: string
description: Publisher ID.
offerId:
type: string
description: The unique identifier of the special offer.
publisherOfferId:
type: string
description: >-
The special offer ID provided by the publisher. This is the offer's
**External ID** value in the Publisher Dashboard.
name:
type: string
description: The name of the special offer.
displayName:
type: string
description: The display name of the special offer.
description:
type: string
description: The description of the offer (conditionally returned)
type:
type: string
description: The type of special offer.
active:
type: boolean
description: Whether the special offer is active.
segments:
type: array
description: >-
List of player segments that this special offer applies to (e.g.,
["NewUser", "BigSpender"]). This is empty by default.
items:
type: string
publisherTabId:
type: string
description: Tab ID in the web store.
offerUi:
type: object
description: UI configuration for the special offer.
properties:
offerUiId:
type: string
description: >-
The ID of the special offer design, as displayed in the
Publisher Dashboard.
externalId:
type: string
description: >-
The SKU of the special offer design, as defined in the Publisher
Dashboard.
active:
type: boolean
description: Whether the special offer design is active.
offerUiType:
type: string
description: The type of offer design. In this case, ‘special offer’.
name:
type: string
description: >-
The name of the special offer design, as defined in the
Publisher Dashboard.
description:
type: string
description: >-
The description of the special offer design, as defined in the
Publisher Dashboard.
backgroundImage:
type: string
description: >-
The background image of the special offer design, as defined in
the Publisher Dashboard.
specialOffer:
type: object
description: Details on the special offer template and design.
properties:
templateType:
type: string
description: The template type, as configured in the Publisher Dashboard.
title:
type: string
description: >-
The title of the special offer, as configured in the
Publisher Dashboard.
fontSize:
type: number
description: >-
The font size of the special offer title, as configured in
the Publisher Dashboard.
fontWeight:
type: string
description: >-
The font weight of the special offer title, as configured in
the Publisher Dashboard.
fontColor:
type: object
description: >-
Details on the font color of the special offer title as
configured in the Publisher Dashboard. If the font color is
set to linear, both 'colorOne' and 'colorTwo' will be
returned. 'colorThree' may also be returned, if configured.
properties:
colorOne:
type: string
description: The font color of the special offer title.
colorTwo:
type: string
description: >-
The second font color of the special offer title.
Relevant only if the font color is set to linear.
colorThree:
type: string
description: >-
The third font color of the special offer title.
Relevant only if the font color is set to linear.
backgroundColor:
type: object
description: >-
Details on the background color of the special offer title
as configured in the Publisher Dashboard. If the background
color is set to linear, the direction will be returned along
with ‘colorOne’ and ‘colorTwo’.
properties:
colorOne:
type: string
description: The background color of the special offer title.
colorTwo:
type: string
description: >-
The second background color of the special offer title.
Relevant only if the background color is set to linear.
direction:
type: string
description: >-
The direction of the linear gradient. Relevant only if
the background color is set to linear.
productsSequence:
type: array
description: A sequence of products in the special offer.
items:
type: object
properties:
index:
type: integer
description: The order of the product in the special offer.
hidePlayerAvailability:
type: boolean
description: >-
Whether to hide the availability text based on the
`playerAvailability` property value in the web store.
example: true
products:
type: array
description: List of products in the special offer.
items:
type: object
properties:
publisherProductId:
type: string
description: The unique ID of the product.
quantity:
type: integer
description: The quantity of the product in the special offer.
priority:
type: string
description: >-
Specifies the display priority of a product within the
special offer. Either `Main` or `Sub`.
priceInUsdCents:
type: integer
description: >-
The price of the product in cents. The value must be either 0
(free), or by minimum 80 cents.
progressBarPoints:
type: array
description: >-
List of Progress Bar offers to which this offer contributes
points.
items:
type: object
properties:
publisherBarId:
type: string
description: >-
The Progress Bar offer ID provided by the publisher.
This is the Progress Bar offer's **External ID** value
in the Publisher Dashboard.
points:
type: number
description: >-
The number of points this offer contributes to the
specified Progress Bar. This value is displayed in the
Points Ribbon shown on contributing offers.
badges:
type: array
description: List of badges associated with the special offer.
items:
type: object
properties:
publisherBadgeId:
type: string
description: The ID as configured in the dashboard.
productSale:
type: object
description: >-
Sale details for products in the special offer. The sale will only
be applied on the first offer.
properties:
sale:
type: integer
description: The sale percentage applied to the product quanitity.
type:
type: string
description: The type of sale.
default: percentage
enum:
- percentage
- multiplier
- fixed_amount
priceDiscount:
type: object
description: Discount applied to the special offer price.
properties:
discount:
type: integer
description: The discount percentage applied.
type:
type: string
description: The type of discount applied.
default: percentage
enum:
- percentage
schedule:
type: object
required:
- timeFrames
- permanent
description: The schedule for when the special offer is available.
properties:
permanent:
type: boolean
description: Whether the special offer will be permanent.
timeFrames:
type: array
description: >-
Time frame for the scheduled offer. Leave blank if `permanent`
is set to `true`. If `permanent` is `false`, at least 1 time
frame is required. When specifying multiple time frames, the
`startTime` and `endTime` of each must not overlap.
items:
type: object
properties:
startTime:
type: string
description: Scheduled offer start time.
format: date-time
endTime:
type: string
description: Scheduled offer end time. Can't be a past date.
format: date-time
notes:
type: string
description: Notes about the scheduled offer.
required:
- startTime
- endTime
intervals:
type: string
description: >-
Defines the recurring intervals for the special offer. The
offer's availability resets at the start of each interval.
**Only relevant if the offer has Player Availability.**
createdAt:
type: string
description: Date the special offer was created.
format: date-time
updatedAt:
type: string
description: Date the special offer was updated.
format: date-time
````