<- Order Custom Attributes API

Order Custom Attributes API

All versions ->

Upsert order custom attributeBeta

POST

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

Use this endpoint to set the value of a custom attribute for a specific order. 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.)

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

Create or update a custom attribute for an order

Try in API Explorer
Link to section

Path parameters

Example code

Link to section

order_id

string

Required

The ID of the target order.

Link to section

custom_attribute_key

string

Required

The key of the custom attribute to create or update. This key must match the key of an existing custom attribute definition.

Link to section

Request body

Link to section

custom_attribute

Required

The custom attribute to create or update, with the following fields:

  • value. This value must conform to the schema specified by the definition. For more information, see Value data types.

  • version. To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.

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

The order custom attribute that was created or modified.

Link to section

errors

Any errors that occurred during the request.