> ## Documentation Index
> Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up a prepaid credit balance

> Balances are split in two: `face_cents` is paid-for value (5 years, per the CARD Act) and `bonus_cents` is promotional value (12 months, spent first).



## OpenAPI

````yaml /openapi.json get /v1/credits/{code}
openapi: 3.1.0
info:
  title: paperplane API
  version: 1.0.0
  summary: Send real physical mail from code.
  description: >-
    Upload a PDF or paste text; we print it and hand it to USPS the next
    business day. No account required — pay per letter with a Stripe link or a
    prepaid credit code, and use `sandbox: true` to exercise the whole flow for
    free.


    Every failure returns the same envelope: `status`, a stable machine-readable
    `code`, a human `reason`, and a `next` array of concrete recovery steps.


    This document is generated from the same zod schemas the server validates
    with, so it cannot describe an endpoint that does not exist.
  contact:
    name: paperplane support
    url: https://sendpaperplane.com/contact
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  termsOfService: https://sendpaperplane.com/terms
servers:
  - url: https://sendpaperplane.com
    description: Production
security: []
tags:
  - name: Mail
    description: Quote, send, track, and cancel letters.
  - name: Credits
    description: Prepaid balances that pay for letters without a card.
  - name: Reviews
    description: Post-delivery feedback. Identity is derived from the order, not supplied.
  - name: Addresses
    description: >-
      Typeahead and reverse geocoding. Convenience only; USPS verification is
      authoritative.
  - name: Meta
    description: Machine-readable description of this API.
paths:
  /v1/credits/{code}:
    get:
      tags:
        - Credits
      summary: Look up a prepaid credit balance
      description: >-
        Balances are split in two: `face_cents` is paid-for value (5 years, per
        the CARD Act) and `bonus_cents` is promotional value (12 months, spent
        first).
      operationId: getCreditBalance
      parameters:
        - name: code
          in: path
          required: true
          description: >-
            Credit code, formatted pp-xxxx-xxxx-xxxx. Case-insensitive — the
            route lower-cases before lookup.
          schema:
            type: string
            pattern: ^[Pp][Pp]-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}$
      responses:
        '200':
          description: Spendable balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalanceResponse'
              example:
                status: ok
                code: pp-ab12-cd34-ef56
                balance_cents: 5400
                face_cents: 5000
                bonus_cents: 400
                bonus_expires_at: '2027-08-23T00:00:00.000Z'
                face_expires_at: '2031-08-23T00:00:00.000Z'
        '404':
          description: No credit account with that code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreditBalanceResponse:
      type: object
      properties:
        status:
          type: string
          const: ok
        code:
          type: string
        balance_cents:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        face_cents:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        bonus_cents:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        bonus_expires_at:
          type: string
        face_expires_at:
          type: string
      required:
        - status
        - code
        - balance_cents
        - face_cents
        - bonus_cents
        - bonus_expires_at
        - face_expires_at
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
            - failed
            - action_required
        code:
          type: string
        reason:
          type: string
        next:
          type: array
          items:
            type: string
      required:
        - status
        - code
        - reason
        - next

````