The Appcharge Publisher REST API for checkout sessions, refunds, coupons and promo codes, price localization, financial/analytics reporting, web-store offers and components, game-portal content, assets, translations, and player personalization/authentication callbacks. Authenticated with the x-publisher-token header; callbacks/webhooks are HMAC-SHA256 signed.
openapi: 3.0.3
info:
title: Appcharge 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: Assets
- name: Authentication
- name: Badges
- name: Coupons
- name: General
- name: Localization
- name: Offer Designs
- name: Offers
- name: Orders
- name: Personalization
- name: Popups
- name: Portal Content
- name: Products
- name: Promo Codes
- name: Rolling Offers
- name: Store Refresh Popups
- name: Triggered Popups
paths:
/{YOUR_GRANT_AWARD_ENDPOINT}:
post:
tags:
- Orders
description: "<Note> This is a callback API. Appcharge calls this endpoint on your server when specific\
\ events occur. </Note> \n\n Notifies your system to grant an award to a customer. \n \n Appcharge\
\ calls this endpoint after a customer payment is finalized or when a free offer is collected.\
\ \n\n When your server responds with a valid `publisherPurchaseId`, Appcharge redirects the customer\
\ to the success page confirming their purchase. \n\n <Warning>Your server must return a valid\
\ `publisherPurchaseId` value to confirm the award has been sucessfully granted. If the property\
\ is missing or invalid, the award is marked as unsuccessful, and an alert is triggered. </Warning>"
operationId: grant-award
parameters:
- name: x-publisher-token
in: header
schema:
type: string
description: Publisher token.
- name: signature
in: header
schema:
type: string
description: '[Signature](/../../api-reference/appcharge-publisher-secure-communication).'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerOrderReportRequest'
responses:
'200':
description: Successfully granted award to customer.
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerOrderReportSuccess'
'400':
description: Award request failed because of a client error. The response body must include
`publisherErrorMessage`.
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerOrderReportError'
example:
publisherErrorMessage: Unable to grant the award because the player ID is invalid.
examples:
'400':
summary: '400'
value:
publisherErrorMessage: Unable to grant the award because the player ID is invalid.
'500':
description: Award request failed because of a server error. The response body must include
`publisherErrorMessage`.
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerOrderReportError'
example:
publisherErrorMessage: Unable to grant the award because the inventory service is unavailable.
examples:
'500':
summary: '500'
value:
publisherErrorMessage: Unable to grant the award because the inventory service is
unavailable.
/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
/coupons/coupon/{couponName}/promo-codes:
parameters:
- in: path
name: couponName
required: true
schema:
type: string
example: summer26
description: Coupon name.
post:
tags:
- Promo Codes
description: Creates multiple promo codes for a specific coupon. <br/><br/> Maximum of 1,000 promo
codes allowed per request.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePromoCodesRequest'
responses:
'200':
description: Promo codes created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PromoCodesResponse'
'400':
description: Bad request. Invalid input or validation failure.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidCouponName:
summary: Invalid coupon name
value:
error: Invalid coupon name. Use only English letters and numbers.
invalidPromoCodeName:
summary: Invalid promo code name
value:
error: Invalid promo code name. Use only English letters and numbers.
promoCodesBelowMinimum:
summary: Promo codes count below minimum
value:
error: Promo codes count must be at least 1.
promoCodesAboveMaximum:
summary: Promo codes count above maximum
value:
error: Promo codes count must not exceed 1000.
duplicatePromoCodes:
summary: Duplicate promo codes in request
value:
error: 'Some promo codes in the request are duplicated: swx1, swx2.'
maxRedemptionsBelowMinimum:
summary: maxRedemptions below minimum
value:
error: maxRedemptions must not be less than 1
missingRequiredField:
summary: Required field missing
value:
error: 'Missing required field: promoCodes.'
'404':
description: Coupon not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponNotFound:
summary: Coupon not found
value:
error: Coupon not found.
'409':
description: Conflict. One or more promo codes already exist and are active on another coupon.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
promoCodeExists:
summary: Promo code already active on another coupon
value:
error: 'Some promo codes are already active on other coupon: swx1, swx2.'
'500':
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unexpectedError:
summary: Unexpected error
value:
error: Unexpected error. Please contact support.
operationId: postCouponsCouponCouponnamePromoCodes
get:
tags:
- Promo Codes
description: Retrieves a paginated list of up to 1,000 promo codes for a specific coupon.
parameters:
- in: query
name: limit
required: false
schema:
type: integer
example: 1000
description: Maximum number of promo codes to return.
- in: query
name: page
required: false
schema:
type: integer
example: 1
description: Page number to retrieve.
- in: query
name: sortDirection
required: false
schema:
type: string
default: asc
enum:
- asc
- desc
example: desc
description: Sort direction of results by `createdAt`.
- in: query
name: isActive
required: false
schema:
type: boolean
example: true
description: Filter by active status.
responses:
'200':
description: Promo codes retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListPromoCodesResponse'
'404':
description: Coupon not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponNotFound:
summary: Coupon not found
value:
error: Coupon not found.
operationId: getCouponsCouponCouponnamePromoCodes
/coupons/coupon/{couponName}/promo-codes/set-activation:
parameters:
- in: path
name: couponName
required: true
schema:
type: string
example: summer26
description: Coupon name.
patch:
tags:
- Promo Codes
description: Activates or deactivates promo codes for a specific coupon. <br/><br/> Maximum of 1,000
promo code names allowed per request.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PromoCodeActivationRequest'
responses:
'200':
description: Promo codes updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PromoCodeActivationResponse'
'400':
description: Bad request. Invalid input or validation failure.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
promoCodeNamesBelowMinimum:
summary: Promo code names count below minimum
value:
error: Promo code names count must be at least 1.
promoCodeNamesAboveMaximum:
summary: Promo code names count above maximum
value:
error: Promo code names count must not exceed 1000.
'404':
description: Coupon not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponNotFound:
summary: Coupon not found
value:
error: Coupon not found.
'500':
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unexpectedError:
summary: Unexpected error
value:
error: Unexpected error. Please contact support.
operationId: patchCouponsCouponCouponnamePromoCodesSetActivation
/coupons/coupon:
post:
tags:
- Coupons
description: Creates a coupon.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCouponRequest'
responses:
'200':
description: Coupon created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CouponResponse'
'400':
description: Bad request. Invalid input or validation failure.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidCouponName:
summary: Invalid coupon name
value:
error: Invalid coupon name. Use only English letters and numbers.
missingRequiredField:
summary: Required field missing
value:
error: 'Missing required field: discountPercentage.'
startsAtInPast:
summary: startsAt is in the past
value:
error: startsAt must be in the future.
expiredByBeforeStartsAt:
summary: expiredBy is before startsAt
value:
error: expiredBy must be after startsAt.
discountPercentageOutOfRange:
summary: discountPercentage out of range
value:
error: discountPercentage must be between 1 and 99.
'409':
description: Conflict. A coupon with the same name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponExists:
summary: Coupon name already in use.
value:
error: Coupon name 'summer26' is already in use.
'500':
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unexpectedError:
summary: Unexpected error
value:
error: Unexpected error. Please contact support.
operationId: postCouponsCoupon
/coupons/coupon/{couponName}:
parameters:
- in: path
name: couponName
required: true
schema:
type: string
example: summer26
description: Coupon name.
get:
tags:
- Coupons
description: Retrieves a specific coupon by name.
responses:
'200':
description: Coupon retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CouponResponse'
'400':
description: Invalid coupon name.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponNotFound:
summary: Invalid coupon name.
value:
error: Invalid coupon name. Use only English letters and numbers.
'404':
description: Coupon not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponNotFound:
summary: Coupon not found.
value:
error: Coupon not found.
'500':
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unexpectedError:
summary: Unexpected error.
value:
error: Unexpected error. Please contact support.
operationId: getCouponsCouponCouponname
patch:
tags:
- Coupons
description: Updates an existing coupon. Only the fields provided in the request body will be updated.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCouponRequest'
responses:
'200':
description: Coupon updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CouponResponse'
'400':
description: Bad request. Invalid input or validation failure.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
startsAtInPast:
summary: startsAt is in the past
value:
error: startsAt must be in the future.
expiredByBeforeStartsAt:
summary: expiredBy is before startsAt
value:
error: expiredBy must be after startsAt.
forbiddenFields:
summary: Attempting to update non-updatable fields
value:
error: property name should not exist ; property discountPercentage should not exist
'404':
description: Coupon not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponNotFound:
summary: Coupon not found
value:
error: Coupon not found.
'500':
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unexpectedError:
summary: Unexpected error
value:
error: Unexpected error. Please contact support.
operationId: patchCouponsCouponCouponname
/coupons/coupon/{couponName}/promo-code/{promoCodeName}:
parameters:
- in: path
name: couponName
required: true
schema:
type: string
example: summer26
description: Coupon name.
- in: path
name: promoCodeName
required: true
schema:
type: string
example: swx1
description: Promo code name.
get:
tags:
- Promo Codes
description: Retrieves a specific promo code.
responses:
'200':
description: Promo code retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PromoCodeResponse'
'400':
description: Bad request. Invalid input or validation failure.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidCouponName:
summary: Invalid coupon name
value:
error: Invalid coupon name. Use only English letters and numbers.
invalidPromoCodeName:
summary: Invalid promo code name
value:
error: Invalid promo code name. Use only English letters and numbers.
'404':
description: Promo code or coupon not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
couponNotFound:
summary: Coupon not found
value:
error: Coupon not found.
promoCodeNotFound:
summary: Promo code not found
value:
error: Promo code not found.
'500':
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
unexpectedError:
summary: Unexpected error
value:
error: Unexpected error. Please contact support.
operationId: getCouponsCouponCouponnamePromoCodePromocodename
/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:
# --- truncated at 32 KB (452 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appcharge/refs/heads/main/openapi/appcharge-openapi.yml