> ## 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.
# Get Special Offer
> Retrieves one or more special offers.
```bash Get Special Offer theme={"system"}
curl -X GET \
'https://api.appcharge.com/v2/offer?publisherOfferIds=special-offer-1' \
-H 'Content-Type: application/json' \
-H 'x-publisher-token: '
```
```json Get Special Offer theme={"system"}
{
"totalCount": 1,
"offers": [
{
"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,
"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 GET /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:
get:
tags:
- Special Offers
summary: Get Special Offer
description: Retrieves one or more special offers.
operationId: getSpecialOffer
parameters:
- name: publisherOfferIds
in: query
required: true
description: >-
The unique identifier for the offer. To retrieve multiple special
offers, separate them with a comma.
schema:
type: string
example: special-offer-1,special-offer-2
- name: x-publisher-token
in: header
required: true
description: The publisher token used for authentication.
schema:
type: string
responses:
'200':
description: Special Offer retrieved successfully.
content:
application/json:
schema:
type: object
properties:
totalCount:
type: number
description: Total number of matching offers.
offers:
type: array
items:
$ref: '#/components/schemas/SpecialOfferDtoResponse'
'401':
description: Unauthorized.
components:
schemas:
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
````