Migrate from Commerce Overview

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.

Migration summary

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

Component	Charge API (Commerce)	Checkouts API
Base URL	https://api.commerce.coinbase.com	https://business.coinbase.com/api/v1
Authentication	X-CC-Api-Key header	Bearer token with CDP API key
Primary resource	Charge	Checkout
ID format	UUID	24-character hexadecimal
Payment URL field	hosted_url	url
Settlement details	Not available	settlement object with fee breakdown

Checkouts API requires CDP API key authentication.

Status and field mappings

Feature	Charge API	Checkouts API
Status values	NEW, SIGNED, PENDING, COMPLETED, EXPIRED, FAILED	ACTIVE, PROCESSING, COMPLETED, DEACTIVATED, EXPIRED, FAILED
Amount structure	local_price.amount and local_price.currency	amount and currency (flat structure)
Network specification	Auto-selected	Explicit network field
Redirect URLs	redirect_url, cancel_url	successRedirectUrl, 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

What to read next

• API & Schema Mapping - Detailed endpoint and response comparisons with code examples
• FAQ - Common questions and troubleshooting