Skip to main content
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:

​
Constraints and limitations

PropertyConstraint
Maximum key-value pairs10 per resource
Maximum key length40 characters
Maximum value length500 characters
TypeStrings only (both keys and values)
ImmutableYes — cannot be updated or deleted after creation
Searchable / filterableNo
Included in webhook event payloadsNo
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.