Metadata

Use metadata to store additional information about Square API resources.

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

Warning

Don't 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. Square doesn't validate metadata contents to ensure that your application is following these important guidelines.

Link to section

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 include the following:

  • Keys written by applications must be 60 characters or less and must be in the character set [a-zA-Z0-9_-]. Entries can also include metadata generated by Square. 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 10 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:

Link to section

Example metadata

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