Define Custom Attributes for Orders

Applies to: Order Custom Attributes API

Learn how to create and manage order-related custom attribute definitions for Square sellers using the Order Custom Attributes API.

To create a custom attribute definition, you must specify its key identifier, visibility setting, schema data type, and other properties. After you create the definition, you can set the custom attribute for orders.

Custom attribute definitions are stored as a collection for a Square seller.

.../v2/orders/custom-attribute-definitions

Every custom attribute definition is represented by a CustomAttributeDefinition object. The following is an example custom attribute definition that defines a "Cover Count" custom attribute of data type Number:

{
  "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 fields represent core properties of a custom attribute definition:

To create a custom attribute definition for orders, use the CreateOrderCustomAttributeDefinition endpoint. Note the following:

• key is the identifier for the definition and its corresponding custom attributes. The value must be unique for the application. It can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-) and must match the following regular expression:

  ^[a-zA-Z0-9\._-]{1,60}$

• visibility is the access control setting that determines whether other applications can view the definition and view or edit corresponding custom attributes. The following are valid values:

  • VISIBILITY_HIDDEN (default)
  • VISIBILITY_READ_ONLY
  • VISIBILITY_READ_WRITE_VALUES

  Sellers can view all custom attributes in exported order data, including those set to VISIBILITY_HIDDEN.

• schema is the data type of the custom attribute. For more information, see Specifying the schema.

• name and description are the name and description of the custom attribute. Each field can contain up to 255 characters.

  Both fields are required when visibility is set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. If provided, name must be unique (case-sensitive) across all visible order-related custom attribute definitions for the seller. Seller-facing custom attributes should be given a friendly name and description.

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

The following example request defines a "Cover Count" custom attribute whose value can be a Number:

The following is an example response:

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

After a custom attribute definition is created, Square invokes the following webhooks:

• order.custom_attribute_definition.owned.created
• order.custom_attribute_definition.visible.created

You can now set the custom attribute for the seller's orders. For more information, see the following:

• Create or update a custom attribute for an order
• Bulk create or update custom attributes for orders

The data type of a custom attribute is specified by the schema field of the definition. Square uses the schema to validate the custom attribute value when it's assigned to an order.

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

• String
• Email
• PhoneNumber
• Address
• Date
• Boolean
• Number
• Selection

In a CreateOrderCustomAttributeDefinition request, the schema field specifies a data type by referencing a JSON schema or meta-schema object hosted on the Square CDN.

For the data types in the following table, specify a $ref value that references the corresponding schema object, as shown in the following example:

 "schema": {
   "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
 },

For a Selection data type, the schema contains a $schema field that references a JSON meta-schema object, as well as additional fields. Note the following:

• $schema references the https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json meta-schema hosted on the Square CDN.
• type must be array.
• items must include a names array that contains strings representing the display names of the predefined options that can be selected. Note that the order of the options might not be respected by all UIs.
• maxItems is an integer that represents the maximum number of allowed selections. Corresponding custom attributes can have zero or more selected values, up to the specified maximum. The minimum value is 1 and cannot exceed the number of options in the names field.
• uniqueItems must be true.

The following example request creates a Selection-type custom attribute definition that contains three named options and allows one selection:

The following is an example response. For each named option, Square generates a UUID and adds it to the enum field. 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.

These UUIDs are used to set the value of the custom attribute or update the option names.

{
  "custom_attribute_definition": {
    "key": "shirt-size",
    "name": "Default shirt size",
    "description": "The default shirt size ordered by the customer.",
    "version": 1,
    "updated_at": "2022-11-16T17:38:19.783Z",
    "schema": {
      "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
      "maxItems": 1,
      "type": "array",
      "uniqueItems": true,
      "items": {
        "names": [
          "Small",
          "Medium",
          "Large"
        ],
        "enum": [
          "4fc37499-6d68-4cdc-a64f-9ba2fd9a2943",
          "6ddaffce-7428-4f6c-bfe4-7f5922be71fd",
          "a1700eeb-0866-458f-bbe9-79e0d74acffa"
        ]
      }
    },
    "created_at": "2022-11-16T17:38:19.783Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

Use the UpdateOrderCustomAttributeDefinition endpoint to update a custom attribute definition for a seller account. Only the following fields can be updated:

• name
• description
• visibility
• schema for a Selection data type

Only new or changed fields need to be included in the request. For more information, see Updatable definition fields.

Note the following about an UpdateOrderCustomAttributeDefinition request:

• A custom attribute definition can be updated only by the definition owner.

• The key path parameter is the key of the custom attribute definition.

• The version field can be optionally included to enable optimistic concurrency control. If included, version must match the current version of the custom attribute definition; otherwise, the request fails with a CONFLICT error. Square increments the version number each time the definition is updated.

• The idempotency_key is a unique ID for the request that can be optionally included to ensure idempotency.

The following example request updates the visibility setting of a definition:

The following is an example response:

{
  "custom_attribute_definition": {
    "key": "cover-count",
    "name": "Cover count",
    "description": "The number of people seated at a table",
    "version": 2,
    "updated_at": "2022-11-16T17:44:11.436Z",
    "schema": {
      "$ref": "https://developer-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
    },
    "created_at": "2022-11-16T16:53:23.141Z",
    "visibility": "VISIBILITY_READ_ONLY"
  }
}

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

The UpdateOrderCustomAttributeDefinition endpoint supports sparse updates, so only new or changed fields need to be included in the request. Square ignores custom attribute definition fields that are unchanged or read-only.

You can update one or more of the following fields:

• name - The name of the custom attribute.

• description - The description of the custom attribute.

• visibility - The access control setting that determines whether other applications can view the definition and view or edit corresponding custom attributes. The following are valid values:

  • VISIBILITY_HIDDEN (default)
  • VISIBILITY_READ_ONLY
  • VISIBILITY_READ_WRITE_VALUES

  Changes to the visibility setting are propagated to corresponding custom attributes within a couple seconds. At that time, the updated_at and version fields of the custom attributes are also updated. For VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES settings, both name and description are required.

• schema - For a Selection data type. You can only change the named options and the maximum number of selections, as described in the following section.

For a Selection data type, you can update the maximum number of allowed selections and the set of predefined named options.

The information you send in the UpdateOrderCustomAttributeDefinition request depends on the change you want to make:

• To change the maximum number of allowed selections, include the maxItems field with the new integer value. The minimum value is 1 and cannot exceed the number of options in the names field.

• To change the set of predefined named options, include the items field with the complete names and enum arrays. The options in the names array map by index to the Square-assigned UUIDs in the enum array, which are unique per seller. The first option maps to the first UUID, the second option maps to the second UUID, and so on.

  • To add an option:

    • Add the name of the new option at the end of the names array. New options must always be added to the end of the array.
    • Don't change the enum array. Square generates a UUID for the new option and adds it to the end of the enum array.

  • To reorder the options:

    • Change the order of the names in the names array.

    • Change the order of the UUIDs in the enum array so that the order of the UUIDs matches the order of the corresponding named options.

      Note that the order might not be respected by all UIs.

  • To remove an option:

    • Remove the name of the option from the names array.
    • Remove the corresponding UUID from the enum array.

The following example UpdateOrderCustomAttributeDefinition request adds two new options by adding the names at the end of the names array.

The following example response includes the UUID that Square generated for the new X-Small and X-Large options:

{
  "custom_attribute_definition": {
    "key": "shirt-size",
    "name": "Default shirt size",
    "description": "The default shirt size ordered by the customer.",
    "version": 4,
    "updated_at": "2022-11-16T17:57:37.227Z",
    "schema": {
      "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
      "maxItems": 1,
      "type": "array",
      "uniqueItems": true,
      "items": {
        "names": [
          "Small",
          "Medium",
          "Large",
          "X-Small",
          "X-Large"
        ],
        "enum": [
          "cbebfe6e-5d1d-4ce2-8bfb-eadbbf548f3b",
          "1ff6e493-31ed-4f9b-a570-948cf54eb94f",
          "a760af07-139d-44aa-acdc-6b706fda79de",
          "35f555a6-ce8b-405b-8e75-c09b3b757550",
          "09f056fd-07dd-4419-b675-4b950d1b2d81"
        ]
      }
    },
    "created_at": "2022-11-16T17:52:00.098Z",
    "visibility": "VISIBILITY_READ_WRITE_VALUES"
  }
}

To list the custom attribute definitions of a seller account, use the ListOrderCustomAttributeDefinitions endpoint. Note the following:

• The limit query parameter optionally specifies a maximum page size of 1 to 100 results. The default limit is 20.

• If the results are paginated, 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, all custom attribute definitions created by the requesting application are included in the results. The key for these definitions is the key that was provided when the definition was created.

Custom attribute definitions created by other applications are included if their visibility is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. The key for these definitions is a qualified key.

The following is an example response:

{
  "custom_attribute_definitions": [
    {
      "key": "cover-count",
      "name": "Cover count",
      "description": "The number of people seated at a table",
      "version": 1,
      "updated_at": "2022-11-16T18:03:44.051Z",
      "schema": {
        "$ref": "https://developer-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
      },
      "created_at": "2022-11-16T18:03:44.051Z",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    },
    {
      "key": "seat-number",
      "name": "Seat number",
      "description": "The identifier for a particular seat",
      "version": 1,
      "updated_at": "2022-11-16T18:04:32.059Z",
      "schema": {
        "$ref": "https://developer-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
      },
      "created_at": "2022-11-16T18:04:32.059Z",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    },
    {
      "key": "table-number",
      "name": "Table number",
      "description": "The identifier for a particular table",
      "version": 1,
      "updated_at": "2022-11-16T18:04:21.912Z",
      "schema": {
        "$ref": "https://developer-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
      },
      "created_at": "2022-11-16T18:04:21.912Z",
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    }
  ]
}

If no custom attribute definitions are found, Square returns an empty response.

{}

Use the RetrieveOrderCustomAttributeDefinition endpoint to retrieve a custom attribute definition using the key. Note the following:

• The key path parameter is the key of the custom attribute definition.

  • 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 definition must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

• The version query parameter is optionally used 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:

The following is an example response:

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

If the custom attribute definition isn't found, Square returns an errors field that contains a 404 NOT_FOUND error.

To delete a custom attribute definition from a seller account, use the DeleteOrderCustomAttributeDefinition endpoint. Note the following:

• Only the definition owner can delete a custom attribute definition.

• The key path parameter is the key of the custom attribute definition.

• Deleting a custom attribute definition also deletes the corresponding custom attribute from all orders.

The following is an example request:

If successful, Square returns an empty object.

{}

After deleting a custom attribute definition, Square invokes the order.custom_attribute_definition.owned.deleted and order.custom_attribute_definition.visible.deleted webhooks.

• Custom Attributes for Orders
• Use Custom Attributes for Orders
• Custom Attributes
• API Reference: Custom Attributes for Orders