Use Custom Attributes for Orders

Order-related custom attributes are used to store properties or metadata for an order. A custom attribute is based on a custom attribute definition in a Square seller account. After the definition is created, the custom attribute can be set for orders. For an overview of how order-related custom attributes work, see Custom Attributes for Orders.

Order-related custom attributes are stored as a collection for an order.

.../v2/orders/{order_id}/custom-attributes

An individual custom attribute is accessed using the order_id and key. If the requesting application isn't the definition owner, then key is a qualified key.

.../v2/orders/{order_id}/custom-attributes/{key}

A custom attribute is represented by a CustomAttribute object. Custom attributes obtain a key identifier, visibility setting, allowed data type, and other properties from a custom attribute definition, which is represented by a CustomAttributeDefinition object.

The following is an example custom attribute:

{
  "custom_attribute": {
    "key": "table-number",
    "version": 1,
    "updated_at": "2022-10-06T20:41:22.673Z",
    "value": "42",
    "created_at": "2022-10-06T20:41:22.673Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

The following fields represent core properties of a custom attribute:

When working with custom attributes owned by other applications, you must provide a qualified key for the following endpoints:

• UpsertOrderCustomAttribute
• BulkUpsertOrderCustomAttributes
• RetrieveOrderCustomAttribute
• DeleteOrderCustomAttribute

Square generates a qualified key in the format {application ID}:{key}, using the application ID of the definition owner and the key that was provided when the definition was created.

The following example is a qualified key generated for a third-party application:

sq0idp-BuahoY39o1X-GPxRRUWc0A:businessEmail

The following example is a qualified key for a seller-defined custom field. The application ID for first-party Square products is square.

square:0460be56-6783-4482-8d55-634f9ae61684

You can call the following endpoints to retrieve a qualified key:

• ListOrderCustomAttributeDefinitions - Custom attributes use the same key as the corresponding definition.

• ListOrderCustomAttributes - Only custom attributes that have a value are returned. If the with_definitions query parameter is included in the request, custom attribute definitions are also returned. For more information, see List order custom attribute definitions.

Square returns qualified keys for custom attributes and custom attribute definitions when the requesting application isn't the definition owner.

The following data types are supported for order-related custom attributes:

For more information about these data types, including constraints and example requests for setting custom attribute values, see Create or update a custom attribute for an order.

The data type of a custom attribute is specified by the schema field of the custom attribute definition. You can call the following endpoints to retrieve a definition:

• RetrieveOrderCustomAttributeDefinition

• RetrieveOrderCustomAttribute using the with_definition query parameter. For more information, see Retrieve a custom attribute for an order.

All data types except Selection are specified using a simple URL reference to an object hosted on the Square CDN. A Selection data type provides additional information.

The following is an example Number-type custom attribute definition:

{
  "custom_attribute_definition": {
    "key": "cover-count",
    "name": "Cover count",
    "description": "The number of people seated at a table",
    "version": 1,
    "updated_at": "2022-10-06T16:53:23.141Z",
    "schema": {
      "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
    },
    "created_at": "2022-10-06T16:53:23.141Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

The following is an excerpt of an example Selection-type custom attribute definition:

{
  "custom_attribute_definition": {
    ...
    "schema": {
      "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
      "maxItems": 3,
      "type": "array", 
      "uniqueItems": true,
      "items": {
        "names": [
          "Cookie",
          "Cake",
          "Pie"
        ],
        "enum": [
          "9492bdda-ab4d-4eeb-8496-0986c8f78499",   // UUID for "Option 1"
          "6b96fba7-d8a5-ae72-48f4-8c3ee875633f",   // UUID for "Option 2"
          "4032c1a2-d749-4c75-9c30-be6472cd2e08"    // UUID for "Option 3"
        ]
      }
    },
    ...
  }
}

Note the following:

• The maxItems field represents the maximum number of allowed selections for the custom attribute value.

• The items field contains two arrays: names and enum. The options in the names field map by index to the UUIDs in the enum field. The first option maps to the first UUID, the second option maps to the second UUID, and so on.

This mapping is used to set the custom attribute value. For example, the value of the following custom attribute maps to "Cake":

{
  "custom_attribute": {
    "key": "favorite-dessert",
    "version": 1,
    "updated_at": "2022-11-16T00:07:20Z",
    "value": [
      "6b96fba7-d8a5-ae72-48f4-8c3ee875633f"
    ],
    "created_at": "2022-11-16T00:07:20Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

For more example UpsertOrderCustomAttribute requests, see Create or update a custom attribute for an order.

To set the value of a custom attribute for an order, call UpsertOrderCustomAttribute and provide the following information:

• order_id - The id of the Order object that represents the target order.

• key - The key of the custom attribute to create or update.

  • If the requesting application is the definition owner, use the key that was provided when the definition was created.

  • If the requesting application isn't the definition owner, use the qualified key. The visibility of the custom attribute must be VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

• custom_attribute - The custom attribute with the following fields:

  • value - The value of the custom attribute, which must conform to the schema specified by the definition. For more information, see Value data types.

  • version - The current version of the custom attribute, optionally included to enable optimistic concurrency control when updating a value that was previously set for the order. If the specified version is less than the current version of the custom attribute, the request fails with a CONFLICT error. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

• idempotency_key - A unique ID for the request that can be optionally included to ensure idempotency.

The following example request sets the value for a Number-type custom attribute. The key in this example is seat-number.

The following is an example response:

{
  "custom_attribute": {
    "key": "table-number",
    "version": 1,
    "updated_at": "2022-10-06T20:41:22.673Z",
    "value": "42",
    "created_at": "2022-10-06T20:41:22.673Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

During upsert operations, Square validates the provided value against the schema specified by the definition.

After a custom attribute is upserted, Square invokes the order.custom_attribute.owned.updated and order.custom_attribute.visible.updated webhooks.

You can set a corresponding custom attribute for an order by providing a value that conforms to the schema specified by the custom attribute definition. For information about retrieving the schema, see Value data types.

To create or update multiple custom attributes for one or more orders, call BulkUpsertOrderCustomAttributes. This endpoint accepts a values map with 1 to 25 objects that each contain:

• An arbitrary ID for the individual upsert request, which corresponds to an entry in the response that has the same ID. The ID must be unique within the BulkUpsertOrderCustomAttributes request.
• An individual upsert request with the information needed to create or update a custom attribute for an order.

The following example includes two upsert requests that set two custom attributes for an order:

During upsert operations, Square validates each provided value against the schema specified by the definition. The optional version field is only supported for update operations.

An individual upsert request contains the information needed to set the value of a custom attribute for an order. Each request includes the following fields:

• order_id - The id of the Order object that represents the target order.

• custom_attribute - The custom attribute with following fields:

  • key - The key of the custom attribute to create or update.

    • If the requesting application is the definition owner, use the key that was provided when the definition was created.

    • If the requesting application isn't the definition owner, use the qualified key. The visibility of the custom attribute must be VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

  • value - The value of the custom attribute, which must conform to the schema specified by the definition. For more information, see Value data types. The size of this field cannot exceed 5 KB.

  • version - The current version of the custom attribute, optionally included to enable optimistic concurrency control when updating a value that was previously set for the order. If the specified version is less than the current version of the custom attribute, the request fails with a CONFLICT error. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

• idempotency_key - A unique ID for the individual request that can be optionally included to ensure idempotency.

Individual upsert requests aren't guaranteed to be returned in the same order. Each upsert response has the same ID as the corresponding upsert request, so you can use the ID to map individual requests and responses.

After each custom attribute is upserted, Square invokes the order.custom_attribute.owned.updated and order.custom_attribute.visible.updated webhooks.

To list the custom attributes that are set for an order, call ListOrderCustomAttributes and provide the following information:

• order_id - The id of the Order object that represents the target order.

• with_definitions - Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to retrieve the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

• limit - The maximum page size (of 1 to 100 results) to return in a response. The default value is 20.

  If the results are paged, the cursor field in the response contains a value that you can send with the cursor query parameter to retrieve the next page of results.

The following example request includes the limit query parameter:

When all pages are retrieved, the results include:

• All custom attributes owned by the requesting application that have a value. The key for these custom attributes is the key that was provided for the definition.

• All custom attributes owned by other applications that have a value and a visibility setting of VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. The key for these custom attributes is a qualified key. For more information, see Qualified keys.

If no custom attributes are found, Square returns an empty object.

{}

To retrieve a custom attribute for an order, call RetrieveOrderCustomAttribute and provide the following information:

• order_id - The id of the Order object that represents the target order.

• key - The key of the custom attribute to retrieve.

  • If the requesting application is the definition owner, use the key that was provided when the definition was created.

  • If the requesting application isn't the definition owner, use the qualified key. The visibility of the custom attribute must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

• with_definition - Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to retrieve the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.

• version - The current version of the custom attribute, optionally included for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a 400 BAD_REQUEST error.

The following is an example request:

To delete a custom attribute for an order, call DeleteOrderCustomAttribute and provide the following information:

• order_id - The id of the Order object that represents the target order.

• key - The key of the custom attribute to delete.

  • If the requesting application is the definition owner, use the key that was provided when the definition was created.

  • If the requesting application isn't the definition owner, use the qualified key. The visibility of the custom attribute must be VISIBILITY_READ_WRITE_VALUES. For more information, see Qualified keys.

The following is an example request:

If the operation is successful, Square returns an empty object:

{}

To delete all custom attributes of one or more orders in a single request, call BulkDeleteOrderCustomAttributes.

After a custom attribute is deleted, Square invokes the order.custom_attribute.owned.deleted and order.custom_attribute.visible.deleted webhooks.

• Custom Attributes for Orders
• Create and Manage Custom Attribute Definitions for Orders
• Custom Attributes Overview
• API Reference: Order Custom Attributes API