Metadata

Many CDP Payments resources accept an optional metadata field — a flat map of string-to-string key-value pairs you can use to tie API objects back to records in your own system (invoice IDs, customer IDs, order numbers, internal references, and so on). The same metadata schema is used across:

Deposit destinations — track the purpose or source of inbound deposits
Transfers — tag outbound or internal movements with your own references
Webhook subscriptions — annotate subscriptions for routing or organization

Constraints and limitations

Property	Constraint
Maximum key-value pairs	10 per resource
Maximum key length	40 characters
Maximum value length	500 characters
Type	Strings only (both keys and values)
Immutable	Yes — cannot be updated or deleted after creation
Searchable / filterable	No
Included in webhook event payloads	No

Never store sensitive data like passwords, account numbers, or PII in metadata. Metadata is returned in API responses and may appear in logs.

Deposit destinations have a temporary additional restriction: metadata values must currently be in UUID format or integer string format. Free-form values are accepted on transfers and webhook subscriptions today and will be supported on deposit destinations in a future release.

Usage

Include the optional metadata field on the create request for the resource.

On a transfer

{
  "source": {
    "accountId": "account_123",
    "asset": "usd"
  },
  "target": {
    "email": "user@example.com",
    "asset": "usd"
  },
  "amount": "100.00",
  "asset": "usd",
  "execute": true,
  "metadata": {
    "invoiceId": "INV-001",
    "customerId": "cust_123"
  }
}

On a deposit destination

{
  "accountId": "account_123",
  "network": "base",
  "type": "crypto",
  "metadata": {
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "orderRef": "12345"
  }
}

On a webhook subscription

{
  "target": {
    "url": "https://api.example.com/webhooks/cdp"
  },
  "eventTypes": ["payments.transfers.completed"],
  "metadata": {
    "team": "payments-ops"
  }
}

## Retrieving metadata

Metadata is returned automatically on every read of the resource. No additional API calls are required.

```json highlight={4-7}
{
  "transferId": "transfer_123",
  "status": "completed",
  "metadata": {
    "invoiceId": "INV-001",
    "customerId": "cust_123"
  }
}

Metadata persists for the lifetime of the resource and is included in every subsequent response.

Best practices

Use consistent key names across resources (e.g., always invoiceId, never sometimes invoice_id) so you can correlate records across your own systems.
Store IDs, not full data. Reference your system’s records by ID rather than duplicating information into metadata.
Keep keys concise — they’re capped at 40 characters and count toward the 10-pair limit.
Plan for immutability. Treat metadata as write-once: if you need a mutable annotation, store it in your own database keyed by the resource ID.

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Constraints and limitations

Usage

On a transfer

On a deposit destination

On a webhook subscription

Best practices

​Constraints and limitations

​Usage

​On a transfer

​On a deposit destination

​On a webhook subscription

​Best practices

​Related endpoints

Constraints and limitations

Usage

On a transfer

On a deposit destination

On a webhook subscription

Best practices

Related endpoints