Learn how to create and manage custom attributes for Square orders using the Order Custom Attributes API.
Order Custom Attributes API

Custom Attributes for Orders

With custom attributes for orders, you can define your own properties and associate them with individual Order objects. For example, in a restaurant scenario, you can define fields such as Table Number, Seat Number, or Cover Count (how many people are seated at the table). When an order is ready, you can use the Order Custom Attributes API to match the order with the table that requested it.

The basic workflow for order custom attributes involves the following types of operations:

  1. Creating a custom attribute definition for Order objects.

  2. Setting a custom attribute for an order, according to the associated custom attribute definition.

  3. Retrieving one or more custom attributes from an order and performing other operations with those custom attributes.

To create a new custom attribute for orders, you must first define its properties. To do this, you call CreateOrderCustomAttributeDefinition.

The following example request defines a Cover Count custom attribute. The schema field indicates that the value of the custom attribute is a Number.

Create Order Custom Attribute Definition
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/orders/custom-attribute-definitions \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute_definition": {
      "key": "cover-count",
      "name": "Cover count",
      "description": "The number of people seated at a table",
      "schema": {
        "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
      },
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    },
    "idempotency_key": "IDEMPOTENCY_KEY"
  }'

The key identifier and visibility setting that you specify for the definition are also used by corresponding custom attributes. The visibility setting determines the access level that other applications (including the Customer Directory and other Square products) have to the definition and corresponding custom attributes.

After you create a custom attribute definition, you can set that custom attribute for any order.

The following example UpsertOrderCustomAttribute request sets the Cover Count custom attribute using the order_id and key. Note the following:

  • The key in the path is cover-count, which is the key specified by the definition.

  • The value in the request body sets the custom attribute value for the order. This value must conform to the Number data type specified by the schema field in the definition.

Upsert Order Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/orders/ORDER_ID/custom-attributes/cover-count \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "4"
    },
    "idempotency_key": "IDEMPOTENCY_KEY"
  }'

Note

Square also provides the BulkUpsertOrderCustomAttributes endpoint to update multiple custom attributes for an order in a single request.

You can now retrieve the custom attribute to retrieve the value that was set for the order.

The following example RetrieveOrderCustomAttribute request retrieves the Cover Count custom attribute for an order using the order_id and key:

Retrieve Order Custom Attribute
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/orders/ORDER_ID/custom-attributes/cover-count?with_definition=true \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The value field in the following example represents the custom attribute value:

You can include the with_definition query parameter to return the corresponding custom attribute definition in the same call. For example, you might want to retrieve the definition to retrieve the custom attribute's data type or name.

Note

Square also provides the ListOrderCustomAttributes endpoint to retrieve all the custom attributes associated with an order.

The Order Custom Attributes API supports the following operations:

The data type of a custom attribute is specified in the schema field of the custom attribute definition. For all data types except Selection, this field contains a simple URL reference to a schema object hosted on the Square CDN.

Order-related custom attributes support the following data types:

  • String

  • Email

  • PhoneNumber

  • Address

  • Date

  • Boolean

  • Number

  • Selection

For information about defining the data type for an order-related custom attribute, see Specifying the schema.

A CreateOrderCustomAttributeDefinition request is scoped to a specific seller. To make the custom attribute available to other sellers, you must call CreateOrderCustomAttributeDefinition on behalf of each seller. To do so when using OAuth, call this endpoint for each seller using their access token.

Note

To simplify management, you might want to keep all definitions that use the same key synchronized across seller accounts. Therefore, if you change a definition for one seller, you should consider making the same change for all other sellers.

The application that creates a custom attribute definition is the definition owner. The definition owner always has READ and WRITE permissions to the definition and to all instances of the corresponding custom attribute.

The visibility of a custom attribute definition determines how other applications that make calls on behalf of a seller can access the definition (and its corresponding custom attributes). This access control applies to third-party applications and Square products, such as the Customer Directory.

The following table shows the access permitted by each supported visibility setting:

Custom attribute definition Custom attribute
Visibility setting READ WRITE READ WRITE
VISIBILITY_HIDDEN (default) No No No No
VISIBILITY_READ_ONLY Yes No Yes No
VISIBILITY_READ_WRITE_VALUES Yes No Yes Yes

You can subscribe to receive notifications for order-related custom attribute events. Each event provides two options that allow you to choose when Square sends notifications:

  1. .owned event notifications are sent when changes are made to custom attribute definitions and custom attributes that are owned by your application. A custom attribute definition is owned by the application that created it. A custom attribute is owned by the application that created the corresponding custom attribute definition.

  2. .visible event notifications are sent when changes are made to custom attribute definitions and custom attributes that are visible to your application. These changes apply to:

    • All custom attribute definitions and custom attributes owned by your application.

    • All other custom attribute definitions or custom attributes whose visibility setting is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. This includes seller-defined custom attributes (also known as custom fields), which are always set to VISIBILITY_READ_WRITE_VALUES.

Notification payloads for both options contain the same information.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

Event
Permission
Description
order.custom_attribute_definition.owned.createdORDERS_READA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
orders.custom_attribute_definition.owned.updatedORDERS_READA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
orders.custom_attribute_definition.owned.deletedORDERS_READA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
orders.custom_attribute.owned.updatedORDERS_READA custom attribute owned by your application was created or updated for an order.
orders.custom_attribute.owned.deletedORDERS_READA custom attribute owned by your application was deleted from an order.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event
Permission
Description
order.custom_attribute_definition.visible.createdORDERS_READA custom attribute definition that is visible to your application was created.
order.custom_attribute_definition.visible.updatedORDERS_READA custom attribute definition that is visible to your application was updated.
order.custom_attribute_definition.visible.deletedORDERS_READA custom attribute definition that is visible to your application was deleted.
order.custom_attribute.visible.updatedORDERS_READA custom attribute that is visible to your application was created or updated for an order.
order.custom_attribute.visible.deletedORDERS_READA custom attribute that is visible to your application was deleted from an order.

Note

Upserting or deleting a custom attribute for an order does not invoke an order.updated webhook.

The following is an example order.custom_attribute_definition.visible.created notification:

The following is an example order.custom_attribute.visible.updated notification:

Note the following:

  • The ORDERS_READ permission is required to receive notifications about order-related custom attribute events.

  • The key of the custom attribute definition or custom attribute in the notification is always the qualified key

    The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{key}
    .

  • If you subscribe to the .owned and .visible options for the same event, Square sends both notifications for changes to custom attribute definitions and custom attributes owned by the subscribing application.

  • The value of the data.id in the notification depends on the affected object:

    • For custom attribute definition events, data.id is the qualified key.

    • For custom attribute events, data.id is generated using the qualified key and the ID of the affected order. This data.id cannot be used directly with the Order Custom Attributes API.

For more information about custom attribute webhooks, see Subscribing to webhooks. For more information about how to subscribe to events and validate notifications, see Square Webhooks Overview.

The following requirements, limitations, and other considerations apply when working with custom attributes for orders:

  • Minimum Square version. Square version 2022-11-16 or later is required to work with the Order Custom Attributes API.

  • Sensitive data. Custom attributes are intended to store additional information or store associations with an entity in another system. Do not use custom attributes to store any PCI data, such as credit card details. PII is supported in custom attribute values, but applications that create or read this data should observe applicable privacy laws and data regulations such as requesting the hard deletion of custom attribute data when a GDPR request for erasure is received. Never store secret-level information in a custom attribute. The use of custom attributes is subject to developers adhering to the Square API Data Policy Disclosures.

  • Unsupported data types. You can only create order-related custom attribute definitions that specify a schema for a supported data type. The following data types are not supported for order-related custom attributes:

    • DateTime

    • Duration

  • Limits. A seller account can have a maximum of 100 order-related custom attribute definitions per application.

  • Unique name. If the visibility of an order-related custom attribute definition is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES, the name must be unique (case-sensitive) across all visible order-related custom attribute definitions for the seller. This requirement is intended to help sellers differentiate between custom attributes that are visible in the Customer Directory and other Square products.

  • Maximum value for Number custom attributes. The absolute value of a Number-type custom attribute cannot exceed (2^63-1)/10^5, or 92233720368547.

  • OAuth permissions. Applications that use OAuth require ORDER_READ or ORDER_WRITE permission to work with order-related custom attributes. For more information, see Connect your Application to a Seller's Account Using OAuth and OAuth Permissions Reference.

    If a seller revokes the permissions of the application that created a custom attribute definition or the token expires, the application cannot access the definition or corresponding custom attributes until permissions are restored. However, the definition and custom attributes remain available to other applications according to the visibility setting.

  • Idempotency. Including an idempotency key in a request guarantees that the request is processed only once. The following endpoints allow you to specify an idempotency_key:

    • CreateOrderCustomAttributeDefinition

    • UpdateOrderCustomAttributeDefinition

    • UpsertOrderCustomAttribute

    • BulkUpsertOrderCustomAttributes

Be sure to generate a unique idempotency key for each request. If an idempotency key is reused in requests to the same endpoint on behalf of the same seller, Square returns the response from the first request that was successfully processed using the key. Square does not process subsequent requests that use the same key, even if they contain different fields. For more information, see Idempotency.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.