Skip to main content

​
Overview

Migrate from Commerce Charge API to the Checkouts API for improved reliability, simplified integration, modern authentication, and additional capabilities including settlement details. This guide covers the key changes and provides code examples to help you update your integration.
Checkouts API requires a Coinbase Business account.
1

Update authentication

Switch from API key to JWT Bearer tokens
2

Change base URL

From api.commerce.coinbase.com to business.coinbase.com/api/v1/checkouts
3

Update request/response handling

New field names and flattened structure
4

Implement status monitoring

Use webhooks for real-time notifications or polling
5

Test thoroughly

New ID formats and status values require updates to your logic

​
Key differences

ComponentCharge API (Commerce)Checkouts API
Base URLhttps://api.commerce.coinbase.comhttps://business.coinbase.com/api/v1
AuthenticationX-CC-Api-Key headerBearer token with CDP API key
Primary resourceChargeCheckout
ID formatUUID24-character hexadecimal
Payment URL fieldhosted_urlurl
Settlement detailsNot availablesettlement object with fee breakdown
Checkouts API requires CDP API key authentication.

​
Status and field mappings

FeatureCharge APICheckouts API
Status valuesNEW, SIGNED, PENDING, COMPLETED, EXPIRED, FAILEDACTIVE, PROCESSING, COMPLETED, DEACTIVATED, EXPIRED, FAILED
Amount structurelocal_price.amount and local_price.currencyamount and currency (flat structure)
Network specificationAuto-selectedExplicit network field
Redirect URLsredirect_url, cancel_urlsuccessRedirectUrl, failRedirectUrl

​
Migration checklist

​
1. Update authentication

  • Create CDP API keys
  • Implement JWT Bearer token generation
  • Update API key storage and rotation procedures
  • Test authentication with Checkouts API

​
2. Update API integration

  • Update base URL to https://business.coinbase.com/api/v1/checkouts
  • Modify request bodies to match new schema
  • Update response parsing to handle new fields (address, settlement, transactionHash)
  • Implement idempotency key generation for create requests

​
3. Handle status changes

  • Map Charge statuses to Checkout statuses in your system
  • Update order fulfillment logic for new status values
  • Set up webhooks for real-time payment notifications (see Webhooks documentation)
  • Update customer-facing status messages

​
4. Update payment flows

  • Use url field instead of hosted_url for payment pages
  • Update redirect URL parameters
  • Test full payment flow end-to-end
  • Verify metadata is correctly passed through

​
5. Handle pagination

  • Update list operations to use pageSize and pageToken
  • Implement nextPageToken handling for multiple pages
  • Test pagination with large datasets

​
6. Test and validate

  • Consider testing your integration with the sandbox environment
  • Verify amount calculations (ensure proper decimal handling)
  • Test expired checkout scenarios
  • Test deactivation flow
  • Verify metadata preservation
  • Test redirect URLs

​
7. Monitor and observe

  • Set up monitoring for API errors
  • Track payment success rates
  • Monitor checkout expiration rates
  • Set up alerts for failed payments
  • API & Schema Mapping - Detailed endpoint and response comparisons with code examples
  • FAQ - Common questions and troubleshooting