Skip to main content
Most Payouts API resources accept a metadata object: free-form string key/value pairs that Melio stores and returns verbatim but never interprets. Use it to stash your own context on a resource, such as an invoice number, a CRM id, or a ledger reference, so you can correlate Melio resources with records in your own system.

​
Setting metadata

Send a metadata object when you create (or update) a resource. Both keys and values must be strings.
The same metadata object is returned on the resource in every response, exactly as you sent it.

​
Limits

Metadata values must be strings. If you need to store a number, boolean, or nested object, serialize it to a string on your side (for example, JSON) before sending it, and parse it back when you read it.

​
Filtering by metadata

Metadata is filterable on list endpoints using the metadata[<key>]=<value> query syntax. A resource matches when its metadata contains every supplied key/value pair (the pairs combine with AND).

​
Metadata in webhooks

When a resource that carries metadata is affected by an event, its metadata is included on the webhook delivery. This lets you correlate an event with your own records without a follow-up GET.

​
Metadata vs. external IDs

Metadata is unstructured context that Melio never interprets and does not enforce uniqueness on. When you need a single, unique identifier that you can look a resource up by, use an external ID instead. The two are complementary: an externalId names the resource, metadata annotates it.