> ## Documentation Index
> Fetch the complete documentation index at: https://developers.staging01.melio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

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.

```bash theme={null}
curl https://api.example.com/v2/payments \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "USD",
    "metadata": {
      "invoiceId": "INV-42",
      "ledgerRef": "L-9"
    }
  }'
```

The same `metadata` object is returned on the resource in every response, exactly as you sent it.

## Limits

| Constraint     | Limit                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------- |
| Number of keys | Up to 50                                                                                        |
| Key length     | 1 to 40 characters                                                                              |
| Key characters | May not contain square brackets (`[` or `]`), which are reserved for the `metadata[key]` filter |
| Value type     | String                                                                                          |
| Value length   | Up to 100 characters                                                                            |

<Note>
  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.
</Note>

## 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).

```bash theme={null}
# Payments whose metadata contains BOTH invoiceId=INV-42 AND ledgerRef=L-9
curl "https://api.example.com/v2/payments?metadata[invoiceId]=INV-42&metadata[ledgerRef]=L-9" \
  -H "Authorization: Bearer <api-key>"
```

## Metadata in webhooks

When a resource that carries metadata is affected by an event, its metadata is included on the [webhook delivery](/docs/webhooks). 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](/docs/external-ids) instead. The two are complementary: an `externalId` names the resource, `metadata` annotates it.