Metadata

Applies to: Orders API

Learn about using 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.

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:

• Order
• OrderFulfillment
• OrderLineItem
• OrderLineItemTax
• OrderLineItemDiscount
• OrderServiceCharge

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"
      }
  }
}