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
  - name: Events
    description: Retrieve charge-related webhook events

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"

  /events:
    get:
      operationId: listEvents
      summary: List all events
      description: Returns a paginated list of charge-related webhook events.
      tags:
        - Events
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: starting_after
          in: query
          schema:
            type: string
        - name: ending_before
          in: query
          schema:
            type: string
      responses:
        "200":
          description: List of events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /events/{event_id}:
    get:
      operationId: getEvent
      summary: Retrieve an event
      description: Returns the details of a specific event.
      tags:
        - Events
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
          description: The event ID
      responses:
        "200":
          description: Event details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-CC-Api-Key

  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

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  schemas:
    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"

    ChargeStatus:
      type: string
      description: The current lifecycle status of the charge
      enum:
        - NEW
        - PENDING
        - COMPLETED
        - EXPIRED
        - UNRESOLVED
        - RESOLVED
        - CANCELED
        - CANCELATION_COMPLETE

    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.

    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

    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

    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

    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]

    Event:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          description: Event type
          enum:
            - charge:created
            - charge:pending
            - charge:confirmed
            - charge:failed
            - charge:delayed
            - charge:resolved
        api_version:
          type: string
          example: "2018-03-22"
        created_at:
          type: string
          format: date-time
        data:
          $ref: "#/components/schemas/Charge"

    EventResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Event"

    EventListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Event"

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error type identifier
            message:
              type: string
              description: Human-readable error description