Order Custom Attributes

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

ListOrderCustomAttributeDefinitionsAsync(
    string visibilityFilter = null,
    string cursor = null,
    int? limit = null)

Parameters

Parameter	Type	Tags	Description
`visibilityFilter`	`string`	Query, Optional	Requests that all of the custom attributes be returned, or only those that are read-only or read-write.
`cursor`	`string`	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`	`int?`	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.

Response Type

Task<Models.ListOrderCustomAttributeDefinitionsResponse>

Example Usage

try
{
    ListOrderCustomAttributeDefinitionsResponse result = await orderCustomAttributesApi.ListOrderCustomAttributeDefinitionsAsync();
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

CreateOrderCustomAttributeDefinitionAsync(
    Models.CreateOrderCustomAttributeDefinitionRequest body)

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.

Response Type

Task<Models.CreateOrderCustomAttributeDefinitionResponse>

Example Usage

CreateOrderCustomAttributeDefinitionRequest body = new CreateOrderCustomAttributeDefinitionRequest.Builder(
    new CustomAttributeDefinition.Builder()
    .Key("cover-count")
    .Name("Cover count")
    .Description("The number of people seated at a table")
    .Visibility("VISIBILITY_READ_WRITE_VALUES")
    .Build()
)
.IdempotencyKey("IDEMPOTENCY_KEY")
.Build();

try
{
    CreateOrderCustomAttributeDefinitionResponse result = await orderCustomAttributesApi.CreateOrderCustomAttributeDefinitionAsync(body);
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

DeleteOrderCustomAttributeDefinitionAsync(
    string key)

Parameters

Parameter	Type	Tags	Description
`key`	`string`	Template, Required	The key of the custom attribute definition to delete.

Response Type

Task<Models.DeleteOrderCustomAttributeDefinitionResponse>

Example Usage

string key = "key0";
try
{
    DeleteOrderCustomAttributeDefinitionResponse result = await orderCustomAttributesApi.DeleteOrderCustomAttributeDefinitionAsync(key);
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

RetrieveOrderCustomAttributeDefinitionAsync(
    string key,
    int? version = null)

Parameters

Parameter	Type	Tags	Description
`key`	`string`	Template, Required	The key of the custom attribute definition to retrieve.
`version`	`int?`	Query, Optional	To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.

Response Type

Task<Models.RetrieveOrderCustomAttributeDefinitionResponse>

Example Usage

string key = "key0";
try
{
    RetrieveOrderCustomAttributeDefinitionResponse result = await orderCustomAttributesApi.RetrieveOrderCustomAttributeDefinitionAsync(key);
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

UpdateOrderCustomAttributeDefinitionAsync(
    string key,
    Models.UpdateOrderCustomAttributeDefinitionRequest body)

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.

Response Type

Task<Models.UpdateOrderCustomAttributeDefinitionResponse>

Example Usage

string key = "key0";
UpdateOrderCustomAttributeDefinitionRequest body = new UpdateOrderCustomAttributeDefinitionRequest.Builder(
    new CustomAttributeDefinition.Builder()
    .Key("cover-count")
    .Visibility("VISIBILITY_READ_ONLY")
    .Version(1)
    .Build()
)
.IdempotencyKey("IDEMPOTENCY_KEY")
.Build();

try
{
    UpdateOrderCustomAttributeDefinitionResponse result = await orderCustomAttributesApi.UpdateOrderCustomAttributeDefinitionAsync(
        key,
        body
    );
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

BulkDeleteOrderCustomAttributesAsync(
    Models.BulkDeleteOrderCustomAttributesRequest body)

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.

Response Type

Task<Models.BulkDeleteOrderCustomAttributesResponse>

Example Usage

BulkDeleteOrderCustomAttributesRequest body = new BulkDeleteOrderCustomAttributesRequest.Builder(
    new Dictionary<string, BulkDeleteOrderCustomAttributesRequestDeleteCustomAttribute>
    {
        ["cover-count"] = new BulkDeleteOrderCustomAttributesRequestDeleteCustomAttribute.Builder(
            "7BbXGEIWNldxAzrtGf9GPVZTwZ4F"
        )
        .Build(),
        ["table-number"] = new BulkDeleteOrderCustomAttributesRequestDeleteCustomAttribute.Builder(
            "7BbXGEIWNldxAzrtGf9GPVZTwZ4F"
        )
        .Build(),
    }
)
.Build();

try
{
    BulkDeleteOrderCustomAttributesResponse result = await orderCustomAttributesApi.BulkDeleteOrderCustomAttributesAsync(body);
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

BulkUpsertOrderCustomAttributesAsync(
    Models.BulkUpsertOrderCustomAttributesRequest body)

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.

Response Type

Task<Models.BulkUpsertOrderCustomAttributesResponse>

Example Usage

BulkUpsertOrderCustomAttributesRequest body = new BulkUpsertOrderCustomAttributesRequest.Builder(
    new Dictionary<string, BulkUpsertOrderCustomAttributesRequestUpsertCustomAttribute>
    {
        ["key0"] = new BulkUpsertOrderCustomAttributesRequestUpsertCustomAttribute.Builder(
            new CustomAttribute.Builder()
            .Build(),
            "order_id4"
        )
        .Build(),
        ["key1"] = new BulkUpsertOrderCustomAttributesRequestUpsertCustomAttribute.Builder(
            new CustomAttribute.Builder()
            .Build(),
            "order_id4"
        )
        .Build(),
    }
)
.Build();

try
{
    BulkUpsertOrderCustomAttributesResponse result = await orderCustomAttributesApi.BulkUpsertOrderCustomAttributesAsync(body);
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

ListOrderCustomAttributesAsync(
    string orderId,
    string visibilityFilter = null,
    string cursor = null,
    int? limit = null,
    bool? withDefinitions = false)

Parameters

Parameter	Type	Tags	Description
`orderId`	`string`	Template, Required	The ID of the target order.
`visibilityFilter`	`string`	Query, Optional	Requests that all of the custom attributes be returned, or only those that are read-only or read-write.
`cursor`	`string`	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`	`int?`	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`	`bool?`	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`

Response Type

Task<Models.ListOrderCustomAttributesResponse>

Example Usage

string orderId = "order_id6";
bool? withDefinitions = false;
try
{
    ListOrderCustomAttributesResponse result = await orderCustomAttributesApi.ListOrderCustomAttributesAsync(
        orderId,
        null,
        null,
        null,
        withDefinitions
    );
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

DeleteOrderCustomAttributeAsync(
    string orderId,
    string customAttributeKey)

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.

Response Type

Task<Models.DeleteOrderCustomAttributeResponse>

Example Usage

string orderId = "order_id6";
string customAttributeKey = "custom_attribute_key2";
try
{
    DeleteOrderCustomAttributeResponse result = await orderCustomAttributesApi.DeleteOrderCustomAttributeAsync(
        orderId,
        customAttributeKey
    );
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

RetrieveOrderCustomAttributeAsync(
    string orderId,
    string customAttributeKey,
    int? version = null,
    bool? withDefinition = false)

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`	`int?`	Query, Optional	To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.
`withDefinition`	`bool?`	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`

Response Type

Task<Models.RetrieveOrderCustomAttributeResponse>

Example Usage

string orderId = "order_id6";
string customAttributeKey = "custom_attribute_key2";
bool? withDefinition = false;
try
{
    RetrieveOrderCustomAttributeResponse result = await orderCustomAttributesApi.RetrieveOrderCustomAttributeAsync(
        orderId,
        customAttributeKey,
        null,
        withDefinition
    );
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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.

UpsertOrderCustomAttributeAsync(
    string orderId,
    string customAttributeKey,
    Models.UpsertOrderCustomAttributeRequest body)

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.

Response Type

Task<Models.UpsertOrderCustomAttributeResponse>

Example Usage

string orderId = "order_id6";
string customAttributeKey = "custom_attribute_key2";
UpsertOrderCustomAttributeRequest body = new UpsertOrderCustomAttributeRequest.Builder(
    new CustomAttribute.Builder()
    .Build()
)
.Build();

try
{
    UpsertOrderCustomAttributeResponse result = await orderCustomAttributesApi.UpsertOrderCustomAttributeAsync(
        orderId,
        customAttributeKey,
        body
    );
}
catch (ApiException e)
{
    // TODO: Handle exception here
    Console.WriteLine(e.Message);
}

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