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

# Metadata

> Learn how to store arbitrary custom metadata in various objects in Tesouro.

## Overview

[Payables](/finops/support/glossary#payable), [Receivables](/finops/guides/accounts-receivable/index), [Organization](/finops/guides/organizations/index), [Counterpart](/finops/guides/common/counterparts/index), and [Counterpart bank account](/finops/guides/common/counterparts/bank-accounts) objects can have arbitrary metadata associated with them. Tesouro API Partners can use metadata to store additional structured information about these objects, such as the object IDs from other systems.
Receivables' metadata can also be [used in emails](#email-templates).

The way to work with metadata varies depending on the object type. Refer to the corresponding section below:

* [Organization and counterpart metadata](#organization-and-counterpart-metadata)
* [Payables, receivables, and counterpart bank account metadata](#payables-receivables-and-counterpart-bank-account-metadata)

## Organization and counterpart metadata

The metadata is not part of the `Organization` and `Counterpart` objects themselves. Instead, it is accessed via the `/partner-metadata` subresource of the corresponding resources:

```lines theme={null}
/entities/{entity_id}/partner-metadata

/counterparts/{counterpart_id}/partner-metadata
```

Use the HTTP PUT method to set the metadata, and GET to read it.

### Metadata format

The `<resource>/partner-metadata` endpoint accepts and returns the metadata in the following format, where `metadata` can be an arbitrary JSON object **up to 2000 bytes** in size:

```json lines theme={null}
{
  "metadata": {

    // Metadata goes here
    "custom_field_1": "value",
    "custom_field_2": 42,
    "custom_field_3": true,
    ...

  }
}
```

### Set metadata

Use `PUT <resource>/partner-metadata` to add metadata or replace existing metadata for a specific organization or counterpart. For example:

```sh lines theme={null}
curl -X PUT 'https://api.sandbox.tesouro.com/v1/counterparts/3a9c5...8df/partner-metadata' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "metadata": {
         "external_id": "id_6c8f1262fdbc",
         "comment": ""
       }
     }'
```

A `200 OK` response means the metadata was successfully saved. If the metadata exceeds the 2 KB limit, a `422` response is returned.

### Get metadata

Use `GET <resource>/partner-metadata` to get existing metadata for a specific organization or counterpart. For example:

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/counterparts/3a9c5...8df/partner-metadata' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: ACCESS_TOKEN'
```

If there is no metadata associated with the specified organization or counterpart, the `metadata` field in the response is an empty object `{}`.

### Partially update metadata

If you need to add, modify, or delete individual fields within a metadata object, you can use this approach:

1. Call `GET <resource>/partner-metadata` to read existing metadata.
2. Modify the returned object as needed.
3. Call `PUT <resource>/partner-metadata` to save the modified metadata.

### Delete metadata

To delete the metadata associated with a specific organization or counterpart, you can call `PUT <resource>/partner-metadata` and pass an empty object `{}` as the `metadata` value:

```sh lines theme={null}
curl -X PUT 'https://api.sandbox.tesouro.com/v1/counterparts/3a9c5...8df/partner-metadata' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"metadata": {}}'
```

## Payables, receivables, and counterpart bank account metadata

### Metadata format

`Payable`, `Receivable`, and `Counterpart Bank Account` objects have the `partner_metadata` field to store partner-provided metadata. The value can be an arbitrary JSON object **up to 2000 bytes** in size:

```json Example: Payable object metadata lines theme={null}
{
  "currency": "USD",
  ...

  "partner_metadata": {
    "custom_field_1": "value",
    "custom_field_2": 42,
    "custom_field_3": true,
    ...
  }
}
```

If there is no metadata associated with a specific payable, receivable, or bank account, the `partner_metadata` field returns an empty object—`{}`.

### Set metadata

When creating a payable, receivable, or counterpart bank account, you can provide the metadata by using the `partner_metadata` field directly in the request object as shown:

```sh Example: Set metadata for a payable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payables' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "currency": "USD",
       "amount": 11900,
       ...
       "partner_metadata": {
         "external_id": "id_6c8f1262fdbc",
         "comment": ""
       }
     }'
```

In case of already existing payables, receivables, or counterpart bank accounts, you can add metadata by sending a `PATCH` request to the respective endpoint and including the `partner_metadata` field as shown:

```sh Example: Update metadata of a payable lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/payables/aa314...5c0' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "partner_metadata": {
         "external_id": "id_6c8f1262fdbc",
         "comment": ""
       }
     }'
```

### Get metadata

To retrieve the metadata of a payable, receivable, or counterpart bank account, send a `GET` request to the corresponding resource.

The following snippet demonstrates a response from the [`GET /payables`](/finops/reference/openapi/payables/get-payables) request, which includes the `partner_metadata` of each payable:

```json expandable lines theme={null}
{
  "data": [
    {
      "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
      ...
      "partner_metadata": {
        "external_id": "id_6c8f1262fdbc",
        "comment": ""
      }
    },
    {
      "id": "f6d57e58-5703-47d4-80c0-2aa2ba0b36c4",
      ...
      "partner_metadata": {}
    },
    ...
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}
```

### Partially update metadata

To add, modify, or delete individual fields within the metadata of a `Payable`, `Receivable`, or `Counterpart Bank Account` object, you can use this approach:

1. Retrieve the object by using the corresponding `GET` request (such as `GET /payables/{payable_id}`).
2. Extract the `partner_metadata` response field to get existing metadata.
3. Modify the `partner_metadata` value as needed.
4. Send a `PATCH` request to update the object and provide the updated `partner_metadata` value in the request.

### Delete metadata

To delete existing metadata from a `Payable`, `Receivable` or `Counterpart Bank Account` object, send a `PATCH` request to the corresponding endpoint and set `partner_metadata` to an empty object `{}` as shown:

```sh Example: Delete a payable's metadata lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/payables/aa314...5c0' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "partner_metadata": {} }'
```

### Use metadata in email templates

<Note>
  This feature is supported only for [receivables](/finops/guides/accounts-receivable/index): invoices, quotes,
  and credit notes.
</Note>

Most keys defined in a receivable's `partner_metadata` are automatically exposed as [variables](/finops/guides/advanced/variables) for use in emails and [email templates](/finops/guides/advanced/email-templates/index).
These variable names are in the format

```lines theme={null}
{{partner_medatata.<key>}}
```

where `<key>` is the name of a field inside `partner_metadata`.

Only top-level metadata keys with primitive values (strings, numbers, booleans) are exposed as email template variables.
Nested keys and keys with array or object values are not exposed as variables.

Since metadata keys can vary per receivable, the `{{partner_metadata.<key>}}` variables are evaluated at the moment when emails are composed to be sent.
Variable names that refer to non-existing metadata keys do not raise errors but evaluate to an empty string.

#### Example

Consider an invoice with the following metadata:

```json lines theme={null}
"partner_metadata": {
  "dashboard_link": "https://myapp.example.com/invoices/123",
  "reference": "deal-ref",
  "priority": 3,
  "is_vip": true,

  "extra": {
    "key": "value"
  },
  "labels": ["marketing", "contract"]
}
```

You can use the following additional variables in email templates:

* `{{partner_metadata.dashboard_link}}`
* `{{partner_metadata.reference}}`
* `{{partner_metadata.priority}}`
* `{{partner_metadata.is_vip}}`

The `extra` and `labels` metadata keys are not exposed as variables because they are not primitives.

The following example includes `{{partner_metadata.dashboard_link}}` in the email body contents:

```json POST /mail-templates lines theme={null}
{
  "type": "receivables_invoice",
  "name": "New invoice template",
  "language": "en",
  "is_default": true,

  "subject_template": "Invoice {{invoice_number}} from {{entity_name}}",
  "body_template": "<!DOCTYPE html><html lang=\"en\"><body>... <a href=\"{{partner_metadata.dashboard_link}}\" target=\"_blank\">View invoice</a> ...</body></html>"
}
```

## See also

* [Tags](/finops/guides/common/tags) - add user-defined tags (labels) to various resources to categorize them.
* [Projects](/finops/guides/common/projects) - group related documents into projects.