curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/disbursements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  }
}
'

{
  "disbursementId": "disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "status": "pending",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  },
  "createdAt": "2026-04-17T17:00:00.000Z",
  "updatedAt": "2026-04-17T17:00:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid disbursement parameters."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

Disbursements

Create a disbursement

Creates a merchant-initiated payment of funds from a CDP account owned by the merchant to a Coinbase user account or onchain address. Used for standalone refunds, goodwill disbursements, rebates, and other merchant-driven payouts that are not tied to a specific payment session.

This is an asynchronous operation. The disbursement is returned in pending status and transitions to succeeded (with associated onchainTransactions) or failed (with error).

POST

disbursements

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/disbursements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  }
}
'

{
  "disbursementId": "disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "status": "pending",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  },
  "createdAt": "2026-04-17T17:00:00.000Z",
  "updatedAt": "2026-04-17T17:00:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid disbursement parameters."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Headers

X-Idempotency-Key

string

An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.

Required string length: 1 - 128

Body

application/json

A request to create a disbursement.

source

Account · object

required

The source from which to fund the disbursement.

Show child attributes

Example:

{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}

target

Disbursement Coinbase Target · object

required

The target receiving the disbursement.

Disbursement Coinbase Target
Disbursement Wallet Target

Show child attributes

Example:

{ "coinbaseUserId": "coinbase_user_abc123" }

amount

string

required

A decimal representation of the amount to disburse, denominated in asset.

Example:

"25.00"

asset

string

required

The symbol of the asset for the disbursement amount.

Required string length: 1 - 42

Example:

"usdc"

reason

string

Human-readable reason for the disbursement.

Example:

"Goodwill disbursement for delayed shipment."

externalReferenceId

string

A merchant-provided internal identifier for this disbursement, from the merchant's own system—not visible to the payer. It must not contain personally identifiable information (PII) or payment credentials.

Maximum string length: 256

Example:

"disbursement-2026-04-1234"

customerDisplay

Operation Customer Display · object

Optional customer-facing display data for this disbursement, shown to the payer. If referenceCode is omitted, one is auto-generated — disbursements have no payment session to fall back to, unlike every other action type.

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

metadata

object

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

compliance

object

Compliance context for this disbursement. Carries recipient information required by some entity configurations to meet regulatory requirements.

Show child attributes

Example:

{
  "requesterIpAddress": "203.0.113.42",
  "recipient": {
    "name": "Jane Smith",
    "address": {
      "line1": "456 Oak Ave",
      "city": "Austin",
      "state": "TX",
      "postCode": "78701",
      "countryCode": "US"
    }
  }
}

Response

Successfully created disbursement.

A Disbursement represents a merchant-initiated payment of funds from a CDP account they own to a Coinbase account or onchain address. Used for standalone refunds, goodwill disbursements, rebates, and other merchant-driven payouts that are not tied to a specific payment session.

Disbursements are asynchronous: the resource is returned in pending status and transitions to succeeded (with associated onchainTransactions) or failed (with error).

disbursementId

string

required

The unique identifier of the disbursement.

Pattern: ^disbursement_[a-f0-9\-]{36}$

Example:

"disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

source

Account · object

required

The source from which the disbursement is funded.

Show child attributes

Example:

{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}

target

Disbursement Coinbase Target · object

required

The target receiving the disbursement.

Disbursement Coinbase Target
Disbursement Wallet Target

Show child attributes

Example:

{ "coinbaseUserId": "coinbase_user_abc123" }

amount

string

required

A decimal representation of the disbursed amount, denominated in asset.

Example:

"25.00"

asset

string

required

The symbol of the asset for the disbursement amount.

Required string length: 1 - 42

Example:

"usdc"

status

enum<string>

required

The current status of the disbursement.

Available options:

pending,

succeeded,

failed

Example:

"pending"

createdAt

string<date-time>

required

The UTC ISO 8601 timestamp at which the disbursement was created.

Example:

"2026-04-17T17:00:00.000Z"

updatedAt

string<date-time>

required

The UTC ISO 8601 timestamp at which the disbursement was last updated.

Example:

"2026-04-17T17:00:00.000Z"

reason

string

Human-readable reason for the disbursement.

Example:

"Goodwill disbursement for delayed shipment."

externalReferenceId

string

Maximum string length: 256

Example:

"disbursement-2026-04-1234"

customerDisplay

Operation Customer Display · object

Customer-facing display data for this disbursement, shown to the payer. Always present: if the create request omits referenceCode, one is auto-generated, since disbursements have no payment session to fall back to.

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

metadata

object

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

error

object

Error details, present only when the disbursement failed.

Show child attributes

Example:

{
  "code": "insufficient_funds",
  "message": "The source account does not have sufficient funds.",
  "occurredAt": "2026-04-17T17:01:00.000Z"
}

onchainTransactions

object[]

The onchain transactions associated with this disbursement.

Show child attributes

Example:

[
  {
    "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
    "network": "base"
  }
]