Appcharge General API
The General API from Appcharge — 9 operation(s) for general.
OpenAPI Specification
openapi: 3.0.3
info:
title: Appcharge Assets General API
version: 1.0.0
description: Appcharge is a monetization platform for mobile games, providing a direct-to-consumer (D2C) web store, mobile Checkout SDK, and Payment Links so publishers can sell in-game offers outside the app stores. This API covers checkout sessions, refunds, coupons and promo codes, price localization, financial and analytics reporting, web store offers (bundles, daily bonuses, rolling/special offers, progress bars, reward calendars, triggered popups), offer components (products, badges, offer designs), game-portal content, media assets, translations, and player personalization/authentication callbacks. Authentication uses the x-publisher-token header; webhooks are signed with an HMAC-SHA256 signature.
contact:
name: Appcharge Developer Support
url: https://docs.appcharge.com/
x-apievangelist-source: https://docs.appcharge.com/api-reference (Mintlify embedded OpenAPI fragments)
x-apievangelist-method: searched
x-apievangelist-generated: '2026-07-17'
servers:
- url: https://api.appcharge.com
description: Production
- url: https://api-sandbox.appcharge.com
description: Sandbox
tags:
- name: General
paths:
/checkout/v3/cancel:
post:
summary: Cancel Checkout Session
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
example: Bearer ba5af26a21ec497cb1551821c630d9f9
description: "Authorization header in the format: `Bearer ${checkoutSessionToken}`. \n\n The checkout session token is retrieved from the [Create Checkout Session API](/../../api-reference/checkout/checkout-session/create-checkout-session) and serves as the checkout session ID."
responses:
'200':
description: Result.
content:
application/json:
schema:
type: object
properties:
isOrderCancelled:
type: boolean
description: Whether the checkout session is no longer available, and can't accept further payments. **Note:** This property only reflects the cancellation of the session, not the order. To track order status, listen for [Order Events](../../events/introduction#order-events), or [view the list of orders](/../../guides/publisher-dashboard/view-orders) in the Publisher Dashboard.
'400':
description: Bad request.
'401':
description: Unauthorized - invalid or missing token.
'500':
description: Internal server error.
operationId: cancelCheckoutSession
tags:
- General
/checkout/v1/session:
post:
summary: Create Checkout Session
description: Creates a checkout session.
parameters:
- in: header
name: x-publisher-token
required: true
schema:
type: string
description: Your checkout token that will be presented at Appcharge's dashboard under Admin section -> Integration tab -> Publisher token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSessionRequest'
responses:
'201':
description: Checkout session created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSessionResponse'
'400':
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Detailed message describing the error.
example: 'Blocked player: this player has been blocked. See the blocked player list in the dashboard for more info.'
operationId: createCheckoutSession
tags:
- General
/reporting/financial-data/transactions:
get:
summary: Get Transactions
description: Retrieves transaction data for a given time period.
operationId: getTransactions
parameters:
- in: query
name: startDate
required: true
schema:
type: string
format: date-time
example: '2025-05-26T00:00:00Z'
description: Start date of the query in [UTC ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- in: query
name: endDate
required: true
schema:
type: string
format: date-time
example: '2025-07-24T23:59:59Z'
description: End date of the query in [UTC ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- in: query
name: limit
required: false
schema:
type: integer
default: 10
description: "Maximum number of transactions to return per page. \n\n **Min:** 1 \n **Max:** 10,000"
- in: query
name: sortDirection
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: Sort order of the results based on the `timestamp` field.
- in: header
name: x-publisher-token
schema:
type: string
required: true
description: Publisher token.
responses:
'200':
description: Successfully retrieved transactions.
content:
application/json:
schema:
type: object
properties:
totalCount:
type: integer
description: Total number of transactions matching the query.
example: '245'
nextCursor:
type: string
description: Cursor pointing to the next page of results.
example: eyJpZCI6IjY0YzkidQ==
nextPageQuery:
type: string
description: Fully-formed query string for fetching the next page of results.
example: ?startDate=2025-05-26T00:00:00Z&endDate=2025-07-24T23:59:59Z&limit=100&sortDirection=asc&cursor=eyJpZCI6IjY0YzkidQ==
results:
type: array
items:
$ref: '#/components/schemas/Transaction'
description: List of transaction results returned by the query.
'400':
description: Bad request - invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
examples:
dateValidation:
summary: Date validation error.
value:
statusCode: 400
error: Bad Request
message:
- validationErrorNumber: 1
error: endDate must be after startDate.
requestUrl: /reporting/financial-data/transactions?startDate=2025-07-24T00:00:00Z&endDate=2025-05-26T23:59:59Z
invalidSortDirection:
summary: Invalid sort direction.
value:
statusCode: 400
error: Bad Request
message:
- validationErrorNumber: 1
error: sortDirection must be either "asc" or "desc".
requestUrl: /reporting/financial-data/transactions?startDate=2025-05-26T00:00:00Z&endDate=2025-07-24T23:59:59Z&sortDirection=invalid
'401':
description: Unauthorized - authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
examples:
missingToken:
summary: Missing publisher token.
value:
statusCode: 401
error: Unauthorized
message:
- validationErrorNumber: 1
error: Publisher token is required.
requestUrl: /reporting/financial-data/transactions?startDate=2025-05-26T00:00:00Z&endDate=2025-07-24T23:59:59Z
invalidToken:
summary: Invalid publisher token.
value:
statusCode: 401
error: Unauthorized
message:
- validationErrorNumber: 1
error: Publisher not found.
requestUrl: /reporting/financial-data/transactions?startDate=2025-05-26T00:00:00Z&endDate=2025-07-24T23:59:59Z
tokenLookupFailed:
summary: Token lookup failed.
value:
statusCode: 401
error: Unauthorized
message:
- validationErrorNumber: 1
error: Failed to authorize publisher token.
requestUrl: /reporting/financial-data/transactions?startDate=2025-05-26T00:00:00Z&endDate=2025-07-24T23:59:59Z
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
examples:
serverError:
summary: Server error
value:
statusCode: 500
error: Internal Server Error
message:
- validationErrorNumber: 1
error: Failed to get transactions
requestUrl: /reporting/financial-data/transactions?startDate=2025-05-26T00:00:00Z&endDate=2025-07-24T23:59:59Z
tags:
- General
/v1/price-points:
post:
summary: Create a Price Point
description: 'Creates a price point.
When you pass the base price in USD, the API returns localized prices for this price point in all currencies supported by Appcharge. Learn more about [how localized prices are calculated](./introduction#how-localized-prices-are-calculated).
To override automatically calculated prices for specific countries, pass the `priceOverrides` property with the relevant country codes and your custom prices.'
operationId: createPricePoint
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
priceInUsdCents:
type: number
description: Base price in USD cents.
example: 999
priceOverrides:
type: array
items:
$ref: '#/components/schemas/PriceOverride'
description: "List of country-specific prices that replace the auto-calculated price.\n\nExchange rates and rounding rules aren't applied. If a country's tax model includes taxes in the price, make sure the custom price include tax. If a country's tax model excludes tax from the price, Appcharge adds the applicable tax during checkout.\n\n Overrides apply only to the countries you specify."
example:
priceInUsdCents: 999
priceOverrides:
- countryCode2: BR
price: 29.99
responses:
'201':
description: Price point created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PricePoint'
'400':
description: Bad request. This can occur due to a schema validation error or an invalid country code.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
examples:
schemaError:
summary: Schema validation error
value:
message: Invalid request body
badCountryCode:
summary: Invalid country code
value:
message: Country code ZZ not found in existing custom pricing.
'409':
description: Conflict. The price point already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictErrorResponse'
example:
message: Cannot create new pricing. The price point already exists.
tags:
- General
get:
summary: Get all Price Points
description: Retrieves a list of all price points in USD cents.
operationId: getAllPricePoints
responses:
'200':
description: Price points retrieved successfully.
content:
application/json:
schema:
type: object
properties:
pricePoints:
type: array
items:
$ref: '#/components/schemas/PricePointSummary'
tags:
- General
/v1/price-points/{priceInUsdCents}:
delete:
summary: Delete a Price Point
description: Deletes a specific price point.
operationId: deletePricePoint
parameters:
- name: priceInUsdCents
in: path
required: true
schema:
type: number
example: 999
description: Base price in USD cents.
responses:
'200':
description: Price point deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PricePoint'
'404':
description: Price point not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: Price point 999 not found.
tags:
- General
get:
summary: Get a Price Point
description: Retrieves a specific price point by its base price in USD cents. The API returns localized prices for this price point.
operationId: getPricePoint
parameters:
- name: priceInUsdCents
in: path
required: true
schema:
type: number
example: 999
description: Base price in USD cents.
responses:
'200':
description: Price point retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PricePointDetailed'
'404':
description: Price point not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: Price point 999 not found.
tags:
- General
put:
summary: Update a Price Point
description: 'Updates a price point.
When a price point is updated, Appcharge recalculates all localized prices. If both `priceInUsdCents` and `priceOverrides` are provided in the same request, Appcharge first recalculates localized prices from the updated base price and then applies the override values.'
operationId: updatePricePoint
parameters:
- name: priceInUsdCents
in: path
required: true
schema:
type: number
example: 999
description: Base price in USD cents.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
updatedPriceInUsdCents:
type: number
description: New base price in USD cents.
example: 999
priceOverrides:
type: array
items:
$ref: '#/components/schemas/PriceOverride'
description: "List of country-specific prices that replace the auto-calculated price. \n\nExchange rates and rounding rules aren't applied. If a country's tax model includes taxes in the price, make sure the custom price include tax. If a country's tax model excludes tax from the price, Appcharge adds the applicable tax during checkout.\n\n Overrides apply only to the countries you specify."
additionalProperties: false
responses:
'200':
description: Price point updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PricePoint'
'400':
description: Bad request. This can occur due to a schema validation error or an invalid country code.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
examples:
schemaError:
summary: Schema validation error
value:
message: Invalid request body
badCountryCode:
summary: Invalid country code
value:
message: Country code ZZ not found in existing custom pricing.
'404':
description: Price point not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: Price point 999 not found.
'409':
description: Conflict. The price point already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictErrorResponse'
example:
message: Cannot create new pricing. The price point already exists.
tags:
- General
/v1/price-points/localized/lookup:
post:
summary: Get Price Points for a Country
description: 'Retrieves price points localized for a specific country.
Pass price points in USD cents and a country code. The API returns each requested price point with its localized price in the currency for that country.'
operationId: lookupLocalizedPricePoints
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocalizedPricePointLookupRequest'
examples:
byCountry:
summary: Get by country
value:
pricesInUsdCents:
- 699
- 4550
- 9999
countryCode2: DE
responses:
'200':
description: Localized price points retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/LocalizedPricePointLookupResponse'
examples:
localizedPrices:
summary: All requested price points configured
value:
currencyCode: EUR
pricePoints:
'699':
price: 664
displayPrice: 6,64 €
'4550':
price: 4323
displayPrice: 43,23 €
'9999':
price: 9499
displayPrice: 94,99 €
missingPricePoint:
summary: One requested price point is not configured
value:
currencyCode: EUR
pricePoints:
'699':
price: 664
displayPrice: 6,64 €
'12000': null
'400':
description: Bad request. All errors return a `message` property.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
examples:
tooManyPricePoints:
summary: Too many price points
value:
message: Too many price points used, maximum is 50.
invalidPricePoint:
summary: Invalid price point
value:
message: 'Invalid priceInUsdCents value: must be a positive integer [invalid1, invalid2].'
invalidCountryCode:
summary: Invalid country code
value:
message: 'Invalid countryCode2: must be ISO 3166-1 alpha-2.'
unsupportedCountry:
summary: Unsupported country
value:
message: countryCode2 XX is not supported.
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: Unauthorized
'429':
description: Too many requests. The rate limit is 5,000 requests per minute.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: Rate limit exceeded.
tags:
- General
/checkout/api/v1/order/{orderId}/refund:
post:
summary: Initiate Refund
description: Initiates a full refund for a specified order. <br /> <br /> Once the API call is successful, the refund process begins. The result of the refund, whether it succeeds or fails, is communicated asynchronously when the order status updates to `Refunded` or `Refund Failed`. You can track the order status in the **Orders** tab of the Publisher Dashboard. <br /> <br /> If the refund is completed successfully, the total order amount is reimbursed, and the [Order Refunded](../../events/v2/order/order_refunded) event is triggered. <br /> <br /> **Note:** This action is final and can't be undone.
operationId: createRefund
parameters:
- name: orderId
in: path
required: true
schema:
type: string
description: Order ID to refund.
- name: x-publisher-token
in: header
required: true
schema:
type: string
description: The publisher token used for authentication.
- name: x-user-id
in: header
required: true
schema:
type: string
description: The user ID initiating the refund for the order.
responses:
'201':
description: Refund initiated successfully.
content:
application/json:
schema:
type: object
description: Returns an empty object.
examples:
success:
summary: Empty success response
value: {}
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
result:
type: string
description: Refund result.
errCode:
type: string
description: Error code.
message:
type: string
description: Error message.
examples:
forbidden:
value:
result: null
errCode: -1
message: Forbidden resource
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message.
examples:
forbidden:
value:
message: Order does not exist or cannot be found.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message.
examples:
refundFailure:
summary: Refund failure response
value:
message: Failed to initiate a refund request
tags:
- General
/refresh-specific-active-players:
post:
summary: Triggers the Personalization API
description: Triggers the [Personalize Web Store Callback](./personalize-webstore-callback) by player ID.
operationId: triggerPersonalization2
parameters:
- in: header
name: x-publisher-token
schema:
type: string
required: true
description: Publisher token.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- playerIds
properties:
playerIds:
type: array
items:
type: string
description: Player IDs to trigger web store personalization.
example:
- player123
- player456
- player789
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
message:
description: Success message.
type: string
example: Event triggered for publisher 6422d554acc1a482bac4698e7
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message.
example: Schema Validation Error
requestUrl:
type: string
description: Request URL.
example: /store/v1/personalization/refresh-specific-active-players
body:
type: string
description: Detailed error description.
example: 'Property playerIds has failed the following validations: each value in playerIds must be a string, playerIds must contain at least 1 elements, playerIds must be an array.'
tags:
- General
/refresh-active-players:
post:
summary: Triggers the Personalization API
description: "Triggers the [Personalize Web Store Callback](./personalize-webstore-callback) for all players. \n\n When refreshing data for all active players, Appcharge identifies everyone currently browsing the web store, and updates their store view in real time."
operationId: triggerPersonalization
parameters:
- in: header
name: x-publisher-token
schema:
type: string
required: true
description: Publisher token.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
message:
description: Success message.
type: string
example: Event triggered for publisher 6422d554acc1a482bac4698e7
'400':
description: Bad request. Missing or invalid parameters.
'500':
description: Internal server error.
tags:
- General
components:
schemas:
CheckoutSessionRequest:
type: object
required:
- priceDetails
- offer
- customer
properties:
priceDetails:
type: object
required:
- price
- currency
properties:
price:
type: integer
description: Price in the smallest currency unit. For example, if the price is $10.00, pass `1000`, not `10.00`. For currencies with no subunit, such as JPY, the value represents the full unit. See [Supported Currencies](/../../merchant-of-record/finance/supported-currencies) for per-currency decimal rules.
default: 1000
currency:
type: string
description: Currency in ISO 4217 format.
default: USD
offer:
type: object
required:
- name
- sku
properties:
name:
type: string
description: Offer name. Cannot be an empty string.
example: Treasure Chest
sku:
type: string
description: Offer ID (SKU).
example: 68452829c5e8
displayName:
type: string
description: Localized offer name.
pricePointMetadata:
type: integer
description: Base price of the price point in USD cents.
items:
type: array
description: List of items in the offer.
items:
type: object
required:
- name
- sku
- quantity
properties:
name:
type: string
description: Item name.
example: coins
assetUrl:
type: string
format: uri
description: URL of the asset (should be on a CDN).
example: https://media-dev.appcharge.com/coin.png
sku:
type: string
description: Item SKU.
example: coins_386f9b
quantity:
type: integer
description: Item quantity. Should be minimum 0 and equal to or less than 30 digits long.
example: 3300000
quantityDisplay:
type: string
description: Overrides the `quantity` value displayed in the checkout. Useful for presenting time-based products or showing abbreviated values.
example: 3.3M
displayName:
type: string
description: Localized item name.
countryCode2:
type: string
description: "Two-letter country code of the player in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. This property is used for determining taxes in the Checkout. If not provided, Appcharge determines the customer's country from the player's IP address. \n\n **Note:** Manually setting a country will determine the applicable tax jurisdiction and rates. Ensure that any country values passed via the API comply with your regulatory and business requirements."
example: US
customer:
type: object
required:
- id
properties:
id:
type: string
description: Unique customer identifier.
example: 7c99fba665c4a
email:
type: string
format: email
description: Customer email address.
example: customer@appcharge.com
identitySignals:
type: object
description: Information regarding the player's identity. Pass this field to improve risk decisions and reduce false declines.
properties:
firstSeenAt:
type: string
format: date-time
description: First time the player was observed on your monetization platform. For example, the player's account creation date in your game. Used to differentiate veteran players from new accounts during risk evaluation. Must be a past date.
example: '2021-01-01T00:00:00Z'
receiptMe
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appcharge/refs/heads/main/openapi/appcharge-general-api-openapi.yml