Coinbase Invoices API

openapi: 3.2.0
info:
  title: Coinbase Commerce Invoices API
  description: The Coinbase Commerce API enables merchants and developers to accept cryptocurrency payments globally. It supports creating charges, managing checkouts, handling invoices, and receiving webhook notifications for payment events. The API provides endpoints for creating payment requests, tracking payment status, and automating financial workflows for businesses accepting crypto as a payment method.
  version: '2.0'
  contact:
    name: Coinbase Commerce Support
    url: https://help.coinbase.com/en/commerce
  termsOfService: https://www.coinbase.com/legal/user-agreement
servers:
- url: https://api.commerce.coinbase.com
  description: Production Server
security:
- apiKeyAuth: []
tags:
- name: Invoices
  description: Create and manage invoices for billing customers with cryptocurrency payment options.
paths:
  /invoices:
    get:
      operationId: listInvoices
      summary: List invoices
      description: Retrieves a paginated list of all invoices. Invoices are used to bill customers with specific payment terms and due dates.
      tags:
      - Invoices
      parameters:
      - $ref: '#/components/parameters/PaginationParam'
      - $ref: '#/components/parameters/OrderParam'
      responses:
        '200':
          description: Successfully retrieved invoices
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      operationId: createInvoice
      summary: Create invoice
      description: Creates a new invoice for billing a customer. The invoice specifies payment terms, due date, and line items.
      tags:
      - Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceRequest'
      responses:
        '201':
          description: Invoice created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
        '400':
          description: Bad request
  /invoices/{invoice_id}:
    get:
      operationId: getInvoice
      summary: Get invoice
      description: Retrieves a specific invoice by its ID.
      tags:
      - Invoices
      parameters:
      - name: invoice_id
        in: path
        required: true
        description: Invoice identifier
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved invoice
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
        '404':
          description: Invoice not found
  /invoices/{invoice_id}/void:
    put:
      operationId: voidInvoice
      summary: Void invoice
      description: Voids an unpaid invoice. Once voided, the invoice can no longer accept payments.
      tags:
      - Invoices
      parameters:
      - name: invoice_id
        in: path
        required: true
        description: Invoice identifier
        schema:
          type: string
      responses:
        '200':
          description: Invoice voided
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
  /invoices/{invoice_id}/resolve:
    put:
      operationId: resolveInvoice
      summary: Resolve invoice
      description: Resolves an unresolved invoice that requires manual review.
      tags:
      - Invoices
      parameters:
      - name: invoice_id
        in: path
        required: true
        description: Invoice identifier
        schema:
          type: string
      responses:
        '200':
          description: Invoice resolved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
components:
  schemas:
    CreateInvoiceRequest:
      type: object
      description: Request body for creating a new invoice
      required:
      - business_name
      - customer_email
      - local_price
      properties:
        business_name:
          type: string
          description: Business name
        customer_name:
          type: string
          description: Customer name
        customer_email:
          type: string
          format: email
          description: Customer email address
        memo:
          type: string
          description: Invoice memo or notes
        local_price:
          type: object
          description: Invoice amount
          required:
          - amount
          - currency
          properties:
            amount:
              type: string
              description: Amount
            currency:
              type: string
              description: Currency code
    Pagination:
      type: object
      description: Pagination cursor information
      properties:
        order:
          type: string
          description: Sort order
        starting_after:
          type: string
          description: Cursor for next page
        ending_before:
          type: string
          description: Cursor for previous page
        total:
          type: integer
          description: Total number of results
        yielded:
          type: integer
          description: Number of results in this page
        cursor_range:
          type: array
          description: Range of cursors in this page
          items:
            type: string
    Invoice:
      type: object
      description: An invoice for billing customers
      properties:
        id:
          type: string
          description: Invoice identifier
        resource:
          type: string
          description: Resource type
          enum:
          - invoice
        code:
          type: string
          description: Invoice code
        status:
          type: string
          description: Invoice status
          enum:
          - OPEN
          - VIEWED
          - PAID
          - VOID
          - UNRESOLVED
        business_name:
          type: string
          description: Business name on the invoice
        customer_name:
          type: string
          description: Customer name
        customer_email:
          type: string
          format: email
          description: Customer email
        memo:
          type: string
          description: Invoice memo
        local_price:
          type: object
          description: Invoice amount
          properties:
            amount:
              type: string
              description: Amount
            currency:
              type: string
              description: Currency code
        hosted_url:
          type: string
          format: uri
          description: URL for the hosted invoice page
        created_at:
          type: string
          format: date-time
          description: When the invoice was created
  parameters:
    PaginationParam:
      name: starting_after
      in: query
      description: Cursor for pagination to fetch the next page of results
      schema:
        type: string
    OrderParam:
      name: order
      in: query
      description: Sort order for results
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-CC-Api-Key
      description: Coinbase Commerce API key for authentication. Include the key in the X-CC-Api-Key header.
externalDocs:
  description: Coinbase Commerce API Documentation
  url: https://commerce.coinbase.com/docs/api