Custom fields, known as in Mercoa as Metadata, can be used to extend the functionality of the Mercoa platform.

Metadata can be used to store additional information about an invoice, such as a propertyId or projectId from your system, data about where how to process the invoice in downstream systems, etc.

Metadata is stored as a dictionary of key value pairs. The keys and values can be any string value.

For metadata to be exposed to the end user, you should create a metadata schema. This allows you to specify the type of each field, and provide a list of options for the user to choose from.

Setting and getting invoice metadata

Metadata is set and retrieved using the metadata property on the invoice object. This property is a dictionary of key value pairs. The keys and values can be any string value.

1
{
2
  "metadata": {
3
    "propertyId": "1234",
4
    "projectId": "5678"
5
  }
6
}

Invoice line items can also have metadata that is independent of the invoice metadata. This is useful if you want to store metadata about a specific line item, such as a propertyId or projectId for that line item.

1
{
2
  "lineItems": [
3
    {
4
      "description": "Line Item 1",
5
      "metadata": {
6
        "propertyId": "1234",
7
        "projectId": "5678"
8
      }
9
    }
10
  ]
11
}

Metadata can be set when creating an invoice, or updated on an existing invoice. Metadata is retrieved by getting the invoice.

Metadata Schemas

Most times, you will want the user to be able to provide metadata when they create an invoice. For example, you may want to allow the user to provide a propertyId when they create an invoice.

This is done by adding a custom field to the invoice creation form with a metadata schema.

Creating a metadata schema with the admin dashboard

Metadata schemas can be created in the developer dashboard.

1. Go to Developer Settings —> Customizations.

2. Go to Invoice Metadata and click Add Field

3. Add the field details and click Save

Creating a metadata schema with the API

You can use the update organization api to manage your metadata schema.

For each field in the schema, you can specify the following:

• key - The name of the field. This is used as the key in the metadata dictionary.
• displayName - The label to display to the user when they are entering the metadata.
• type - The type of the field. This can be STRING, NUMBER, BOOLEAN, DATE, KEY_VALUE.
• lineItem - Whether the field should be displayed on the invoice line item or the invoice header.
• allowMultiple - Whether the user should be able to enter multiple values for this field. This is only applicable for STRING and KEY_VALUE fields.
• showConditions - A list of conditions that determine whether the field should be displayed. See the API Reference for more details.

Setting metadata options for an entity

By default, the custom metadata fields will be free form fields. This makes sense for BOOLEAN or DATE fields, but for STRING or KEY_VALUE fields, you may want to provide a list of options for the user to choose from.

To do this, you can push data to specific keys in the metadata schema for each entity. For example, if you have a propertyId field of type STRING, you can push a list of property ids to the propertyId key in the metadata schema. This will cause the invoice creation form to display a dropdown with the list of property ids.

STRING Example

1
curl -X POST \
2
     --url "https://api.mercoa.com/entity/:entityId/metadata/propertyId" \
3
     --header "Content-Type: application/json" \
4
     --header "Authorization <token>" \
5
     --data '
6
[
7
  "prop_123",
8
  "prop_456"
9
]
10
'

This will let the user choose between prop_123 and prop_456 in a dropdown when they create an invoice.

KEY_VALUE Example

In the STRING example, the user has to choose between two ID values. If you want to provide more information about each ID, you can use the KEY_VALUE type. This type allows you to provide a list of key value pairs, where the key is the value that will be stored in the metadata, and the value is the label that will be displayed to the user.

1
curl -X POST \
2
     --url "https://api.mercoa.com/entity/:entityId/metadata/propertyId" \
3
     --header "Content-Type: application/json" \
4
     --header "Authorization <token>" \
5
     --data '
6
[
7
  "{'key': 'prop_123', 'value': 'Beach House'}",
8
  "{'key': 'prop_456', 'value': 'Mountain House'}",
9
]
10
'

This will let the user choose between Beach House and Mountain House in a dropdown when they create an invoice. When the user selects one of these options, the prop_123 or prop_456 value will be stored in the metadata.