Applies to: Orders API
Learn about using metadata to store application logic-supporting strings in an order.
Metadata fields store strings that support application logic, such as references to resources outside of Square or brief information about an order. Developers can fill these fields with any string values their application needs. Square doesn't process this field; it just stores and returns it in API calls. Metadata entries from one 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). Square doesn't validate metadata contents to ensure that your application is following these important guidelines.
Metadata is a map of string keys to string values in a property named metadata. Metadata can be written at the Order level or order sub-type level.
Metadata has the following restrictions:
- Keys - Keys written by applications must be 60 characters or less and must be in the following character set: a-z, A-Z, 0-9, _ or -. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a
:character. - Value length - Values have a maximum length of 255 characters.
- Metadata map length - An application can map up to 10 entries per metadata field.
- Privacy - Entries written by applications are private and can only be read or modified by the same application.
You can read and write metadata to these Order API types:
The following example Order object has metadata mapped in its fulfillments (line 90) and the order itself (line 166):
{
"order": {
"id": "aOqBokk0BGMIenv2FLxf81rPCQ6YY",
"location_id": "E78VDDVFW1EYX",
"line_items": [
{
"uid": "pPE0m2p0KHAjnBjMRqKTJB",
"catalog_object_id": "32VNHUXOSP4UIRS3DV5TAIAY",
"catalog_version": 1738622146579,
"quantity": "1",
"name": "One-off coffee mug",
"variation_name": "Coffee cup - brown",
"base_price_money": {
"amount": 100,
"currency": "USD"
},
"gross_sales_money": {
"amount": 100,
"currency": "USD"
},
"total_tax_money": {
"amount": 9,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 109,
"currency": "USD"
},
"variation_total_price_money": {
"amount": 100,
"currency": "USD"
},
"applied_taxes": [
{
"uid": "7d8b3f81-f94e-4e48-a0f6-bbdadba68b04",
"tax_uid": "0f8e9c2c-a39b-4b7e-8d70-7f3ebacf8d42",
"applied_money": {
"amount": 9,
"currency": "USD"
}
}
],
"item_type": "ITEM",
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
}
}
],
"taxes": [
{
"uid": "0f8e9c2c-a39b-4b7e-8d70-7f3ebacf8d42",
"catalog_object_id": "UCQQDWUYMYIZD3NZZBG7GLQK",
"catalog_version": 1649720625765,
"name": "Washington",
"percentage": "8.9",
"type": "ADDITIVE",
"applied_money": {
"amount": 9,
"currency": "USD"
},
"scope": "LINE_ITEM",
"auto_applied": true
}
],
"discounts": [
{
"uid": "ARy34sogRd1AmuBZiUg2G",
"catalog_object_id": "YPQO34UERK4BGC7P7WXEL7ZX",
"catalog_version": 1738713513765,
"name": "Weekday Coffee Discount",
"percentage": "5.0",
"applied_money": {
"amount": 0,
"currency": "USD"
},
"type": "FIXED_PERCENTAGE",
"scope": "LINE_ITEM"
}
],
"fulfillments": [
{
"uid": "KbGTRwmKLFPb8v1DYhNNzC",
"type": "PICKUP",
"state": "PROPOSED",
"metadata": {
"external-PO": "ABC1234",
"courier-identity": "John Q Public"
},
"pickup_details": {
"pickup_at": "2023-11-30T01:01:05.000Z",
"note": "Just a little cream please",
"schedule_type": "ASAP",
"recipient": {
"display_name": "A. CoffeeDrinker",
"email_address": "recipient email address",
"phone_number": "1 (234) 567 8900"
},
"pickup_window_duration": "P1W3D",
"prep_time_duration": "P1W3D"
}
}
],
"created_at": "2025-02-04T23:14:33.159Z",
"updated_at": "2025-02-04T23:58:58.698Z",
"state": "OPEN",
"version": 3,
"total_tax_money": {
"amount": 9,
"currency": "USD"
},
"total_discount_money": {
"amount": 0,
"currency": "USD"
},
"total_tip_money": {
"amount": 0,
"currency": "USD"
},
"total_money": {
"amount": 109,
"currency": "USD"
},
"total_service_charge_money": {
"amount": 0,
"currency": "USD"
},
"net_amounts": {
"total_money": {
"amount": 109,
"currency": "USD"
},
"tax_money": {
"amount": 9,
"currency": "USD"
},
"discount_money": {
"amount": 0,
"currency": "USD"
},
"tip_money": {
"amount": 0,
"currency": "USD"
},
"service_charge_money": {
"amount": 0,
"currency": "USD"
}
},
"source": {
"name": "app for marketplace"
},
"customer_id": "KZSXNTC1TD14MH7H13MQ07TF4C",
"pricing_options": {
"auto_apply_discounts": true,
"auto_apply_taxes": true
},
"net_amount_due_money": {
"amount": 109,
"currency": "USD"
},
"metadata": {
"recurring_date": "20180213",
"house_account": "123-56-A"
}
}
}Important
When any application updates metadata on an order, the Order.version number is incremented. If another application changes its metadata on that order, your application will see the higher version number but not the new metadata values. To your application, the order looks the same except for the higher version number.