CBCommerceClient: Crypto Payments, Charges & Checkouts

CBCommerceClient is the REST client for Coinbase Commerce — Coinbase’s payment processing platform. Use it to accept crypto payments by generating payment charges, building hosted checkout pages, and querying payment event history for webhook reconciliation.

Coinbase Commerce uses a Commerce-specific API key — separate from the CDP API keys used by the trading clients. Commerce keys are created from the Coinbase Commerce dashboard, not from the standard API Key Management page.

Installation

npm install coinbase-api

Instantiation

TypeScript
JavaScript

import { CBCommerceClient } from 'coinbase-api';

const client = new CBCommerceClient({
  apiKey: 'your_commerce_api_key',
});

const { CBCommerceClient } = require('coinbase-api');

const client = new CBCommerceClient({
  apiKey: 'your_commerce_api_key',
});

There is no sandbox environment for Coinbase Commerce. All API calls are live.

Charges

A charge represents a single payment request for a specific amount. Once created, you redirect the buyer to Coinbase’s hosted payment page or use the charge details to build your own payment UI.

Method	Description
`createCharge(params)`	Create a new payment charge
`getAllCharges()`	List all charges
`getCharge(params)`	Get a charge by code or ID

Create a Charge

TypeScript
JavaScript

const charge = await client.createCharge({
  // Required: exact price
  local_price: {
    amount: '10.00',
    currency: 'USD',
  },
  // 'fixed_price' for a set amount, 'no_price' for open donations
  pricing_type: 'fixed_price',

  // Optional metadata and redirect URLs
  metadata: {
    custom_field: 'order-12345',
    custom_field_two: 'user-abc',
  },
  redirect_url: 'https://example.com/payment/success',
  cancel_url: 'https://example.com/payment/cancel',
});

console.log('Hosted payment URL:', charge.data.hosted_url);
console.log('Charge code:', charge.data.code);

const charge = await client.createCharge({
  local_price: {
    amount: '10.00',
    currency: 'USD',
  },
  pricing_type: 'fixed_price',
  metadata: {
    custom_field: 'order-12345',
  },
  redirect_url: 'https://example.com/payment/success',
  cancel_url: 'https://example.com/payment/cancel',
});

console.log('Hosted payment URL:', charge.data.hosted_url);

List & Retrieve Charges

// All charges
const charges = await client.getAllCharges();

// A specific charge by its order code or UUID
const charge = await client.getCharge({
  charge_code_or_charge_id: 'CHARGE-CODE',
});

Checkouts

A checkout is a reusable payment page configuration. Unlike a charge (one-time use), a checkout can generate multiple charges over time — useful for recurring payment buttons or product pages.

Method	Description
`createCheckout(params)`	Create a reusable checkout session
`getAllCheckouts()`	List all checkouts
`getCheckout(params)`	Get a specific checkout by ID

Create a Checkout

TypeScript
JavaScript

const checkout = await client.createCheckout({
  // Required: price configuration
  total_price: {
    amount: '49.99',
    currency: 'USD',
  },
  pricing_type: 'fixed_price',

  // Optional: collect information from the buyer
  requested_info: ['name', 'email'],

  metadata: {
    custom_field: 'premium-plan',
  },
});

console.log('Checkout ID:', checkout.data.id);

const checkout = await client.createCheckout({
  total_price: {
    amount: '49.99',
    currency: 'USD',
  },
  pricing_type: 'fixed_price',
  requested_info: ['name', 'email'],
});

console.log('Checkout ID:', checkout.data.id);

List & Retrieve Checkouts

// All checkouts
const checkouts = await client.getAllCheckouts();

// A specific checkout
const checkout = await client.getCheckout({
  checkout_id: 'checkout-uuid',
});

Events

Coinbase Commerce fires webhook events as payment states change (e.g. charge:pending, charge:confirmed, charge:failed). The Events API lets you query these programmatically for reconciliation and debugging.

The listEvents and showEvent methods require a X-CC-Version header to be passed explicitly. Pass it as the first argument to both methods.

Method	Description
`listEvents(headers)`	List all events
`showEvent(params, headers)`	Get details for a specific event

const versionHeader = { 'X-CC-Version': '2018-03-22' };

// List all events
const events = await client.listEvents(versionHeader);

// Get a specific event (e.g. from a received webhook)
const event = await client.showEvent(
  { event_id: 'event-uuid' },
  versionHeader,
);

console.log('Event type:', event.data.type);
console.log('Event resource:', event.data.data);

Typical Payment Flow

Create a charge

Call createCharge() with the amount, currency, and pricing_type. Store the returned charge id and code in your database against your order.

Redirect the buyer

Send the buyer to charge.data.hosted_url for Coinbase’s hosted payment page, or use the raw charge data to render your own UI.

Receive webhooks

Coinbase Commerce will POST events to your webhook endpoint as the payment progresses through pending → confirmed → resolved (or expired / failed).

Verify via API

Use getCharge() or showEvent() to independently verify payment status without relying solely on the incoming webhook payload.

Pricing Types

`pricing_type`	Behaviour
`fixed_price`	Buyer pays the exact `local_price` amount
`no_price`	Open-ended (buyer chooses the amount — suitable for donations)

Get Started

REST Clients

WebSockets

Guides

CBCommerceClient: Crypto Payments, Charges & Checkouts

Installation

Instantiation

Charges

Create a Charge

List & Retrieve Charges

Checkouts

Create a Checkout

List & Retrieve Checkouts

Events

Typical Payment Flow

Pricing Types

Next Steps

Advanced Trade Client

Coinbase App Client

Build docs developers (and LLMs) love

Get Started

REST Clients

WebSockets

Guides

Documentation Index

​Installation

​Instantiation

​Charges

​Create a Charge

​List & Retrieve Charges

​Checkouts

​Create a Checkout

​List & Retrieve Checkouts

​Events

​Typical Payment Flow

​Pricing Types

​Next Steps

Advanced Trade Client

Coinbase App Client

Build docs developers (and LLMs) love

Installation

Instantiation

Charges

Create a Charge

List & Retrieve Charges

Checkouts

Create a Checkout

List & Retrieve Checkouts

Events

Typical Payment Flow

Pricing Types

Next Steps