Skip to main content
POST
/
v2
/
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"
}

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.

Example:
{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}
​
target
Disbursement Coinbase Target · object
required

The target receiving the disbursement.

Example:
{ "coinbaseUserId": "coinbase_user_abc123" }
​
amount
string
required

A decimal representation of the amount to disbursement, 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

An arbitrary client-supplied identifier for the disbursement, such as a ticket ID or disbursement memo from the caller's own system. Not interpreted by CDP — stored and returned as-is.

Maximum string length: 256
Example:

"disbursement-2026-04-1234"

​
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.

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

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.

Example:
{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}
​
target
Disbursement Coinbase Target · object
required

The target receiving the disbursement.

Example:
{ "coinbaseUserId": "coinbase_user_abc123" }
​
amount
string
required

A decimal representation of the disbursemented 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

An arbitrary client-supplied identifier for the disbursement, such as a ticket ID or disbursement memo from the caller's own system. Not interpreted by CDP — stored and returned as-is.

Maximum string length: 256
Example:

"disbursement-2026-04-1234"

​
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.

Example:
{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}
​
error
object

Error details, present only when the disbursement failed.

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.

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