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 ->

Bulk upsert order custom attributesBeta

POST

 /v2/orders/custom-attributes/bulk-upsert

Creates or updates order custom attributes as a bulk operation.

Use this endpoint to delete one or more custom attributes from one or more orders. A custom attribute is based on a custom attribute definition in a Square seller account. (To create a custom attribute definition, use the CreateOrderCustomAttributeDefinition endpoint.)

This BulkUpsertOrderCustomAttributes endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides an order ID and custom attribute. Each upsert response is returned with the ID of the corresponding request.

To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

Permissions:ORDERS_WRITE

Guide

Bulk create or update custom attributes for orders

Try in API Explorer
Link to section

Request body

Example code

Link to section

values

Required

A map of requests that correspond to individual upsert operations for custom attributes.

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

values

Required

A map of responses that correspond to individual upsert operations for custom attributes.

Link to section

Examples

All versions ->

POST /v2/orders/custom-attributes/bulk-upsert
curl https://connect.squareup.com/v2/orders/custom-attributes/bulk-upsert \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "values": { "table-number": { "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F", "custom_attribute": { "key": "table-number", "value": "11", "version": 4 } }, "cover-count": { "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F", "custom_attribute": { "key": "cover-count", "value": "6", "version": 2 } } } }'

Response JSON

{ "values": { "table-number": { "custom_attribute": { "key": "table-number", "updated_at": "2022-11-22T21:28:35.726Z", "value": "11", "created_at": "2022-11-22T21:24:57.823Z", "visibility": "VISIBILITY_HIDDEN" } }, "cover-count": { "custom_attribute": { "key": "cover-count", "updated_at": "2022-11-22T21:28:35.721Z", "value": "6", "created_at": "2022-11-22T21:27:33.429Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } } } }