Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Order Custom Attributes

  • List order custom attribute definitions

  • Create order custom attribute definition

  • Delete order custom attribute definition

  • Retrieve order custom attribute definition

  • Update order custom attribute definition

  • Bulk delete order custom attributes

  • Bulk upsert order custom attributes

  • List order custom attributes

  • Delete order custom attribute

  • Retrieve order custom attribute

  • Upsert order custom attribute

  • Webhooks

  • order.custom_attribute_definition.owned.created

  • order.custom_attribute_definition.owned.deleted

  • order.custom_attribute_definition.owned.updated

  • order.custom_attribute_definition.visible.created

  • order.custom_attribute_definition.visible.deleted

  • order.custom_attribute_definition.visible.updated

  • order.custom_attribute.owned.deleted

  • order.custom_attribute.owned.updated

  • order.custom_attribute.visible.deleted

  • order.custom_attribute.visible.updated

<- Order Custom Attributes API

Order Custom Attributes API

All versions ->

Create order custom attribute definitionBeta

POST

 /v2/orders/custom-attribute-definitions

Creates an order-related custom attribute definition.

Use this endpoint to define a custom attribute that can be associated with orders.

After creating a custom attribute definition, you can set the custom attribute for orders in the Square seller account.

Permissions:ORDERS_WRITE

Guide

Create an order custom attribute definition

Try in API Explorer
Link to section

Request body

Example code

Link to section

custom_attribute_definition

Required

The custom attribute definition to create. Note the following:

  • With the exception of the Selection data type, the schema is specified as a simple URL to the JSON schema definition hosted on the Square CDN. For more information, including supported values and constraints, see Specifying the schema.
  • If provided, name must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.
  • All custom attributes are visible in exported customer data, including those set to VISIBILITY_HIDDEN.
Link to section

idempotency_key

string

A unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.

Min Length
1
Max Length
45
Link to section

Response fields

Link to section

custom_attribute_definition

The new custom attribute definition.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

POST /v2/orders/custom-attribute-definitions
curl https://connect.squareup.com/v2/orders/custom-attribute-definitions \ -X POST \ -H 'Square-Version: 2026-11-18' \ -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" }'

Response JSON

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