Skip to main content

​
Overview

Payables, Receivables, Entity, Counterpart, and Counterpart bank account objects can have arbitrary metadata associated with them. Monite 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. The way to work with metadata varies depending on the object type. Refer to the corresponding section below:

​
Entity and counterpart metadata

The metadata is not part of the Entity and Counterpart objects themselves. Instead, it is accessed via the /partner_metadata subresource of the corresponding resources: 
/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: 
{
  "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 entity or counterpart. For example: 
curl -X PUT 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/partner_metadata' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'X-Monite-Entity-Id: ENTITY_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 entity or counterpart. For example: 
curl -X GET 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/partner_metadata' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: ACCESS_TOKEN'
If there is no metadata associated with the specified entity 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 entity or counterpart, you can call PUT <resource>/partner_metadata and pass an empty object {} as the metadata value: 
curl -X PUT 'https://api.sandbox.monite.com/v1/counterparts/3a9c5...8df/partner_metadata' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'X-Monite-Entity-Id: ENTITY_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:
Example: Payable object metadata
{
  "currency": "EUR",
  ...

  "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:
Example: Set metadata for a payable
curl -X POST 'https://api.sandbox.monite.com/v1/payables' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "currency": "EUR",
       "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:
Example: Update metadata of a payable
curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/aa314...5c0' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'X-Monite-Entity-Id: ENTITY_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 request, which includes the partner_metadata of each payable: 
{
  "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:
Example: Delete a payable's metadata
curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/aa314...5c0' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "partner_metadata": {} }'

​
Use metadata in email templates

This feature is supported only for receivables: invoices, quotes, and credit notes.
Most keys defined in a receivable’s partner_metadata are automatically exposed as variables for use in emails and email templates. These variable names are in the format 
{{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: 
"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:
POST /mail_templates
{
  "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 - add user-defined tags (labels) to various resources to categorize them.
  • Projects - group related documents into projects.