asoskill-com Billing API

openapi: 3.2.0
info:
  title: ASO Skill Developer Billing API
  version: 1.0.0
  description: 'Customer-facing API for App Store keyword search, autocomplete, difficulty,

    popularity, app metadata, credit balances, and credit purchases. Every successful data

    response costs one credit. Rejected requests and failed upstream calls do

    not consume a credit.


    Major versions are encoded in the URL. Existing `/v1/` operations do not

    receive intentional breaking changes; compatible additions may ship within

    v1, while breaking replacements use a new path such as `/v2/`. When

    practical, deprecated operations remain available for at least six months

    and return the RFC 9745 `Deprecation` header, a migration `Link` with

    `rel="deprecation"`, and an RFC 8594 `Sunset` header once removal is

    scheduled. See the developer guide for the complete policy.'
  contact:
    name: ASO Skill support
    email: viktor@asosuite.com
  license:
    name: Proprietary; use governed by the ASO Skill Terms
    url: https://www.asoskill.com/terms
servers:
- url: https://api.asoskill.com
  description: Production
security:
- bearerApiKey: []
tags:
- name: Billing
  description: Credit-pack discovery and Polar Checkout
paths:
  /v1/billing/packs:
    get:
      tags:
      - Billing
      security: []
      operationId: billingPacks
      summary: Discover available credit packs
      description: Returns the currently configured prepaid packs without creating a checkout. This public request does not cost a credit.
      responses:
        '200':
          description: Available packs, or billingEnabled false when online purchasing is unavailable
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPacksResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/billing/checkout:
    post:
      tags:
      - Billing
      operationId: checkout
      summary: Create a Polar-hosted credit checkout
      description: Returns a URL that the account owner must open to complete payment. Creating checkout does not cost a credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: Manual action containing a short-lived Polar Checkout URL
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountUnavailable'
        '428':
          $ref: '#/components/responses/LegalAcceptanceRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ApiError:
      type: object
      description: Machine-readable error details. Clients should branch on code and present message when useful; additional fields provide error-specific recovery context.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable snake_case identifier suitable for programmatic handling
          example: invalid_request
        message:
          type: string
          description: Human-readable explanation that is safe to show to the account owner
          example: The request body is invalid
        retryAfterSeconds:
          type: integer
          minimum: 1
          description: Suggested delay for a retryable failure, when applicable
      additionalProperties: true
    BillingPacksResponse:
      type: object
      required:
      - billingEnabled
      - unit
      - creditsPerDataCall
      - pricesIncludeTax
      - packs
      - checkout
      properties:
        billingEnabled:
          type: boolean
        unit:
          type: string
          const: credit
        creditsPerDataCall:
          type: integer
          const: 1
        pricesIncludeTax:
          type: boolean
          const: false
        packs:
          type: array
          items:
            $ref: '#/components/schemas/BillingPack'
        checkout:
          oneOf:
          - $ref: '#/components/schemas/CheckoutDiscovery'
          - type: 'null'
    GatewayMessage:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Too Many Requests
    CheckoutRequest:
      type: object
      required:
      - packId
      additionalProperties: false
      properties:
        packId:
          type: string
          pattern: ^[a-z][a-z0-9_]{2,63}$
    BillingPack:
      type: object
      required:
      - packId
      - credits
      - amountCents
      - currency
      - taxBehavior
      properties:
        packId:
          type: string
          pattern: ^[a-z][a-z0-9_]{2,63}$
        credits:
          type: integer
          minimum: 1
        amountCents:
          type: integer
          minimum: 1
        currency:
          type: string
          pattern: ^[a-z]{3}$
        taxBehavior:
          type: string
          const: exclusive
    CheckoutResponse:
      type: object
      required:
      - status
      - action
      - requestId
      properties:
        status:
          type: string
          const: action_required
        action:
          type: object
          required:
          - type
          - url
          - expiresAt
          - message
          properties:
            type:
              type: string
              const: open_url
            url:
              type:
              - string
              - 'null'
              format: uri
            expiresAt:
              type: integer
            message:
              type: string
        requestId:
          type: string
    ErrorResponse:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
    CheckoutDiscovery:
      type: object
      required:
      - method
      - path
      - body
      properties:
        method:
          type: string
          const: POST
        path:
          type: string
          const: /v1/billing/checkout
        body:
          type: object
          required:
          - packId
          properties:
            packId:
              type: string
  headers:
    RateLimitLimit:
      description: Compatibility field advertising the same maximum request rate.
      schema:
        type: integer
        example: 50
    RateLimitPolicy:
      description: API Gateway request policy for the route. This is a service-capacity hint, not a credit balance or per-account quota.
      schema:
        type: string
        example: '"default";q=50;w=1'
    RetryAfter:
      description: Number of seconds to wait before retrying. When absent, use exponential backoff with jitter.
      schema:
        type: integer
        minimum: 1
  responses:
    LegalAcceptanceRequired:
      description: The current Terms and Privacy Policy must be reviewed before purchasing credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Request capacity or a rate allowance was exceeded; no credit is consumed. Respect Retry-After when present, otherwise retry with exponential backoff and jitter.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/GatewayMessage'
    TemporarilyUnavailable:
      description: ASO Skill or an upstream service is temporarily unavailable; any reserved credit is restored. Retry after the indicated delay when provided.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AccountUnavailable:
      description: The account is unavailable or disabled; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected processing failure; any reserved credit is restored
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvalidRequest:
      description: The request body or parameters are invalid; no credit is consumed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The bearer credential is missing, invalid, expired, or revoked; no credit is consumed
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - $ref: '#/components/schemas/GatewayMessage'
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: aso_live_...
      description: 'Long-lived secret created in the ASO Skill developer dashboard. Send it as `Authorization: Bearer <key>` and keep it on the server.'
    mcpOAuth:
      type: oauth2
      description: OAuth authorization code with S256 PKCE, dynamic client registration, exact MCP resource binding, refresh rotation, and revocation.
      flows:
        authorizationCode:
          authorizationUrl: https://api.asoskill.com/oauth/authorize
          tokenUrl: https://api.asoskill.com/oauth/token
          refreshUrl: https://api.asoskill.com/oauth/token
          scopes:
            data: Search, autocomplete, popularity, and app metadata tools
            credits: Read the connected account credit balance
externalDocs:
  description: Developer guide, including versioning and deprecation policy
  url: https://www.asoskill.com/developers#versioning
x-api-versioning:
  strategy: path
  currentMajorVersion: v1
  backwardCompatibleChangesWithinMajor: true
  minimumDeprecationPeriod: P6M
  policy: https://www.asoskill.com/developers#versioning