Overview

Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. PlanOmatic does not process this field; it only stores and returns it in relevant API calls. Metadata entries written by an application are not visible to other applications.

❗️
Warning
Do not use metadata to store any sensitive information (such as personally identifiable information and card details). Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. PlanOmatic does not process this field.

How Metadata Works

Metadata is represented as a map of string keys to string values, in a field named metadata. Metadata can be written at the object level or nested datatype level.

Metadata characteristics:

Keys passed in metadata must be 60 characters or less and be in the character set [a-zA-Z0-9_-] . These keys are prefixed with a namespace, separated from the key with a : character.
Values have a maximum length of 255 characters.
An application can have up to 4 entries per metadata field.
Entries written by applications are private and can only be read or modified by the same application.

Currently, you can read and write metadata with objects under the Orders API:

Example metadata
The following example Order object has metadata definitions at both the order level and fulfillment level:

// Simplified Create Order Request Body
{
  api_key: 'y0Ur-AP1-k3y',
  external_property_id: '{property_id}',
  billing_entity_slug: 'investment_entity_1',
  metadata: {
    metadata_key1: 'abc123',
    metadata_key2: 'wxyz987'
  }
}