openapi: 3.1.0
info:
  title: Coinbase Commerce Charges API
  description: 'Legacy REST API for creating and managing crypto payment charges. Merchants generate a charge object representing a payment request; customers pay to the charge address and the API tracks status through the full lifecycle from created → pending → confirmed or failed. Authentication uses the X-CC-Api-Key header and the API-Version header.

    '
  version: '2018-03-22'
  termsOfService: https://commerce.coinbase.com/legal/user-agreement
  contact:
    name: Coinbase Commerce Support
    url: https://help.coinbase.com/en/commerce
  license:
    name: Proprietary
servers:
- url: https://api.commerce.coinbase.com
  description: Coinbase Commerce production server
security:
- ApiKeyAuth: []
tags:
- name: Charges
  description: Create and retrieve crypto payment charges
paths:
  /charges:
    post:
      operationId: createCharge
      summary: Create a charge
      description: 'Creates a new crypto payment charge object. Returns a hosted payment URL and a charge code that the customer uses to complete payment.

        '
      tags:
      - Charges
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChargeRequest'
            example:
              name: Widget Order
              description: Order for 2 widgets
              local_price:
                amount: '49.99'
                currency: USD
              pricing_type: fixed_price
              redirect_url: https://yourstore.com/success
              cancel_url: https://yourstore.com/cancel
              metadata:
                customer_id: cust_42
                order_id: ord_99
      responses:
        '201':
          description: Charge created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: listCharges
      summary: List all charges
      description: Returns a paginated list of all charges for the merchant account.
      tags:
      - Charges
      parameters:
      - name: limit
        in: query
        description: Number of results per page (1–100, default 25)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: starting_after
        in: query
        description: Cursor for forward pagination (charge ID)
        schema:
          type: string
      - name: ending_before
        in: query
        description: Cursor for backward pagination (charge ID)
        schema:
          type: string
      responses:
        '200':
          description: List of charges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /charges/{charge_code_or_id}:
    get:
      operationId: getCharge
      summary: Retrieve a charge
      description: Returns the details of a specific charge by its ID or code.
      tags:
      - Charges
      parameters:
      - $ref: '#/components/parameters/ChargeCodeOrId'
      responses:
        '200':
          description: Charge details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /charges/{charge_code_or_id}/cancel:
    post:
      operationId: cancelCharge
      summary: Cancel a charge
      description: 'Cancels a charge that has not yet been confirmed. Only NEW charges can be cancelled; charges in PENDING or later states cannot be cancelled.

        '
      tags:
      - Charges
      parameters:
      - $ref: '#/components/parameters/ChargeCodeOrId'
      responses:
        '200':
          description: Cancelled charge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /charges/{charge_code_or_id}/resolve:
    post:
      operationId: resolveCharge
      summary: Resolve a charge
      description: 'Resolves a charge that has been overpaid or underpaid, marking it as resolved. Only applicable to UNRESOLVED charges.

        '
      tags:
      - Charges
      parameters:
      - $ref: '#/components/parameters/ChargeCodeOrId'
      responses:
        '200':
          description: Resolved charge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PricingType:
      type: string
      enum:
      - fixed_price
      - no_price
      description: '`fixed_price` charges the customer a specific fiat amount converted to crypto. `no_price` lets the customer pay any amount.

        '
    Money:
      type: object
      description: A monetary amount with currency
      required:
      - amount
      - currency
      properties:
        amount:
          type: string
          description: Decimal amount string (e.g. "49.99")
          example: '49.99'
        currency:
          type: string
          description: ISO 4217 currency code (fiat) or crypto ticker
          example: USD
    ChargeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Charge'
    ChargeListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Charge'
        cursor_range:
          type: array
          items:
            type: string
          description: Pagination cursors [start, end]
    CreateChargeRequest:
      type: object
      required:
      - name
      - description
      - pricing_type
      properties:
        name:
          type: string
          description: Charge name shown to the customer
          maxLength: 200
        description:
          type: string
          description: Short description of what is being purchased
          maxLength: 500
        local_price:
          $ref: '#/components/schemas/Money'
          description: Required when pricing_type is fixed_price
        pricing_type:
          $ref: '#/components/schemas/PricingType'
        redirect_url:
          type: string
          format: uri
          description: URL to redirect the customer after a successful payment
        cancel_url:
          type: string
          format: uri
          description: URL to redirect the customer if they cancel the payment
        metadata:
          type: object
          description: Arbitrary key-value metadata (max 20 keys, 100 chars per value)
          additionalProperties:
            type: string
    ChargeStatus:
      type: string
      description: The current lifecycle status of the charge
      enum:
      - NEW
      - PENDING
      - COMPLETED
      - EXPIRED
      - UNRESOLVED
      - RESOLVED
      - CANCELED
      - CANCELATION_COMPLETE
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error type identifier
            message:
              type: string
              description: Human-readable error description
    TimelineEntry:
      type: object
      properties:
        time:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/ChargeStatus'
        context:
          type: string
          description: Additional context for UNRESOLVED statuses (e.g. UNDERPAID, OVERPAID)
    Payment:
      type: object
      properties:
        network:
          type: string
          description: Blockchain network (e.g. ethereum, bitcoin)
        transaction_id:
          type: string
          description: Blockchain transaction hash
        status:
          type: string
          enum:
          - PENDING
          - CONFIRMED
        value:
          type: object
          properties:
            local:
              $ref: '#/components/schemas/Money'
            crypto:
              $ref: '#/components/schemas/Money'
        block:
          type: object
          properties:
            height:
              type: integer
            hash:
              type: string
            confirmations_accumulated:
              type: integer
            confirmations_required:
              type: integer
    Charge:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique charge identifier
        code:
          type: string
          description: Short 8-character alphanumeric charge code
          example: WZNDTFQK
        name:
          type: string
        description:
          type: string
        local_price:
          $ref: '#/components/schemas/Money'
        pricing_type:
          $ref: '#/components/schemas/PricingType'
        pricing:
          type: object
          description: Crypto pricing in supported currencies (populated after creation)
          additionalProperties:
            $ref: '#/components/schemas/Money'
        addresses:
          type: object
          description: Blockchain payment addresses keyed by crypto currency
          additionalProperties:
            type: string
        status:
          $ref: '#/components/schemas/ChargeStatus'
        redirect_url:
          type: string
          format: uri
        cancel_url:
          type: string
          format: uri
        metadata:
          type: object
          additionalProperties:
            type: string
        hosted_url:
          type: string
          format: uri
          description: URL to the hosted payment page
        timeline:
          type: array
          description: Status history events for the charge
          items:
            $ref: '#/components/schemas/TimelineEntry'
        payments:
          type: array
          description: Payment attempts associated with the charge
          items:
            $ref: '#/components/schemas/Payment'
        expires_at:
          type: string
          format: date-time
          description: When the charge expires (UTC, RFC 3339)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    ChargeCodeOrId:
      name: charge_code_or_id
      in: path
      required: true
      description: The charge ID (UUID) or charge code (8-character alphanumeric)
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-CC-Api-Key