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

The 500-key limit makes metadata usable for line-item style data: 500 keys holds roughly 250 two-field records (for example an invoice_number and a total_amount per record), flattened into distinct keys.
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.
The total-size limit is measured on the serialized JSON in bytes, not on character counts, so it can be reached well before the per-key limits are. Characters that JSON escapes (such as control characters, which become \u0001) cost six bytes each, and non-ASCII characters cost up to four. A request whose metadata exceeds 128 KB is rejected with 400, even when every key and value is individually within its limit.

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

Metadata is not included in webhook deliveries. Because a metadata object can be up to 128 KB, including it would risk pushing an event past the delivery size limit. To correlate an event with your own records, use the externalId on the delivery payload — it is always present when you set one, and needs no follow-up call. When you need the metadata itself, fetch the resource using the id from the payload:

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.