Get a disbursement - Coinbase Developer Documentation

Get a disbursement

curl --request GET \
  --url https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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": "succeeded",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  },
  "onchainTransactions": [
    {
      "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "network": "base"
    }
  ],
  "createdAt": "2026-04-17T17:00:00.000Z",
  "updatedAt": "2026-04-17T17:05:00.000Z"
}

{
  "errorType": "not_found",
  "errorMessage": "Disbursement with the given ID does not exist."
}

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

GET

disbursements

{disbursementId}

Get a disbursement

curl --request GET \
  --url https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/disbursements/{disbursementId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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": "succeeded",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  },
  "onchainTransactions": [
    {
      "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "network": "base"
    }
  ],
  "createdAt": "2026-04-17T17:00:00.000Z",
  "updatedAt": "2026-04-17T17:05:00.000Z"
}

{
  "errorType": "not_found",
  "errorMessage": "Disbursement with the given ID does not exist."
}

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

Path Parameters

disbursementId

string

required

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

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

Example:

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

Response

Successfully retrieved 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

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

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

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

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