Order Custom Attributes

const orderCustomAttributesApi = client.orderCustomAttributesApi;

Class Name

OrderCustomAttributesApi

Methods

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

List Order Custom Attribute Definitions

Lists the order-related custom attribute definitions that belong to a Square seller account.

When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

async listOrderCustomAttributeDefinitions(
  visibilityFilter?: string,
  cursor?: string,
  limit?: number,
  requestOptions?: RequestOptions
): Promise<ApiResponse<ListOrderCustomAttributeDefinitionsResponse>>

Parameters

Parameter	Type	Tags	Description
`visibilityFilter`	`string \| undefined`	Query, Optional	Requests that all of the custom attributes be returned, or only those that are read-only or read-write.
`cursor`	`string \| undefined`	Query, Optional	The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
`limit`	`number \| undefined`	Query, Optional	The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

ListOrderCustomAttributeDefinitionsResponse

Example Usage

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.listOrderCustomAttributeDefinitions();
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Create Order Custom Attribute Definition

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.

async createOrderCustomAttributeDefinition(
  body: CreateOrderCustomAttributeDefinitionRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<CreateOrderCustomAttributeDefinitionResponse>>

Parameters

Parameter	Type	Tags	Description
`body`	`CreateOrderCustomAttributeDefinitionRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

CreateOrderCustomAttributeDefinitionResponse

Example Usage

const body: CreateOrderCustomAttributeDefinitionRequest = {
  customAttributeDefinition: {
    key: 'cover-count',
    name: 'Cover count',
    description: 'The number of people seated at a table',
    visibility: 'VISIBILITY_READ_WRITE_VALUES',
  },
  idempotencyKey: 'IDEMPOTENCY_KEY',
};

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.createOrderCustomAttributeDefinition(body);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Delete Order Custom Attribute Definition

Deletes an order-related custom attribute definition from a Square seller account.

Only the definition owner can delete a custom attribute definition.

async deleteOrderCustomAttributeDefinition(
  key: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<DeleteOrderCustomAttributeDefinitionResponse>>

Parameters

Parameter	Type	Tags	Description
`key`	`string`	Template, Required	The key of the custom attribute definition to delete.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

DeleteOrderCustomAttributeDefinitionResponse

Example Usage

const key = 'key0';

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.deleteOrderCustomAttributeDefinition(key);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Retrieve Order Custom Attribute Definition

Retrieves an order-related custom attribute definition from a Square seller account.

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

async retrieveOrderCustomAttributeDefinition(
  key: string,
  version?: number,
  requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveOrderCustomAttributeDefinitionResponse>>

Parameters

Parameter	Type	Tags	Description
`key`	`string`	Template, Required	The key of the custom attribute definition to retrieve.
`version`	`number \| undefined`	Query, Optional	To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

RetrieveOrderCustomAttributeDefinitionResponse

Example Usage

const key = 'key0';

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.retrieveOrderCustomAttributeDefinition(key);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Update Order Custom Attribute Definition

Updates an order-related custom attribute definition for a Square seller account.

Only the definition owner can update a custom attribute definition. Note that sellers can view all custom attributes in exported customer data, including those set to VISIBILITY_HIDDEN.

async updateOrderCustomAttributeDefinition(
  key: string,
  body: UpdateOrderCustomAttributeDefinitionRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<UpdateOrderCustomAttributeDefinitionResponse>>

Parameters

Parameter	Type	Tags	Description
`key`	`string`	Template, Required	The key of the custom attribute definition to update.
`body`	`UpdateOrderCustomAttributeDefinitionRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

UpdateOrderCustomAttributeDefinitionResponse

Example Usage

const key = 'key0';

const body: UpdateOrderCustomAttributeDefinitionRequest = {
  customAttributeDefinition: {
    key: 'cover-count',
    visibility: 'VISIBILITY_READ_ONLY',
    version: 1,
  },
  idempotencyKey: 'IDEMPOTENCY_KEY',
};

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.updateOrderCustomAttributeDefinition(
  key,
  body
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Bulk Delete Order Custom Attributes

Deletes 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 BulkDeleteOrderCustomAttributes endpoint accepts a map of 1 to 25 individual delete requests and returns a map of individual delete responses. Each delete request has a unique ID and provides an order ID and custom attribute. Each delete response is returned with the ID of the corresponding request.

To delete 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.

async bulkDeleteOrderCustomAttributes(
  body: BulkDeleteOrderCustomAttributesRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<BulkDeleteOrderCustomAttributesResponse>>

Parameters

Parameter	Type	Tags	Description
`body`	`BulkDeleteOrderCustomAttributesRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

BulkDeleteOrderCustomAttributesResponse

Example Usage

const body: BulkDeleteOrderCustomAttributesRequest = {
  values: {
    'cover-count': {
      orderId: '7BbXGEIWNldxAzrtGf9GPVZTwZ4F',
    },
    'table-number': {
      orderId: '7BbXGEIWNldxAzrtGf9GPVZTwZ4F',
    }
  },
};

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.bulkDeleteOrderCustomAttributes(body);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Bulk Upsert Order Custom Attributes

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.

async bulkUpsertOrderCustomAttributes(
  body: BulkUpsertOrderCustomAttributesRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<BulkUpsertOrderCustomAttributesResponse>>

Parameters

Parameter	Type	Tags	Description
`body`	`BulkUpsertOrderCustomAttributesRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

BulkUpsertOrderCustomAttributesResponse

Example Usage

const body: BulkUpsertOrderCustomAttributesRequest = {
  values: {
    'key0': {
      customAttribute: {
      },
      orderId: 'order_id4',
    },
    'key1': {
      customAttribute: {
      },
      orderId: 'order_id4',
    }
  },
};

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.bulkUpsertOrderCustomAttributes(body);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

List Order Custom Attributes

Lists the custom attributes associated with an order.

You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call.

When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

async listOrderCustomAttributes(
  orderId: string,
  visibilityFilter?: string,
  cursor?: string,
  limit?: number,
  withDefinitions?: boolean,
  requestOptions?: RequestOptions
): Promise<ApiResponse<ListOrderCustomAttributesResponse>>

Parameters

Parameter	Type	Tags	Description
`orderId`	`string`	Template, Required	The ID of the target order.
`visibilityFilter`	`string \| undefined`	Query, Optional	Requests that all of the custom attributes be returned, or only those that are read-only or read-write.
`cursor`	`string \| undefined`	Query, Optional	The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
`limit`	`number \| undefined`	Query, Optional	The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
`withDefinitions`	`boolean \| undefined`	Query, Optional	Indicates whether to return the custom attribute definition in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`. Default: `false`
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

ListOrderCustomAttributesResponse

Example Usage

const orderId = 'order_id6';

const withDefinitions = false;

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.listOrderCustomAttributes(
  orderId,
  undefined,
  undefined,
  undefined,
  withDefinitions
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Delete Order Custom Attribute

Deletes a custom attribute associated with a customer profile.

To delete 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.

async deleteOrderCustomAttribute(
  orderId: string,
  customAttributeKey: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<DeleteOrderCustomAttributeResponse>>

Parameters

Parameter	Type	Tags	Description
`orderId`	`string`	Template, Required	The ID of the target order.
`customAttributeKey`	`string`	Template, Required	The key of the custom attribute to delete. This key must match the key of an existing custom attribute definition.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

DeleteOrderCustomAttributeResponse

Example Usage

const orderId = 'order_id6';

const customAttributeKey = 'custom_attribute_key2';

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.deleteOrderCustomAttribute(
  orderId,
  customAttributeKey
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Retrieve Order Custom Attribute

Retrieves a custom attribute associated with an order.

You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call.

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

async retrieveOrderCustomAttribute(
  orderId: string,
  customAttributeKey: string,
  version?: number,
  withDefinition?: boolean,
  requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveOrderCustomAttributeResponse>>

Parameters

Parameter	Type	Tags	Description
`orderId`	`string`	Template, Required	The ID of the target order.
`customAttributeKey`	`string`	Template, Required	The key of the custom attribute to retrieve. This key must match the key of an existing custom attribute definition.
`version`	`number \| undefined`	Query, Optional	To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.
`withDefinition`	`boolean \| undefined`	Query, Optional	Indicates whether to return the custom attribute definition in the `definition` field of each custom attribute. Set this parameter to `true` to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is `false`. Default: `false`
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

RetrieveOrderCustomAttributeResponse

Example Usage

const orderId = 'order_id6';

const customAttributeKey = 'custom_attribute_key2';

const withDefinition = false;

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.retrieveOrderCustomAttribute(
  orderId,
  customAttributeKey,
  undefined,
  withDefinition
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Upsert Order Custom Attribute

Creates or updates a custom attribute for an order.

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.

async upsertOrderCustomAttribute(
  orderId: string,
  customAttributeKey: string,
  body: UpsertOrderCustomAttributeRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<UpsertOrderCustomAttributeResponse>>

Parameters

Parameter	Type	Tags	Description
`orderId`	`string`	Template, Required	The ID of the target order.
`customAttributeKey`	`string`	Template, Required	The key of the custom attribute to create or update. This key must match the key of an existing custom attribute definition.
`body`	`UpsertOrderCustomAttributeRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

UpsertOrderCustomAttributeResponse

Example Usage

const orderId = 'order_id6';

const customAttributeKey = 'custom_attribute_key2';

const body: UpsertOrderCustomAttributeRequest = {
  customAttribute: {
  },
};

try {
  const { result, ...httpResponse } = await orderCustomAttributesApi.upsertOrderCustomAttribute(
  orderId,
  customAttributeKey,
  body
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Files

order-custom-attributes.md

Latest commit

History

order-custom-attributes.md

File metadata and controls

Order Custom Attributes

Class Name

Methods

List Order Custom Attribute Definitions

Parameters

Response Type

Example Usage

Create Order Custom Attribute Definition

Parameters

Response Type

Example Usage

Delete Order Custom Attribute Definition

Parameters

Response Type

Example Usage

Retrieve Order Custom Attribute Definition

Parameters

Response Type

Example Usage

Update Order Custom Attribute Definition

Parameters

Response Type

Example Usage

Bulk Delete Order Custom Attributes

Parameters

Response Type

Example Usage

Bulk Upsert Order Custom Attributes

Parameters

Response Type

Example Usage

List Order Custom Attributes

Parameters

Response Type

Example Usage

Delete Order Custom Attribute

Parameters

Response Type

Example Usage

Retrieve Order Custom Attribute

Parameters

Response Type

Example Usage

Upsert Order Custom Attribute

Parameters

Response Type

Example Usage