diff --git a/LICENSE b/LICENSE index 6863d491..ae39372e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright 2022 Square, Inc. +Copyright 2023 Square, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at diff --git a/doc/api/location-custom-attributes.md b/doc/api/location-custom-attributes.md new file mode 100644 index 00000000..d4a2954b --- /dev/null +++ b/doc/api/location-custom-attributes.md @@ -0,0 +1,477 @@ +# Location Custom Attributes + +```python +location_custom_attributes_api = client.location_custom_attributes +``` + +## Class Name + +`LocationCustomAttributesApi` + +## Methods + +* [List Location Custom Attribute Definitions](../../doc/api/location-custom-attributes.md#list-location-custom-attribute-definitions) +* [Create Location Custom Attribute Definition](../../doc/api/location-custom-attributes.md#create-location-custom-attribute-definition) +* [Delete Location Custom Attribute Definition](../../doc/api/location-custom-attributes.md#delete-location-custom-attribute-definition) +* [Retrieve Location Custom Attribute Definition](../../doc/api/location-custom-attributes.md#retrieve-location-custom-attribute-definition) +* [Update Location Custom Attribute Definition](../../doc/api/location-custom-attributes.md#update-location-custom-attribute-definition) +* [Bulk Delete Location Custom Attributes](../../doc/api/location-custom-attributes.md#bulk-delete-location-custom-attributes) +* [Bulk Upsert Location Custom Attributes](../../doc/api/location-custom-attributes.md#bulk-upsert-location-custom-attributes) +* [List Location Custom Attributes](../../doc/api/location-custom-attributes.md#list-location-custom-attributes) +* [Delete Location Custom Attribute](../../doc/api/location-custom-attributes.md#delete-location-custom-attribute) +* [Retrieve Location Custom Attribute](../../doc/api/location-custom-attributes.md#retrieve-location-custom-attribute) +* [Upsert Location Custom Attribute](../../doc/api/location-custom-attributes.md#upsert-location-custom-attribute) + + +# List Location Custom Attribute Definitions + +Lists the location-related [custom attribute definitions](../../doc/models/custom-attribute-definition.md) 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`. + +```python +def list_location_custom_attribute_definitions(self, + visibility_filter=None, + limit=None, + cursor=None) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `visibility_filter` | [`str (Visibility Filter)`](../../doc/models/visibility-filter.md) | Query, Optional | Filters the `CustomAttributeDefinition` results by their `visibility` values. | +| `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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | +| `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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | + +## Response Type + +[`List Location Custom Attribute Definitions Response`](../../doc/models/list-location-custom-attribute-definitions-response.md) + +## Example Usage + +```python +result = location_custom_attributes_api.list_location_custom_attribute_definitions() + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Create Location Custom Attribute Definition + +Creates a location-related [custom attribute definition](../../doc/models/custom-attribute-definition.md) for a Square seller account. +Use this endpoint to define a custom attribute that can be associated with locations. +A custom attribute definition specifies the `key`, `visibility`, `schema`, and other properties +for a custom attribute. After the definition is created, you can call +[UpsertLocationCustomAttribute](../../doc/api/location-custom-attributes.md#upsert-location-custom-attribute) or +[BulkUpsertLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-upsert-location-custom-attributes) +to set the custom attribute for locations. + +```python +def create_location_custom_attribute_definition(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Create Location Custom Attribute Definition Request`](../../doc/models/create-location-custom-attribute-definition-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +[`Create Location Custom Attribute Definition Response`](../../doc/models/create-location-custom-attribute-definition-response.md) + +## Example Usage + +```python +body = {} +body['custom_attribute_definition'] = {} +body['custom_attribute_definition']['key'] = 'bestseller' +body['custom_attribute_definition']['name'] = 'Bestseller' +body['custom_attribute_definition']['description'] = 'Bestselling item at location' +body['custom_attribute_definition']['visibility'] = 'VISIBILITY_READ_WRITE_VALUES' + +result = location_custom_attributes_api.create_location_custom_attribute_definition(body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Delete Location Custom Attribute Definition + +Deletes a location-related [custom attribute definition](../../doc/models/custom-attribute-definition.md) from a Square seller account. +Deleting a custom attribute definition also deletes the corresponding custom attribute from +all locations. +Only the definition owner can delete a custom attribute definition. + +```python +def delete_location_custom_attribute_definition(self, + key) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `key` | `string` | Template, Required | The key of the custom attribute definition to delete. | + +## Response Type + +[`Delete Location Custom Attribute Definition Response`](../../doc/models/delete-location-custom-attribute-definition-response.md) + +## Example Usage + +```python +key = 'key0' + +result = location_custom_attributes_api.delete_location_custom_attribute_definition(key) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Retrieve Location Custom Attribute Definition + +Retrieves a location-related [custom attribute definition](../../doc/models/custom-attribute-definition.md) 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`. + +```python +def retrieve_location_custom_attribute_definition(self, + key, + version=None) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `key` | `string` | Template, Required | The key of the custom attribute definition to retrieve. If the requesting application
is not the definition owner, you must use the qualified key. | +| `version` | `int` | Query, Optional | The current version of the custom attribute definition, which is used for strongly consistent
reads to guarantee that you receive the most up-to-date data. When included in the request,
Square returns the specified version or a higher version if one exists. If the specified version
is higher than the current version, Square returns a `BAD_REQUEST` error. | + +## Response Type + +[`Retrieve Location Custom Attribute Definition Response`](../../doc/models/retrieve-location-custom-attribute-definition-response.md) + +## Example Usage + +```python +key = 'key0' + +result = location_custom_attributes_api.retrieve_location_custom_attribute_definition(key) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Update Location Custom Attribute Definition + +Updates a location-related [custom attribute definition](../../doc/models/custom-attribute-definition.md) for a Square seller account. +Use this endpoint to update the following fields: `name`, `description`, `visibility`, or the +`schema` for a `Selection` data type. +Only the definition owner can update a custom attribute definition. + +```python +def update_location_custom_attribute_definition(self, + key, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `key` | `string` | Template, Required | The key of the custom attribute definition to update. | +| `body` | [`Update Location Custom Attribute Definition Request`](../../doc/models/update-location-custom-attribute-definition-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +[`Update Location Custom Attribute Definition Response`](../../doc/models/update-location-custom-attribute-definition-response.md) + +## Example Usage + +```python +key = 'key0' +body = {} +body['custom_attribute_definition'] = {} +body['custom_attribute_definition']['description'] = 'Update the description as desired.' +body['custom_attribute_definition']['visibility'] = 'VISIBILITY_READ_ONLY' + +result = location_custom_attributes_api.update_location_custom_attribute_definition(key, body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Bulk Delete Location Custom Attributes + +Deletes [custom attributes](../../doc/models/custom-attribute.md) for locations as a bulk operation. +To delete a custom attribute owned by another application, the `visibility` setting must be +`VISIBILITY_READ_WRITE_VALUES`. + +```python +def bulk_delete_location_custom_attributes(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Bulk Delete Location Custom Attributes Request`](../../doc/models/bulk-delete-location-custom-attributes-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +[`Bulk Delete Location Custom Attributes Response`](../../doc/models/bulk-delete-location-custom-attributes-response.md) + +## Example Usage + +```python +body = {} +body['values'] = {} + +result = location_custom_attributes_api.bulk_delete_location_custom_attributes(body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Bulk Upsert Location Custom Attributes + +Creates or updates [custom attributes](../../doc/models/custom-attribute.md) for locations as a bulk operation. +Use this endpoint to set the value of one or more custom attributes for one or more locations. +A custom attribute is based on a custom attribute definition in a Square seller account, which is +created using the [CreateLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#create-location-custom-attribute-definition) endpoint. +This `BulkUpsertLocationCustomAttributes` 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 a location 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`. + +```python +def bulk_upsert_location_custom_attributes(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Bulk Upsert Location Custom Attributes Request`](../../doc/models/bulk-upsert-location-custom-attributes-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +[`Bulk Upsert Location Custom Attributes Response`](../../doc/models/bulk-upsert-location-custom-attributes-response.md) + +## Example Usage + +```python +body = {} +body['values'] = {} +body['values']['location_id'] = None +body['values']['custom_attribute'] = {} + +result = location_custom_attributes_api.bulk_upsert_location_custom_attributes(body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# List Location Custom Attributes + +Lists the [custom attributes](../../doc/models/custom-attribute.md) associated with a location. +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`. + +```python +def list_location_custom_attributes(self, + location_id, + visibility_filter=None, + limit=None, + cursor=None, + with_definitions=False) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `string` | Template, Required | The ID of the target [location](../../doc/models/location.md). | +| `visibility_filter` | [`str (Visibility Filter)`](../../doc/models/visibility-filter.md) | Query, Optional | Filters the `CustomAttributeDefinition` results by their `visibility` values. | +| `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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | +| `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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | +| `with_definitions` | `bool` | Query, Optional | Indicates whether to return the [custom attribute definition](../../doc/models/custom-attribute-definition.md) 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 + +[`List Location Custom Attributes Response`](../../doc/models/list-location-custom-attributes-response.md) + +## Example Usage + +```python +location_id = 'location_id4' +with_definitions = False + +result = location_custom_attributes_api.list_location_custom_attributes(location_id, None, None, None, with_definitions) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Delete Location Custom Attribute + +Deletes a [custom attribute](../../doc/models/custom-attribute.md) associated with a location. +To delete a custom attribute owned by another application, the `visibility` setting must be +`VISIBILITY_READ_WRITE_VALUES`. + +```python +def delete_location_custom_attribute(self, + location_id, + key) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `string` | Template, Required | The ID of the target [location](../../doc/models/location.md). | +| `key` | `string` | Template, Required | The key of the custom attribute to delete. This key must match the `key` of a custom
attribute definition in the Square seller account. If the requesting application is not the
definition owner, you must use the qualified key. | + +## Response Type + +[`Delete Location Custom Attribute Response`](../../doc/models/delete-location-custom-attribute-response.md) + +## Example Usage + +```python +location_id = 'location_id4' +key = 'key0' + +result = location_custom_attributes_api.delete_location_custom_attribute(location_id, key) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Retrieve Location Custom Attribute + +Retrieves a [custom attribute](../../doc/models/custom-attribute.md) associated with a location. +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`. + +```python +def retrieve_location_custom_attribute(self, + location_id, + key, + with_definition=False, + version=None) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `string` | Template, Required | The ID of the target [location](../../doc/models/location.md). | +| `key` | `string` | Template, Required | The key of the custom attribute to retrieve. This key must match the `key` of a custom
attribute definition in the Square seller account. If the requesting application is not the
definition owner, you must use the qualified key. | +| `with_definition` | `bool` | Query, Optional | Indicates whether to return the [custom attribute definition](../../doc/models/custom-attribute-definition.md) in the `definition` field of
the custom attribute. Set this parameter to `true` to get the name and description of the custom
attribute, information about the data type, or other definition details. The default value is `false`.
**Default**: `False` | +| `version` | `int` | Query, Optional | The current version of the custom attribute, which is used for strongly consistent reads to
guarantee that you receive the most up-to-date data. When included in the request, Square
returns the specified version or a higher version if one exists. If the specified version is
higher than the current version, Square returns a `BAD_REQUEST` error. | + +## Response Type + +[`Retrieve Location Custom Attribute Response`](../../doc/models/retrieve-location-custom-attribute-response.md) + +## Example Usage + +```python +location_id = 'location_id4' +key = 'key0' +with_definition = False + +result = location_custom_attributes_api.retrieve_location_custom_attribute(location_id, key, with_definition) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Upsert Location Custom Attribute + +Creates or updates a [custom attribute](../../doc/models/custom-attribute.md) for a location. +Use this endpoint to set the value of a custom attribute for a specified location. +A custom attribute is based on a custom attribute definition in a Square seller account, which +is created using the [CreateLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#create-location-custom-attribute-definition) endpoint. +To create or update a custom attribute owned by another application, the `visibility` setting +must be `VISIBILITY_READ_WRITE_VALUES`. + +```python +def upsert_location_custom_attribute(self, + location_id, + key, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `string` | Template, Required | The ID of the target [location](../../doc/models/location.md). | +| `key` | `string` | Template, Required | The key of the custom attribute to create or update. This key must match the `key` of a
custom attribute definition in the Square seller account. If the requesting application is not
the definition owner, you must use the qualified key. | +| `body` | [`Upsert Location Custom Attribute Request`](../../doc/models/upsert-location-custom-attribute-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +[`Upsert Location Custom Attribute Response`](../../doc/models/upsert-location-custom-attribute-response.md) + +## Example Usage + +```python +location_id = 'location_id4' +key = 'key0' +body = {} +body['custom_attribute'] = {} + +result = location_custom_attributes_api.upsert_location_custom_attribute(location_id, key, body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + diff --git a/doc/client.md b/doc/client.md index 182f7f1e..f947fc32 100644 --- a/doc/client.md +++ b/doc/client.md @@ -5,7 +5,7 @@ The following parameters are configurable for the API Client: | Parameter | Type | Description | | --- | --- | --- | -| `square_version` | `string` | Square Connect API versions
*Default*: `'2022-12-14'` | +| `square_version` | `string` | Square Connect API versions
*Default*: `'2023-01-19'` | | `custom_url` | `string` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
*Default*: `'https://connect.squareup.com'` | | `environment` | `string` | The API environment.
**Default: `production`** | | `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests | @@ -26,7 +26,7 @@ The API client can be initialized as follows: from square.client import Client client = Client( - square_version='2022-12-14', + square_version='2023-01-19', access_token='AccessToken', environment='production', custom_url = 'https://connect.squareup.com',) @@ -52,7 +52,7 @@ import jsonpickle from square.client import Client client = Client( - square_version='2022-12-14', + square_version='2023-01-19', access_token='AccessToken',) locations_api = client.locations @@ -95,6 +95,7 @@ The gateway for the SDK. This class acts as a factory for the Apis and also hold | invoices | Gets InvoicesApi | | labor | Gets LaborApi | | locations | Gets LocationsApi | +| location_custom_attributes | Gets LocationCustomAttributesApi | | checkout | Gets CheckoutApi | | transactions | Gets TransactionsApi | | loyalty | Gets LoyaltyApi | diff --git a/doc/models/break-type.md b/doc/models/break-type.md index c36c4256..2ec01dc3 100644 --- a/doc/models/break-type.md +++ b/doc/models/break-type.md @@ -15,7 +15,7 @@ instances on a `Shift`. | `id` | `string` | Optional | The UUID for this object.
**Constraints**: *Maximum Length*: `255` | | `location_id` | `string` | Required | The ID of the business location this type of break applies to.
**Constraints**: *Minimum Length*: `1` | | `break_name` | `string` | Required | A human-readable name for this type of break. The name is displayed to
employees in Square products.
**Constraints**: *Minimum Length*: `1` | -| `expected_duration` | `string` | Required | Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
this break. Precision less than minutes is truncated.
**Constraints**: *Minimum Length*: `1` | +| `expected_duration` | `string` | Required | Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
this break. Precision less than minutes is truncated.

Example for break expected duration of 15 minutes: T15M
**Constraints**: *Minimum Length*: `1` | | `is_paid` | `bool` | Required | Whether this break counts towards time worked for compensation
purposes. | | `version` | `int` | Optional | Used for resolving concurrency issues. The request fails if the version
provided does not match the server version at the time of the request. If a value is not
provided, Square's servers execute a "blind" write; potentially
overwriting another writer's data. | | `created_at` | `string` | Optional | A read-only timestamp in RFC 3339 format. | diff --git a/doc/models/bulk-delete-location-custom-attributes-request-location-custom-attribute-delete-request.md b/doc/models/bulk-delete-location-custom-attributes-request-location-custom-attribute-delete-request.md new file mode 100644 index 00000000..2a872a68 --- /dev/null +++ b/doc/models/bulk-delete-location-custom-attributes-request-location-custom-attribute-delete-request.md @@ -0,0 +1,23 @@ + +# Bulk Delete Location Custom Attributes Request Location Custom Attribute Delete Request + +Represents an individual delete request in a [BulkDeleteLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-delete-location-custom-attributes) +request. An individual request contains an optional ID of the associated custom attribute definition +and optional key of the associated custom attribute definition. + +## Structure + +`Bulk Delete Location Custom Attributes Request Location Custom Attribute Delete Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `key` | `string` | Optional | The key of the associated custom attribute definition.
Represented as a qualified key if the requesting app is not the definition owner.
**Constraints**: *Pattern*: `^([a-zA-Z0-9_-]+:)?[a-zA-Z0-9_-]{1,60}$` | + +## Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/bulk-delete-location-custom-attributes-request.md b/doc/models/bulk-delete-location-custom-attributes-request.md new file mode 100644 index 00000000..dd7c395f --- /dev/null +++ b/doc/models/bulk-delete-location-custom-attributes-request.md @@ -0,0 +1,36 @@ + +# Bulk Delete Location Custom Attributes Request + +Represents a [BulkDeleteLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-delete-location-custom-attributes) request. + +## Structure + +`Bulk Delete Location Custom Attributes Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `values` | [`Dict`](../../doc/models/bulk-delete-location-custom-attributes-request-location-custom-attribute-delete-request.md) | Required | The data used to update the `CustomAttribute` objects.
The keys must be unique and are used to map to the corresponding response. | + +## Example (as JSON) + +```json +{ + "values": { + "id1": { + "key": "bestseller", + "location_id": "L0TBCBTB7P8RQ" + }, + "id2": { + "key": "bestseller", + "location_id": "L9XMD04V3STJX" + }, + "id3": { + "key": "phone-number", + "location_id": "L0TBCBTB7P8RQ" + } + } +} +``` + diff --git a/doc/models/bulk-delete-location-custom-attributes-response-location-custom-attribute-delete-response.md b/doc/models/bulk-delete-location-custom-attributes-response-location-custom-attribute-delete-response.md new file mode 100644 index 00000000..a68dfce2 --- /dev/null +++ b/doc/models/bulk-delete-location-custom-attributes-response-location-custom-attribute-delete-response.md @@ -0,0 +1,26 @@ + +# Bulk Delete Location Custom Attributes Response Location Custom Attribute Delete Response + +Represents an individual delete response in a [BulkDeleteLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-delete-location-custom-attributes) +request. + +## Structure + +`Bulk Delete Location Custom Attributes Response Location Custom Attribute Delete Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `string` | Optional | The ID of the location associated with the custom attribute. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Errors that occurred while processing the individual LocationCustomAttributeDeleteRequest request | + +## Example (as JSON) + +```json +{ + "errors": [], + "location_id": "L0TBCBTB7P8RQ" +} +``` + diff --git a/doc/models/bulk-delete-location-custom-attributes-response.md b/doc/models/bulk-delete-location-custom-attributes-response.md new file mode 100644 index 00000000..d0215045 --- /dev/null +++ b/doc/models/bulk-delete-location-custom-attributes-response.md @@ -0,0 +1,38 @@ + +# Bulk Delete Location Custom Attributes Response + +Represents a [BulkDeleteLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-delete-location-custom-attributes) response, +which contains a map of responses that each corresponds to an individual delete request. + +## Structure + +`Bulk Delete Location Custom Attributes Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `values` | [`Dict`](../../doc/models/bulk-delete-location-custom-attributes-response-location-custom-attribute-delete-response.md) | Required | A map of responses that correspond to individual delete requests. Each response has the
same key as the corresponding request. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "values": { + "id1": { + "errors": [], + "location_id": "L0TBCBTB7P8RQ" + }, + "id2": { + "errors": [], + "location_id": "L9XMD04V3STJX" + }, + "id3": { + "errors": [], + "location_id": "L0TBCBTB7P8RQ" + } + } +} +``` + diff --git a/doc/models/bulk-upsert-location-custom-attributes-request-location-custom-attribute-upsert-request.md b/doc/models/bulk-upsert-location-custom-attributes-request-location-custom-attribute-upsert-request.md new file mode 100644 index 00000000..79c77a7e --- /dev/null +++ b/doc/models/bulk-upsert-location-custom-attributes-request-location-custom-attribute-upsert-request.md @@ -0,0 +1,35 @@ + +# Bulk Upsert Location Custom Attributes Request Location Custom Attribute Upsert Request + +Represents an individual upsert request in a [BulkUpsertLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-upsert-location-custom-attributes) +request. An individual request contains a location ID, the custom attribute to create or update, +and an optional idempotency key. + +## Structure + +`Bulk Upsert Location Custom Attributes Request Location Custom Attribute Upsert Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `string` | Required | The ID of the target [location](../../doc/models/location.md).
**Constraints**: *Minimum Length*: `1` | +| `custom_attribute` | [`Custom Attribute`](../../doc/models/custom-attribute.md) | Required | A custom attribute value. Each custom attribute value has a corresponding
`CustomAttributeDefinition` object. | +| `idempotency_key` | `string` | Optional | A unique identifier for this individual upsert request, used to ensure idempotency.
For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
**Constraints**: *Maximum Length*: `45` | + +## Example (as JSON) + +```json +{ + "location_id": "location_id4", + "custom_attribute": { + "key": null, + "value": null, + "version": null, + "visibility": null, + "definition": null + }, + "idempotency_key": null +} +``` + diff --git a/doc/models/bulk-upsert-location-custom-attributes-request.md b/doc/models/bulk-upsert-location-custom-attributes-request.md new file mode 100644 index 00000000..a2b7247d --- /dev/null +++ b/doc/models/bulk-upsert-location-custom-attributes-request.md @@ -0,0 +1,57 @@ + +# Bulk Upsert Location Custom Attributes Request + +Represents a [BulkUpsertLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-upsert-location-custom-attributes) request. + +## Structure + +`Bulk Upsert Location Custom Attributes Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `values` | [`Dict`](../../doc/models/bulk-upsert-location-custom-attributes-request-location-custom-attribute-upsert-request.md) | Required | A map containing 1 to 25 individual upsert requests. For each request, provide an
arbitrary ID that is unique for this `BulkUpsertLocationCustomAttributes` request and the
information needed to create or update a custom attribute. | + +## Example (as JSON) + +```json +{ + "values": { + "key0": { + "location_id": "location_id4", + "custom_attribute": { + "key": null, + "value": null, + "version": null, + "visibility": null, + "definition": null + }, + "idempotency_key": null + }, + "key1": { + "location_id": "location_id5", + "custom_attribute": { + "key": null, + "value": null, + "version": null, + "visibility": null, + "definition": null + }, + "idempotency_key": null + }, + "key2": { + "location_id": "location_id6", + "custom_attribute": { + "key": null, + "value": null, + "version": null, + "visibility": null, + "definition": null + }, + "idempotency_key": null + } + } +} +``` + diff --git a/doc/models/bulk-upsert-location-custom-attributes-response-location-custom-attribute-upsert-response.md b/doc/models/bulk-upsert-location-custom-attributes-response-location-custom-attribute-upsert-response.md new file mode 100644 index 00000000..99abe5b0 --- /dev/null +++ b/doc/models/bulk-upsert-location-custom-attributes-response-location-custom-attribute-upsert-response.md @@ -0,0 +1,27 @@ + +# Bulk Upsert Location Custom Attributes Response Location Custom Attribute Upsert Response + +Represents a response for an individual upsert request in a [BulkUpsertLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-upsert-location-custom-attributes) operation. + +## Structure + +`Bulk Upsert Location Custom Attributes Response Location Custom Attribute Upsert Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `location_id` | `string` | Optional | The ID of the location associated with the custom attribute. | +| `custom_attribute` | [`Custom Attribute`](../../doc/models/custom-attribute.md) | Optional | A custom attribute value. Each custom attribute value has a corresponding
`CustomAttributeDefinition` object. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred while processing the individual request. | + +## Example (as JSON) + +```json +{ + "location_id": null, + "custom_attribute": null, + "errors": null +} +``` + diff --git a/doc/models/bulk-upsert-location-custom-attributes-response.md b/doc/models/bulk-upsert-location-custom-attributes-response.md new file mode 100644 index 00000000..248734b0 --- /dev/null +++ b/doc/models/bulk-upsert-location-custom-attributes-response.md @@ -0,0 +1,26 @@ + +# Bulk Upsert Location Custom Attributes Response + +Represents a [BulkUpsertLocationCustomAttributes](../../doc/api/location-custom-attributes.md#bulk-upsert-location-custom-attributes) response, +which contains a map of responses that each corresponds to an individual upsert request. + +## Structure + +`Bulk Upsert Location Custom Attributes Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `values` | [`Dict`](../../doc/models/bulk-upsert-location-custom-attributes-response-location-custom-attribute-upsert-response.md) | Optional | A map of responses that correspond to individual upsert requests. Each response has the
same ID as the corresponding request and contains either a `location_id` and `custom_attribute` or an `errors` field. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "values": null, + "errors": null +} +``` + diff --git a/doc/models/create-location-custom-attribute-definition-request.md b/doc/models/create-location-custom-attribute-definition-request.md new file mode 100644 index 00000000..1dacf6fa --- /dev/null +++ b/doc/models/create-location-custom-attribute-definition-request.md @@ -0,0 +1,30 @@ + +# Create Location Custom Attribute Definition Request + +Represents a [CreateLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#create-location-custom-attribute-definition) request. + +## Structure + +`Create Location Custom Attribute Definition Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute_definition` | [`Custom Attribute Definition`](../../doc/models/custom-attribute-definition.md) | Required | Represents a definition for custom attribute values. A custom attribute definition
specifies the key, visibility, schema, and other properties for a custom attribute. | +| `idempotency_key` | `string` | Optional | A unique identifier for this request, used to ensure idempotency. For more information,
see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
**Constraints**: *Maximum Length*: `45` | + +## Example (as JSON) + +```json +{ + "custom_attribute_definition": { + "description": "Bestselling item at location", + "key": "bestseller", + "name": "Bestseller", + "schema": null, + "visibility": "VISIBILITY_READ_WRITE_VALUES" + } +} +``` + diff --git a/doc/models/create-location-custom-attribute-definition-response.md b/doc/models/create-location-custom-attribute-definition-response.md new file mode 100644 index 00000000..5e0a4f5a --- /dev/null +++ b/doc/models/create-location-custom-attribute-definition-response.md @@ -0,0 +1,34 @@ + +# Create Location Custom Attribute Definition Response + +Represents a [CreateLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#create-location-custom-attribute-definition) response. +Either `custom_attribute_definition` or `errors` is present in the response. + +## Structure + +`Create Location Custom Attribute Definition Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute_definition` | [`Custom Attribute Definition`](../../doc/models/custom-attribute-definition.md) | Optional | Represents a definition for custom attribute values. A custom attribute definition
specifies the key, visibility, schema, and other properties for a custom attribute. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "custom_attribute_definition": { + "created_at": "2022-12-02T19:06:36.559Z", + "description": "Bestselling item at location", + "key": "bestseller", + "name": "Bestseller", + "schema": null, + "updated_at": "2022-12-02T19:06:36.559Z", + "version": 1, + "visibility": "VISIBILITY_READ_WRITE_VALUES" + } +} +``` + diff --git a/doc/models/delete-location-custom-attribute-definition-response.md b/doc/models/delete-location-custom-attribute-definition-response.md new file mode 100644 index 00000000..126f4916 --- /dev/null +++ b/doc/models/delete-location-custom-attribute-definition-response.md @@ -0,0 +1,21 @@ + +# Delete Location Custom Attribute Definition Response + +Represents a response from a delete request containing error messages if there are any. + +## Structure + +`Delete Location Custom Attribute Definition Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/delete-location-custom-attribute-response.md b/doc/models/delete-location-custom-attribute-response.md new file mode 100644 index 00000000..48a07cf9 --- /dev/null +++ b/doc/models/delete-location-custom-attribute-response.md @@ -0,0 +1,22 @@ + +# Delete Location Custom Attribute Response + +Represents a [DeleteLocationCustomAttribute](../../doc/api/location-custom-attributes.md#delete-location-custom-attribute) response. +Either an empty object `{}` (for a successful deletion) or `errors` is present in the response. + +## Structure + +`Delete Location Custom Attribute Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{} +``` + diff --git a/doc/models/gift-card-activity-transfer-balance-from.md b/doc/models/gift-card-activity-transfer-balance-from.md new file mode 100644 index 00000000..9f23dab5 --- /dev/null +++ b/doc/models/gift-card-activity-transfer-balance-from.md @@ -0,0 +1,28 @@ + +# Gift Card Activity Transfer Balance From + +Represents details about a `TRANSFER_BALANCE_FROM` [gift card activity type](../../doc/models/gift-card-activity-type.md). + +## Structure + +`Gift Card Activity Transfer Balance From` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `transfer_to_gift_card_id` | `string` | Required | The ID of the gift card to which the specified amount was transferred. | +| `amount_money` | [`Money`](../../doc/models/money.md) | Required | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | + +## Example (as JSON) + +```json +{ + "transfer_to_gift_card_id": "transfer_to_gift_card_id6", + "amount_money": { + "amount": null, + "currency": null + } +} +``` + diff --git a/doc/models/gift-card-activity-transfer-balance-to.md b/doc/models/gift-card-activity-transfer-balance-to.md new file mode 100644 index 00000000..2bc5fc3b --- /dev/null +++ b/doc/models/gift-card-activity-transfer-balance-to.md @@ -0,0 +1,28 @@ + +# Gift Card Activity Transfer Balance To + +Represents details about a `TRANSFER_BALANCE_TO` [gift card activity type](../../doc/models/gift-card-activity-type.md). + +## Structure + +`Gift Card Activity Transfer Balance To` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `transfer_from_gift_card_id` | `string` | Required | The ID of the gift card from which the specified amount was transferred. | +| `amount_money` | [`Money`](../../doc/models/money.md) | Required | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | + +## Example (as JSON) + +```json +{ + "transfer_from_gift_card_id": "transfer_from_gift_card_id0", + "amount_money": { + "amount": null, + "currency": null + } +} +``` + diff --git a/doc/models/gift-card-activity-type.md b/doc/models/gift-card-activity-type.md index e35cc247..2b22419f 100644 --- a/doc/models/gift-card-activity-type.md +++ b/doc/models/gift-card-activity-type.md @@ -24,4 +24,6 @@ Indicates the type of [gift card activity](../../doc/models/gift-card-activity.m | `BLOCK` | Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities
are managed by Square and cannot be created using the Gift Card Activities API. | | `UNBLOCK` | Unblocked a gift card, which enables it to resume balance-changing activities. `UNBLOCK`
activities are managed by Square and cannot be created using the Gift Card Activities API. | | `IMPORT_REVERSAL` | Reversed the import of a third-party gift card, which sets the gift card state to
`PENDING` and clears the balance. `IMPORT_REVERSAL` activities are managed by Square and
cannot be created using the Gift Card Activities API. | +| `TRANSFER_BALANCE_FROM` | Deducted money from a gift card as the result of a transfer to the balance of another gift card.
`TRANSFER_BALANCE_FROM` activities are managed by Square and cannot be created using the Gift Card Activities API. | +| `TRANSFER_BALANCE_TO` | Added money to a gift card as the result of a transfer from the balance of another gift card.
`TRANSFER_BALANCE_TO` activities are managed by Square and cannot be created using the Gift Card Activities API. | diff --git a/doc/models/gift-card-activity.md b/doc/models/gift-card-activity.md index c2f56a51..dd48bedd 100644 --- a/doc/models/gift-card-activity.md +++ b/doc/models/gift-card-activity.md @@ -33,6 +33,8 @@ includes a `redeem_activity_details` field that contains information about the r | `block_activity_details` | [`Gift Card Activity Block`](../../doc/models/gift-card-activity-block.md) | Optional | Represents details about a `BLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). | | `unblock_activity_details` | [`Gift Card Activity Unblock`](../../doc/models/gift-card-activity-unblock.md) | Optional | Represents details about an `UNBLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). | | `import_reversal_activity_details` | [`Gift Card Activity Import Reversal`](../../doc/models/gift-card-activity-import-reversal.md) | Optional | Represents details about an `IMPORT_REVERSAL` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `transfer_balance_to_activity_details` | [`Gift Card Activity Transfer Balance To`](../../doc/models/gift-card-activity-transfer-balance-to.md) | Optional | Represents details about a `TRANSFER_BALANCE_TO` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `transfer_balance_from_activity_details` | [`Gift Card Activity Transfer Balance From`](../../doc/models/gift-card-activity-transfer-balance-from.md) | Optional | Represents details about a `TRANSFER_BALANCE_FROM` [gift card activity type](../../doc/models/gift-card-activity-type.md). | ## Example (as JSON) @@ -55,7 +57,9 @@ includes a `redeem_activity_details` field that contains information about the r "import_activity_details": null, "block_activity_details": null, "unblock_activity_details": null, - "import_reversal_activity_details": null + "import_reversal_activity_details": null, + "transfer_balance_to_activity_details": null, + "transfer_balance_from_activity_details": null } ``` diff --git a/doc/models/list-location-custom-attribute-definitions-request.md b/doc/models/list-location-custom-attribute-definitions-request.md new file mode 100644 index 00000000..843f4c10 --- /dev/null +++ b/doc/models/list-location-custom-attribute-definitions-request.md @@ -0,0 +1,27 @@ + +# List Location Custom Attribute Definitions Request + +Represents a [ListLocationCustomAttributeDefinitions](../../doc/api/location-custom-attributes.md#list-location-custom-attribute-definitions) request. + +## Structure + +`List Location Custom Attribute Definitions Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `visibility_filter` | [`str (Visibility Filter)`](../../doc/models/visibility-filter.md) | Optional | Enumeration of visibility-filter values used to set the ability to view custom attributes or custom attribute definitions. | +| `limit` | `int` | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
**Constraints**: `>= 1`, `<= 100` | +| `cursor` | `string` | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | + +## Example (as JSON) + +```json +{ + "visibility_filter": null, + "limit": null, + "cursor": null +} +``` + diff --git a/doc/models/list-location-custom-attribute-definitions-response.md b/doc/models/list-location-custom-attribute-definitions-response.md new file mode 100644 index 00000000..c2ae6594 --- /dev/null +++ b/doc/models/list-location-custom-attribute-definitions-response.md @@ -0,0 +1,49 @@ + +# List Location Custom Attribute Definitions Response + +Represents a [ListLocationCustomAttributeDefinitions](../../doc/api/location-custom-attributes.md#list-location-custom-attribute-definitions) response. +Either `custom_attribute_definitions`, an empty object, or `errors` is present in the response. +If additional results are available, the `cursor` field is also present along with `custom_attribute_definitions`. + +## Structure + +`List Location Custom Attribute Definitions Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute_definitions` | [`List of Custom Attribute Definition`](../../doc/models/custom-attribute-definition.md) | Optional | The retrieved custom attribute definitions. If no custom attribute definitions are found,
Square returns an empty object (`{}`). | +| `cursor` | `string` | Optional | The cursor to provide in your next call to this endpoint to retrieve the next page of
results for your original request. This field is present only if the request succeeded and
additional results are available. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "cursor": "ImfNzWVSiAYyiAR4gEcxDJ75KZAOSjX8H2BVHUTR0ofCtp4SdYvrUKbwYY2aCH2WqZ2FsfAuylEVUlTfaINg3ecIlFpP9Y5Ie66w9NSg9nqdI5fCJ6qdH2s0za5m2plFonsjIuFaoN89j78ROUwuSOzD6mFZPcJHhJ0CxEKc0SBH", + "custom_attribute_definitions": [ + { + "created_at": "2022-12-02T19:50:21.832Z", + "description": "Location's phone number", + "key": "phone-number", + "name": "phone number", + "schema": null, + "updated_at": "2022-12-02T19:50:21.832Z", + "version": 1, + "visibility": "VISIBILITY_READ_ONLY" + }, + { + "created_at": "2022-12-02T19:06:36.559Z", + "description": "Bestselling item at location", + "key": "bestseller", + "name": "Bestseller", + "schema": null, + "updated_at": "2022-12-03T10:17:52.341Z", + "version": 4, + "visibility": "VISIBILITY_READ_WRITE_VALUES" + } + ] +} +``` + diff --git a/doc/models/list-location-custom-attributes-request.md b/doc/models/list-location-custom-attributes-request.md new file mode 100644 index 00000000..e6744ec4 --- /dev/null +++ b/doc/models/list-location-custom-attributes-request.md @@ -0,0 +1,29 @@ + +# List Location Custom Attributes Request + +Represents a [ListLocationCustomAttributes](../../doc/api/location-custom-attributes.md#list-location-custom-attributes) request. + +## Structure + +`List Location Custom Attributes Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `visibility_filter` | [`str (Visibility Filter)`](../../doc/models/visibility-filter.md) | Optional | Enumeration of visibility-filter values used to set the ability to view custom attributes or custom attribute definitions. | +| `limit` | `int` | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
**Constraints**: `>= 1`, `<= 100` | +| `cursor` | `string` | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | +| `with_definitions` | `bool` | Optional | Indicates whether to return the [custom attribute definition](../../doc/models/custom-attribute-definition.md) 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`. | + +## Example (as JSON) + +```json +{ + "visibility_filter": null, + "limit": null, + "cursor": null, + "with_definitions": null +} +``` + diff --git a/doc/models/list-location-custom-attributes-response.md b/doc/models/list-location-custom-attributes-response.md new file mode 100644 index 00000000..6efddba1 --- /dev/null +++ b/doc/models/list-location-custom-attributes-response.md @@ -0,0 +1,29 @@ + +# List Location Custom Attributes Response + +Represents a [ListLocationCustomAttributes](../../doc/api/location-custom-attributes.md#list-location-custom-attributes) response. +Either `custom_attributes`, an empty object, or `errors` is present in the response. If additional +results are available, the `cursor` field is also present along with `custom_attributes`. + +## Structure + +`List Location Custom Attributes Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attributes` | [`List of Custom Attribute`](../../doc/models/custom-attribute.md) | Optional | The retrieved custom attributes. If `with_definitions` was set to `true` in the request,
the custom attribute definition is returned in the `definition` field of each custom attribute.
If no custom attributes are found, Square returns an empty object (`{}`). | +| `cursor` | `string` | Optional | The cursor to use in your next call to this endpoint to retrieve the next page of results
for your original request. This field is present only if the request succeeded and additional
results are available. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "custom_attributes": null, + "cursor": null, + "errors": null +} +``` + diff --git a/doc/models/retrieve-location-custom-attribute-definition-request.md b/doc/models/retrieve-location-custom-attribute-definition-request.md new file mode 100644 index 00000000..03b7ce64 --- /dev/null +++ b/doc/models/retrieve-location-custom-attribute-definition-request.md @@ -0,0 +1,23 @@ + +# Retrieve Location Custom Attribute Definition Request + +Represents a [RetrieveLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#retrieve-location-custom-attribute-definition) request. + +## Structure + +`Retrieve Location Custom Attribute Definition Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `version` | `int` | Optional | The current version of the custom attribute definition, which is used for strongly consistent
reads to guarantee that you receive the most up-to-date data. When included in the request,
Square returns the specified version or a higher version if one exists. If the specified version
is higher than the current version, Square returns a `BAD_REQUEST` error. | + +## Example (as JSON) + +```json +{ + "version": null +} +``` + diff --git a/doc/models/retrieve-location-custom-attribute-definition-response.md b/doc/models/retrieve-location-custom-attribute-definition-response.md new file mode 100644 index 00000000..d8675e4d --- /dev/null +++ b/doc/models/retrieve-location-custom-attribute-definition-response.md @@ -0,0 +1,34 @@ + +# Retrieve Location Custom Attribute Definition Response + +Represents a [RetrieveLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#retrieve-location-custom-attribute-definition) response. +Either `custom_attribute_definition` or `errors` is present in the response. + +## Structure + +`Retrieve Location Custom Attribute Definition Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute_definition` | [`Custom Attribute Definition`](../../doc/models/custom-attribute-definition.md) | Optional | Represents a definition for custom attribute values. A custom attribute definition
specifies the key, visibility, schema, and other properties for a custom attribute. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "custom_attribute_definition": { + "created_at": "2022-12-02T19:06:36.559Z", + "description": "Bestselling item at location", + "key": "bestseller", + "name": "Bestseller", + "schema": null, + "updated_at": "2022-12-02T19:06:36.559Z", + "version": 1, + "visibility": "VISIBILITY_READ_WRITE_VALUES" + } +} +``` + diff --git a/doc/models/retrieve-location-custom-attribute-request.md b/doc/models/retrieve-location-custom-attribute-request.md new file mode 100644 index 00000000..4bdd7738 --- /dev/null +++ b/doc/models/retrieve-location-custom-attribute-request.md @@ -0,0 +1,25 @@ + +# Retrieve Location Custom Attribute Request + +Represents a [RetrieveLocationCustomAttribute](../../doc/api/location-custom-attributes.md#retrieve-location-custom-attribute) request. + +## Structure + +`Retrieve Location Custom Attribute Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `with_definition` | `bool` | Optional | Indicates whether to return the [custom attribute definition](../../doc/models/custom-attribute-definition.md) in the `definition` field of
the custom attribute. Set this parameter to `true` to get the name and description of the custom
attribute, information about the data type, or other definition details. The default value is `false`. | +| `version` | `int` | Optional | The current version of the custom attribute, which is used for strongly consistent reads to
guarantee that you receive the most up-to-date data. When included in the request, Square
returns the specified version or a higher version if one exists. If the specified version is
higher than the current version, Square returns a `BAD_REQUEST` error. | + +## Example (as JSON) + +```json +{ + "with_definition": null, + "version": null +} +``` + diff --git a/doc/models/retrieve-location-custom-attribute-response.md b/doc/models/retrieve-location-custom-attribute-response.md new file mode 100644 index 00000000..bcdb86fd --- /dev/null +++ b/doc/models/retrieve-location-custom-attribute-response.md @@ -0,0 +1,26 @@ + +# Retrieve Location Custom Attribute Response + +Represents a [RetrieveLocationCustomAttribute](../../doc/api/location-custom-attributes.md#retrieve-location-custom-attribute) response. +Either `custom_attribute_definition` or `errors` is present in the response. + +## Structure + +`Retrieve Location Custom Attribute Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute` | [`Custom Attribute`](../../doc/models/custom-attribute.md) | Optional | A custom attribute value. Each custom attribute value has a corresponding
`CustomAttributeDefinition` object. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "custom_attribute": null, + "errors": null +} +``` + diff --git a/doc/models/update-location-custom-attribute-definition-request.md b/doc/models/update-location-custom-attribute-definition-request.md new file mode 100644 index 00000000..9046a39f --- /dev/null +++ b/doc/models/update-location-custom-attribute-definition-request.md @@ -0,0 +1,27 @@ + +# Update Location Custom Attribute Definition Request + +Represents an [UpdateLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#update-location-custom-attribute-definition) request. + +## Structure + +`Update Location Custom Attribute Definition Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute_definition` | [`Custom Attribute Definition`](../../doc/models/custom-attribute-definition.md) | Required | Represents a definition for custom attribute values. A custom attribute definition
specifies the key, visibility, schema, and other properties for a custom attribute. | +| `idempotency_key` | `string` | Optional | A unique identifier for this request, used to ensure idempotency. For more information,
see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
**Constraints**: *Maximum Length*: `45` | + +## Example (as JSON) + +```json +{ + "custom_attribute_definition": { + "description": "Update the description as desired.", + "visibility": "VISIBILITY_READ_ONLY" + } +} +``` + diff --git a/doc/models/update-location-custom-attribute-definition-response.md b/doc/models/update-location-custom-attribute-definition-response.md new file mode 100644 index 00000000..1628c081 --- /dev/null +++ b/doc/models/update-location-custom-attribute-definition-response.md @@ -0,0 +1,34 @@ + +# Update Location Custom Attribute Definition Response + +Represents an [UpdateLocationCustomAttributeDefinition](../../doc/api/location-custom-attributes.md#update-location-custom-attribute-definition) response. +Either `custom_attribute_definition` or `errors` is present in the response. + +## Structure + +`Update Location Custom Attribute Definition Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute_definition` | [`Custom Attribute Definition`](../../doc/models/custom-attribute-definition.md) | Optional | Represents a definition for custom attribute values. A custom attribute definition
specifies the key, visibility, schema, and other properties for a custom attribute. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "custom_attribute_definition": { + "created_at": "2022-12-02T19:06:36.559Z", + "description": "Update the description as desired.", + "key": "bestseller", + "name": "Bestseller", + "schema": null, + "updated_at": "2022-12-02T19:34:10.181Z", + "version": 2, + "visibility": "VISIBILITY_READ_ONLY" + } +} +``` + diff --git a/doc/models/upsert-location-custom-attribute-request.md b/doc/models/upsert-location-custom-attribute-request.md new file mode 100644 index 00000000..63088851 --- /dev/null +++ b/doc/models/upsert-location-custom-attribute-request.md @@ -0,0 +1,31 @@ + +# Upsert Location Custom Attribute Request + +Represents an [UpsertLocationCustomAttribute](../../doc/api/location-custom-attributes.md#upsert-location-custom-attribute) request. + +## Structure + +`Upsert Location Custom Attribute Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute` | [`Custom Attribute`](../../doc/models/custom-attribute.md) | Required | A custom attribute value. Each custom attribute value has a corresponding
`CustomAttributeDefinition` object. | +| `idempotency_key` | `string` | Optional | A unique identifier for this request, used to ensure idempotency. For more information,
see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
**Constraints**: *Maximum Length*: `45` | + +## Example (as JSON) + +```json +{ + "custom_attribute": { + "key": null, + "value": null, + "version": null, + "visibility": null, + "definition": null + }, + "idempotency_key": null +} +``` + diff --git a/doc/models/upsert-location-custom-attribute-response.md b/doc/models/upsert-location-custom-attribute-response.md new file mode 100644 index 00000000..d380d6d7 --- /dev/null +++ b/doc/models/upsert-location-custom-attribute-response.md @@ -0,0 +1,26 @@ + +# Upsert Location Custom Attribute Response + +Represents an [UpsertLocationCustomAttribute](../../doc/api/location-custom-attributes.md#upsert-location-custom-attribute) response. +Either `custom_attribute_definition` or `errors` is present in the response. + +## Structure + +`Upsert Location Custom Attribute Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `custom_attribute` | [`Custom Attribute`](../../doc/models/custom-attribute.md) | Optional | A custom attribute value. Each custom attribute value has a corresponding
`CustomAttributeDefinition` object. | +| `errors` | [`List of Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "custom_attribute": null, + "errors": null +} +``` + diff --git a/pyproject.toml b/pyproject.toml index fae02042..0cc50c61 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ requires = ["setuptools>=61.0"] [project] name = "squareup" description = "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management." -version = "25.0.0.20221214" +version = "25.1.0.20230119" requires-python = ">=3.7" authors = [{name = "Square Developer Platform", email = "developers@squareup.com"}] dependencies = ["apimatic-core~=0.1.0", "apimatic-core-interfaces~=0.1.0", "apimatic-requests-client-adapter~=0.1.0", "python-dateutil~=2.8.1", "deprecation~=2.1"] diff --git a/square/api/__init__.py b/square/api/__init__.py index d2019f58..e0e8d073 100644 --- a/square/api/__init__.py +++ b/square/api/__init__.py @@ -23,6 +23,7 @@ 'invoices_api', 'labor_api', 'locations_api', + 'location_custom_attributes_api', 'checkout_api', 'transactions_api', 'loyalty_api', diff --git a/square/api/base_api.py b/square/api/base_api.py index 5abdb1cd..a07e894d 100644 --- a/square/api/base_api.py +++ b/square/api/base_api.py @@ -24,7 +24,7 @@ class BaseApi(object): @staticmethod def user_agent(): - return 'Square-Python-SDK/25.0.0.20221214 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}' + return 'Square-Python-SDK/25.1.0.20230119 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}' @staticmethod def user_agent_parameters(): diff --git a/square/api/location_custom_attributes_api.py b/square/api/location_custom_attributes_api.py new file mode 100644 index 00000000..341e0f20 --- /dev/null +++ b/square/api/location_custom_attributes_api.py @@ -0,0 +1,709 @@ +# -*- coding: utf-8 -*- + +from square.api_helper import APIHelper +from square.http.api_response import ApiResponse +from square.api.base_api import BaseApi +from apimatic_core.request_builder import RequestBuilder +from apimatic_core.response_handler import ResponseHandler +from apimatic_core.types.parameter import Parameter +from square.http.http_method_enum import HttpMethodEnum +from apimatic_core.authentication.multiple.single_auth import Single +from apimatic_core.authentication.multiple.and_auth_group import And +from apimatic_core.authentication.multiple.or_auth_group import Or + + +class LocationCustomAttributesApi(BaseApi): + + """A Controller to access Endpoints in the square API.""" + def __init__(self, config): + super(LocationCustomAttributesApi, self).__init__(config) + + def list_location_custom_attribute_definitions(self, + visibility_filter=None, + limit=None, + cursor=None): + """Does a GET request to /v2/locations/custom-attribute-definitions. + + Lists the location-related [custom attribute + definitions]($m/CustomAttributeDefinition) 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`. + + Args: + visibility_filter (VisibilityFilter, optional): Filters the + `CustomAttributeDefinition` results by their `visibility` + values. + limit (int, 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](https://developer.squareup.com/docs/build-basics/c + ommon-api-patterns/pagination). + cursor (string, 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](https://developer.squareup.com/docs/build-basics/c + ommon-api-patterns/pagination). + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/custom-attribute-definitions') + .http_method(HttpMethodEnum.GET) + .query_param(Parameter() + .key('visibility_filter') + .value(visibility_filter)) + .query_param(Parameter() + .key('limit') + .value(limit)) + .query_param(Parameter() + .key('cursor') + .value(cursor)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def create_location_custom_attribute_definition(self, + body): + """Does a POST request to /v2/locations/custom-attribute-definitions. + + Creates a location-related [custom attribute + definition]($m/CustomAttributeDefinition) for a Square seller + account. + Use this endpoint to define a custom attribute that can be associated + with locations. + A custom attribute definition specifies the `key`, `visibility`, + `schema`, and other properties + for a custom attribute. After the definition is created, you can call + [UpsertLocationCustomAttribute]($e/LocationCustomAttributes/UpsertLocat + ionCustomAttribute) or + [BulkUpsertLocationCustomAttributes]($e/LocationCustomAttributes/BulkUp + sertLocationCustomAttributes) + to set the custom attribute for locations. + + Args: + body (CreateLocationCustomAttributeDefinitionRequest): An object + containing the fields to POST for the request. See the + corresponding object definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/custom-attribute-definitions') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def delete_location_custom_attribute_definition(self, + key): + """Does a DELETE request to /v2/locations/custom-attribute-definitions/{key}. + + Deletes a location-related [custom attribute + definition]($m/CustomAttributeDefinition) from a Square seller + account. + Deleting a custom attribute definition also deletes the corresponding + custom attribute from + all locations. + Only the definition owner can delete a custom attribute definition. + + Args: + key (string): The key of the custom attribute definition to + delete. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/custom-attribute-definitions/{key}') + .http_method(HttpMethodEnum.DELETE) + .template_param(Parameter() + .key('key') + .value(key) + .should_encode(True)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def retrieve_location_custom_attribute_definition(self, + key, + version=None): + """Does a GET request to /v2/locations/custom-attribute-definitions/{key}. + + Retrieves a location-related [custom attribute + definition]($m/CustomAttributeDefinition) 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`. + + Args: + key (string): The key of the custom attribute definition to + retrieve. If the requesting application is not the definition + owner, you must use the qualified key. + version (int, optional): The current version of the custom + attribute definition, which is used for strongly consistent + reads to guarantee that you receive the most up-to-date data. + When included in the request, Square returns the specified + version or a higher version if one exists. If the specified + version is higher than the current version, Square returns a + `BAD_REQUEST` error. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/custom-attribute-definitions/{key}') + .http_method(HttpMethodEnum.GET) + .template_param(Parameter() + .key('key') + .value(key) + .should_encode(True)) + .query_param(Parameter() + .key('version') + .value(version)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def update_location_custom_attribute_definition(self, + key, + body): + """Does a PUT request to /v2/locations/custom-attribute-definitions/{key}. + + Updates a location-related [custom attribute + definition]($m/CustomAttributeDefinition) for a Square seller + account. + Use this endpoint to update the following fields: `name`, + `description`, `visibility`, or the + `schema` for a `Selection` data type. + Only the definition owner can update a custom attribute definition. + + Args: + key (string): The key of the custom attribute definition to + update. + body (UpdateLocationCustomAttributeDefinitionRequest): An object + containing the fields to POST for the request. See the + corresponding object definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/custom-attribute-definitions/{key}') + .http_method(HttpMethodEnum.PUT) + .template_param(Parameter() + .key('key') + .value(key) + .should_encode(True)) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def bulk_delete_location_custom_attributes(self, + body): + """Does a POST request to /v2/locations/custom-attributes/bulk-delete. + + Deletes [custom attributes]($m/CustomAttribute) for locations as a + bulk operation. + To delete a custom attribute owned by another application, the + `visibility` setting must be + `VISIBILITY_READ_WRITE_VALUES`. + + Args: + body (BulkDeleteLocationCustomAttributesRequest): An object + containing the fields to POST for the request. See the + corresponding object definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/custom-attributes/bulk-delete') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def bulk_upsert_location_custom_attributes(self, + body): + """Does a POST request to /v2/locations/custom-attributes/bulk-upsert. + + Creates or updates [custom attributes]($m/CustomAttribute) for + locations as a bulk operation. + Use this endpoint to set the value of one or more custom attributes + for one or more locations. + A custom attribute is based on a custom attribute definition in a + Square seller account, which is + created using the + [CreateLocationCustomAttributeDefinition]($e/LocationCustomAttributes/C + reateLocationCustomAttributeDefinition) endpoint. + This `BulkUpsertLocationCustomAttributes` 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 a location 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`. + + Args: + body (BulkUpsertLocationCustomAttributesRequest): An object + containing the fields to POST for the request. See the + corresponding object definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/custom-attributes/bulk-upsert') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def list_location_custom_attributes(self, + location_id, + visibility_filter=None, + limit=None, + cursor=None, + with_definitions=False): + """Does a GET request to /v2/locations/{location_id}/custom-attributes. + + Lists the [custom attributes]($m/CustomAttribute) associated with a + location. + 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`. + + Args: + location_id (string): The ID of the target + [location]($m/Location). + visibility_filter (VisibilityFilter, optional): Filters the + `CustomAttributeDefinition` results by their `visibility` + values. + limit (int, 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](https://developer.squareup.com/docs/build-basics/c + ommon-api-patterns/pagination). + cursor (string, 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](https://developer.squareup.com/docs/build-basics/c + ommon-api-patterns/pagination). + with_definitions (bool, optional): Indicates whether to return the + [custom attribute definition]($m/CustomAttributeDefinition) 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`. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/{location_id}/custom-attributes') + .http_method(HttpMethodEnum.GET) + .template_param(Parameter() + .key('location_id') + .value(location_id) + .should_encode(True)) + .query_param(Parameter() + .key('visibility_filter') + .value(visibility_filter)) + .query_param(Parameter() + .key('limit') + .value(limit)) + .query_param(Parameter() + .key('cursor') + .value(cursor)) + .query_param(Parameter() + .key('with_definitions') + .value(with_definitions)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def delete_location_custom_attribute(self, + location_id, + key): + """Does a DELETE request to /v2/locations/{location_id}/custom-attributes/{key}. + + Deletes a [custom attribute]($m/CustomAttribute) associated with a + location. + To delete a custom attribute owned by another application, the + `visibility` setting must be + `VISIBILITY_READ_WRITE_VALUES`. + + Args: + location_id (string): The ID of the target + [location]($m/Location). + key (string): The key of the custom attribute to delete. This key + must match the `key` of a custom attribute definition in the + Square seller account. If the requesting application is not + the definition owner, you must use the qualified key. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/{location_id}/custom-attributes/{key}') + .http_method(HttpMethodEnum.DELETE) + .template_param(Parameter() + .key('location_id') + .value(location_id) + .should_encode(True)) + .template_param(Parameter() + .key('key') + .value(key) + .should_encode(True)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def retrieve_location_custom_attribute(self, + location_id, + key, + with_definition=False, + version=None): + """Does a GET request to /v2/locations/{location_id}/custom-attributes/{key}. + + Retrieves a [custom attribute]($m/CustomAttribute) associated with a + location. + 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`. + + Args: + location_id (string): The ID of the target + [location]($m/Location). + key (string): The key of the custom attribute to retrieve. This + key must match the `key` of a custom attribute definition in + the Square seller account. If the requesting application is + not the definition owner, you must use the qualified key. + with_definition (bool, optional): Indicates whether to return the + [custom attribute definition]($m/CustomAttributeDefinition) in + the `definition` field of the custom attribute. Set this + parameter to `true` to get the name and description of the + custom attribute, information about the data type, or other + definition details. The default value is `false`. + version (int, optional): The current version of the custom + attribute, which is used for strongly consistent reads to + guarantee that you receive the most up-to-date data. When + included in the request, Square returns the specified version + or a higher version if one exists. If the specified version is + higher than the current version, Square returns a + `BAD_REQUEST` error. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/{location_id}/custom-attributes/{key}') + .http_method(HttpMethodEnum.GET) + .template_param(Parameter() + .key('location_id') + .value(location_id) + .should_encode(True)) + .template_param(Parameter() + .key('key') + .value(key) + .should_encode(True)) + .query_param(Parameter() + .key('with_definition') + .value(with_definition)) + .query_param(Parameter() + .key('version') + .value(version)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def upsert_location_custom_attribute(self, + location_id, + key, + body): + """Does a POST request to /v2/locations/{location_id}/custom-attributes/{key}. + + Creates or updates a [custom attribute]($m/CustomAttribute) for a + location. + Use this endpoint to set the value of a custom attribute for a + specified location. + A custom attribute is based on a custom attribute definition in a + Square seller account, which + is created using the + [CreateLocationCustomAttributeDefinition]($e/LocationCustomAttributes/C + reateLocationCustomAttributeDefinition) endpoint. + To create or update a custom attribute owned by another application, + the `visibility` setting + must be `VISIBILITY_READ_WRITE_VALUES`. + + Args: + location_id (string): The ID of the target + [location]($m/Location). + key (string): The key of the custom attribute to create or update. + This key must match the `key` of a custom attribute definition + in the Square seller account. If the requesting application is + not the definition owner, you must use the qualified key. + body (UpsertLocationCustomAttributeRequest): An object containing + the fields to POST for the request. See the corresponding + object definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/locations/{location_id}/custom-attributes/{key}') + .http_method(HttpMethodEnum.POST) + .template_param(Parameter() + .key('location_id') + .value(location_id) + .should_encode(True)) + .template_param(Parameter() + .key('key') + .value(key) + .should_encode(True)) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() diff --git a/square/client.py b/square/client.py index fe9df6cc..6491f848 100644 --- a/square/client.py +++ b/square/client.py @@ -29,6 +29,8 @@ from square.api.invoices_api import InvoicesApi from square.api.labor_api import LaborApi from square.api.locations_api import LocationsApi +from square.api.location_custom_attributes_api\ + import LocationCustomAttributesApi from square.api.checkout_api import CheckoutApi from square.api.transactions_api import TransactionsApi from square.api.loyalty_api import LoyaltyApi @@ -51,11 +53,11 @@ class Client(object): @staticmethod def sdk_version(): - return '25.0.0.20221214' + return '25.1.0.20230119' @staticmethod def square_version(): - return '2022-12-14' + return '2023-01-19' def user_agent_detail(self): return self.config.user_agent_detail @@ -152,6 +154,10 @@ def labor(self): def locations(self): return LocationsApi(self.global_configuration) + @LazyProperty + def location_custom_attributes(self): + return LocationCustomAttributesApi(self.global_configuration) + @LazyProperty def checkout(self): return CheckoutApi(self.global_configuration) @@ -222,7 +228,7 @@ def __init__(self, http_client_instance=None, retry_statuses=[408, 413, 429, 500, 502, 503, 504, 521, 522, 524], retry_methods=['GET', 'PUT'], environment='production', custom_url='https://connect.squareup.com', access_token='', - square_version='2022-12-14', additional_headers={}, + square_version='2023-01-19', additional_headers={}, user_agent_detail='', config=None): if config is None: self.config = Configuration( diff --git a/square/configuration.py b/square/configuration.py index 7fd7a4c2..8a08d190 100644 --- a/square/configuration.py +++ b/square/configuration.py @@ -41,7 +41,7 @@ def __init__( retry_statuses=[408, 413, 429, 500, 502, 503, 504, 521, 522, 524], retry_methods=['GET', 'PUT'], environment='production', custom_url='https://connect.squareup.com', access_token='', - square_version='2022-12-14', additional_headers={}, + square_version='2023-01-19', additional_headers={}, user_agent_detail='' ): super().__init__(http_client_instance, override_http_client_configuration, http_call_back, timeout, max_retries,