Skip to content

Latest commit

 

History

History
552 lines (390 loc) · 22.4 KB

order-custom-attributes.md

File metadata and controls

552 lines (390 loc) · 22.4 KB
Raw

Order Custom Attributes

order_custom_attributes_api = client.order_custom_attributes

Class Name

OrderCustomAttributesApi

Methods

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.

def list_order_custom_attribute_definitions(self,
                                           visibility_filter=None,
                                           cursor=None,
                                           limit=None)

Parameters

Parameter Type Tags Description
visibility_filter str (Visibility Filter) Query, Optional Requests that all of the custom attributes be returned, or only those that are read-only or read-write.
cursor str 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

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type List Order Custom Attribute Definitions Response.

Example Usage

result = order_custom_attributes_api.list_order_custom_attribute_definitions()

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def create_order_custom_attribute_definition(self,
                                            body)

Parameters

Parameter Type Tags Description
body Create Order Custom Attribute Definition Request Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Create Order Custom Attribute Definition Response.

Example Usage

body = {
    'custom_attribute_definition': {
        'key': 'cover-count',
        'name': 'Cover count',
        'description': 'The number of people seated at a table',
        'visibility': 'VISIBILITY_READ_WRITE_VALUES'
    },
    'idempotency_key': 'IDEMPOTENCY_KEY'
}

result = order_custom_attributes_api.create_order_custom_attribute_definition(body)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def delete_order_custom_attribute_definition(self,
                                            key)

Parameters

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

Response Type

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Delete Order Custom Attribute Definition Response.

Example Usage

key = 'key0'

result = order_custom_attributes_api.delete_order_custom_attribute_definition(key)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def retrieve_order_custom_attribute_definition(self,
                                              key,
                                              version=None)

Parameters

Parameter Type Tags Description
key str 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

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Retrieve Order Custom Attribute Definition Response.

Example Usage

key = 'key0'

result = order_custom_attributes_api.retrieve_order_custom_attribute_definition(key)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def update_order_custom_attribute_definition(self,
                                            key,
                                            body)

Parameters

Parameter Type Tags Description
key str Template, Required The key of the custom attribute definition to update.
body Update Order Custom Attribute Definition Request Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Update Order Custom Attribute Definition Response.

Example Usage

key = 'key0'

body = {
    'custom_attribute_definition': {
        'key': 'cover-count',
        'visibility': 'VISIBILITY_READ_ONLY',
        'version': 1
    },
    'idempotency_key': 'IDEMPOTENCY_KEY'
}

result = order_custom_attributes_api.update_order_custom_attribute_definition(
    key,
    body
)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def bulk_delete_order_custom_attributes(self,
                                       body)

Parameters

Parameter Type Tags Description
body Bulk Delete Order Custom Attributes Request Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Bulk Delete Order Custom Attributes Response.

Example Usage

body = {
    'values': {
        'cover-count': {
            'order_id': '7BbXGEIWNldxAzrtGf9GPVZTwZ4F',
            'key': 'cover-count'
        },
        'table-number': {
            'order_id': '7BbXGEIWNldxAzrtGf9GPVZTwZ4F',
            'key': 'table-number'
        }
    }
}

result = order_custom_attributes_api.bulk_delete_order_custom_attributes(body)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def bulk_upsert_order_custom_attributes(self,
                                       body)

Parameters

Parameter Type Tags Description
body Bulk Upsert Order Custom Attributes Request Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Bulk Upsert Order Custom Attributes Response.

Example Usage

body = {
    'values': {
        'key0': {
            'custom_attribute': {},
            'order_id': 'order_id4'
        },
        'key1': {
            'custom_attribute': {},
            'order_id': 'order_id4'
        }
    }
}

result = order_custom_attributes_api.bulk_upsert_order_custom_attributes(body)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def list_order_custom_attributes(self,
                                order_id,
                                visibility_filter=None,
                                cursor=None,
                                limit=None,
                                with_definitions=False)

Parameters

Parameter Type Tags Description
order_id str Template, Required The ID of the target order.
visibility_filter str (Visibility Filter) Query, Optional Requests that all of the custom attributes be returned, or only those that are read-only or read-write.
cursor str 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.
with_definitions 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

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type List Order Custom Attributes Response.

Example Usage

order_id = 'order_id6'

with_definitions = False

result = order_custom_attributes_api.list_order_custom_attributes(
    order_id,
    with_definitions=with_definitions
)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def delete_order_custom_attribute(self,
                                 order_id,
                                 custom_attribute_key)

Parameters

Parameter Type Tags Description
order_id str Template, Required The ID of the target order.
custom_attribute_key str Template, Required The key of the custom attribute to delete. This key must match the key of an
existing custom attribute definition.

Response Type

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Delete Order Custom Attribute Response.

Example Usage

order_id = 'order_id6'

custom_attribute_key = 'custom_attribute_key2'

result = order_custom_attributes_api.delete_order_custom_attribute(
    order_id,
    custom_attribute_key
)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def retrieve_order_custom_attribute(self,
                                   order_id,
                                   custom_attribute_key,
                                   version=None,
                                   with_definition=False)

Parameters

Parameter Type Tags Description
order_id str Template, Required The ID of the target order.
custom_attribute_key str 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.
with_definition 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

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Retrieve Order Custom Attribute Response.

Example Usage

order_id = 'order_id6'

custom_attribute_key = 'custom_attribute_key2'

with_definition = False

result = order_custom_attributes_api.retrieve_order_custom_attribute(
    order_id,
    custom_attribute_key,
    with_definition=with_definition
)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

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.

def upsert_order_custom_attribute(self,
                                 order_id,
                                 custom_attribute_key,
                                 body)

Parameters

Parameter Type Tags Description
order_id str Template, Required The ID of the target order.
custom_attribute_key str 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 Upsert Order Custom Attribute Request Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a ApiResponse instance. The body property of this instance returns the response data which is of type Upsert Order Custom Attribute Response.

Example Usage

order_id = 'order_id6'

custom_attribute_key = 'custom_attribute_key2'

body = {
    'custom_attribute': {}
}

result = order_custom_attributes_api.upsert_order_custom_attribute(
    order_id,
    custom_attribute_key,
    body
)

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)