openapi: 3.0.3
info:
  title: Appcharge Assets Coupons 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: Coupons
paths:
  /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
components:
  schemas:
    Coupon:
      type: object
      properties:
        name:
          type: string
          description: Coupon name.
          example: summer26
        active:
          type: boolean
          description: Whether the coupon is active.
          example: true
        discountPercentage:
          type: number
          description: Discount percentage applied by the coupon.
          example: 1
        maxRedemptionsPerCustomer:
          type: integer
          description: Maximum number of times a customer can redeem this coupon.
          example: 2
        expiredBy:
          type: string
          format: date-time
          description: Expiration date of the coupon.
          example: '2025-04-02T06:54:51.670Z'
        startsAt:
          type: string
          format: date-time
          description: Start date of the coupon validity.
          example: '2025-02-02T06:54:51.670Z'
        supportedOfferExternalIds:
          type: array
          items:
            type: string
          description: List of offer external IDs that support this coupon. Empty array means all offers are supported.
          example:
          - bundle1
          - rollingoffer3
        firstTimePurchase:
          type: boolean
          description: Whether the coupon is only valid for first-time purchases.
          example: false
        allowedPlayers:
          type: array
          items:
            type: string
          description: List of player IDs allowed to use this coupon. Empty array means all players are allowed.
          example:
          - player123
          - player456
          - player789
    UpdateCouponRequest:
      type: object
      properties:
        active:
          type: boolean
          description: Whether the coupon is active.
          example: false
        maxRedemptionsPerCustomer:
          type: integer
          nullable: true
          description: Maximum number of times a customer can redeem this coupon. Set to `null` to remove the maximum redemptions per customer.
          example: 5
        expiredBy:
          type: string
          format: date-time
          nullable: true
          description: Expiration date of the coupon. Set to `null` to remove the expiration date and make the coupon permanent.
          example: '2026-12-31T23:59:59.000Z'
        startsAt:
          type: string
          format: date-time
          description: Start date of the coupon validity. If not provided, defaults to current date and time.
          example: '2026-06-16T09:30:53.378Z'
        supportedOfferExternalIds:
          type: array
          items:
            type: string
          description: "List of offer external IDs that support this coupon. Empty array means all offers are supported. \n\n **Note:** This represents both the `offer.sku` value in the [Create Checkout Session API](../checkout-session/create-checkout-session), and the `publisherOfferId` in the [Offers V2 API](../../webstore/offers-v2/introduction)."
          example:
          - bundle1
          - rollingoffer3
        firstTimePurchase:
          type: boolean
          description: Whether the coupon is only valid for first-time purchases.
          example: false
        allowedPlayers:
          type: array
          items:
            type: string
          description: List of player IDs allowed to use this coupon. Empty array means all players are allowed.
          example:
          - player123
          - player456
    CreateCouponRequest:
      type: object
      properties:
        name:
          type: string
          description: Coupon name. Can't contain spaces or special characters.
          example: summer26
        discountPercentage:
          type: number
          description: Discount percentage applied by the coupon.
          example: 1
        active:
          type: boolean
          description: Whether the coupon is active.
          default: true
          example: true
        maxRedemptionsPerCustomer:
          type: integer
          description: Maximum number of times a customer can redeem this coupon.
          example: 2
        expiredBy:
          type: string
          format: date-time
          description: Expiration date of the coupon.
          example: '2025-04-02T06:54:51.670Z'
        startsAt:
          type: string
          format: date-time
          description: Start date of the coupon validity. If not provided, defaults to current date and time.
          example: '2025-02-02T06:54:51.670Z'
        supportedOfferExternalIds:
          type: array
          items:
            type: string
          description: "List of offer IDs which this coupon applies. Empty array means all offers are supported. \n\n **Note:** This represents both the `offer.sku` value in the [Create Checkout Session API](../checkout-session/create-checkout-session), and the `publisherOfferId` in the [Offers V2 API](../../webstore/offers-v2/introduction)."
          example:
          - bundle1
          - rollingoffer3
        firstTimePurchase:
          type: boolean
          description: Whether the coupon is only valid for first-time purchases.
          default: false
          example: false
        allowedPlayers:
          type: array
          items:
            type: string
          description: List of player IDs that can redeem this coupon.
      required:
      - name
      - discountPercentage
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong.
    CouponResponse:
      $ref: '#/components/schemas/Coupon'
  securitySchemes:
    PublisherTokenAuth:
      type: apiKey
      in: header
      name: x-publisher-token
      description: Publisher token, as displayed in the Publisher Dashboard.