Accounts5

Customers6

Deposit Destinations3

Disbursements3

End User Account Management9

End User Accounts26

EVM Accounts15

EVM Smart Accounts12

EVM Swaps2

EVM Token Balances1

Faucets2

Mandates12

Onchain Data2

Onramp7

Payment Methods2

Payment Sessions21

Policy Engine5

Solana Accounts11

Solana Token Balances1

SQL API3

Transfers5

Webhooks6

x402 Facilitator10

Webhooks

Customers2

Disbursements3

Health5

Mandates8

Onchain Data3

Onramp8

Payment Sessions14

Transfers7

Wallet Webhooks12

Disbursements

Create a disbursement

Changed on Oct 6, 2026

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/v2/disbursements

Request

Base URL: https://api.cdp.coinbase.com/platform
URL: https://api.cdp.coinbase.com/platform/v2/disbursements
Auth: HTTP bearer

Headers

X-Idempotency-Keystring

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.

Request body

amountstring required

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

assetstring required

The symbol of the asset (e.g., eth, usd, usdc, usdt).

reasonstring

Human-readable reason for the disbursement.

externalReferenceIdstring

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.

metadataMetadata

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 request

{
  "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",
  "compliance": {
    "recipient": {
      "name": "Jane Smith",
      "address": {
        "line1": "456 Oak Ave",
        "city": "Austin",
        "state": "TX",
        "postCode": "78701",
        "countryCode": "US"
      }
    }
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  }
}

Response

Successfully created disbursement.

disbursementIdstring required

The ID of the disbursement, a UUID prefixed by disbursement_.

amountstring required

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

assetstring required

The symbol of the asset (e.g., eth, usd, usdc, usdt).

status'pending' | 'succeeded' | 'failed' required

The current status of a payment action (authorization, capture, void, or refund).

reasonstring

Human-readable reason for the disbursement.

externalReferenceIdstring

metadataMetadata

createdAtstring date-time required

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

updatedAtstring date-time required

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

Example response

{
  "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"
}

Changes

Oct 6, 2026156440e9f8df Revision changes
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new solana enum value to the ////// response property for the response status
- warning
  added the new solana-devnet enum value to the ////// response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
Sep 25, 2026229ed860a74b Revision changes
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status

Operation history (5 revisions)