Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Build Basics

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 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. Square does not process this field.

How metadata works Permalink Get a link to this section

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 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:

Example metadata Permalink Get a link to this section

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

{
  "order": {
    "id": "order-id",
    "name": "Test Order",
    "merchant_id": "Merchant 1",
    "location_id": "Location 1",
    "version": "1", 
    "fulfillments": [
      {
        "uid": "fulfillment-uid"
        "type": "PICKUP",
        "state": "PROPOSED",
        "metadata": 
          { 
            "my-reference-id": "ABC1234"
          }
      }
    ],
    "metadata": 
      {
"recurring_date": "20180213"
      }
  }
}