Appcharge General API

openapi: 3.2.0
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:
    LocalizedPricePointLookupRequest:
      type: object
      required:
      - pricesInUsdCents
      - countryCode2
      properties:
        pricesInUsdCents:
          type: array
          description: List of base prices in USD.
          items:
            type: number
          maxItems: 50
          example:
          - 699
          - 4550
          - 9999
        countryCode2:
          type: string
          description: Country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
          example: DE
    Transaction:
      type: object
      properties:
        orderId:
          type: string
          description: Order ID.
          example: ac_order_98f3pb4
        purchaseId:
          type: string
          description: Purchase ID.
          example: pr-1234-5678-9012-34567
        publisherTransactionId:
          type: string
          description: Transaction ID.
          example: ca-9832-custom
        timestamp:
          type: string
          format: date-time
          description: Transaction timestamp in [UTC ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
          example: '2025-05-26T14:30:00.000Z'
        customerDetails:
          type: object
          description: Customer information.
          properties:
            id:
              type: string
              description: Customer ID.
              example: jane-doe
            email:
              type: string
              description: Customer email address.
              example: jan.doe@example.com
        geolocation:
          type: object
          description: Geolocation information.
          properties:
            countryCode2:
              type: string
              description: Country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
              example: US
            region:
              type: string
              description: Region or state.
              example: CA
            ipAddress:
              type: string
              description: IP address.
              example: 192.168.1.10
            zipCode:
              type: string
              description: Postal code.
              example: '94107'
        offerDetails:
          type: object
          description: Offer information.
          properties:
            offerId:
              type: string
              description: Offer ID.
              example: offer_7890
            offerName:
              type: string
              description: Offer name.
              example: Gem Pack
            type:
              type: string
              description: Offer type.
              example: Bundle
            products:
              type: array
              description: List of products in the offer.
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Product name.
                    example: Gems
                  sku:
                    type: string
                    description: Product SKU.
                    example: gems_100
                  quantity:
                    type: number
                    description: Product quantity.
                    example: 100
        transactionDetails:
          type: object
          description: Transaction information.
          properties:
            id:
              type: string
              description: Transaction ID.
              example: 64c9f6a12e1b4a3d9c7a5f1ef
            type:
              type: string
              description: Transaction type.
              enum:
              - paid
              - refund
              - dispute_funds_withdrawn
              - dispute_funds_reinstated
              example: paid
            amount:
              type: number
              description: Transaction amount in the local currency's smallest unit. For example, if the amount is $9.99, the API returns `999`, not `9.99`. 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.
              example: 999
            amount

# --- 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