diff --git a/CHANGELOG.md b/CHANGELOG.md index 676d8332..0a0a6b67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,35 @@ # Change Log +## Version 17.0.0.20211215 (2021-12-15) +### API updates + +* **Invoices API:** + * The Invoices API now supports seller accounts in France. For more information, see [International availability and considerations.](https://developer.squareup.com/docs/invoices-api/overview#international-availability-invoices) + * France only: [`Invoice`](https://developer.squareup.com/reference/square_2021-12-15/objects/Invoice) object. Added a new `payment_conditions` field, which contains payment terms and conditions that are displayed on the invoice. This field is available only for sellers in France. For more information, see [Payment conditions.](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions) + + Square version 2021-12-15 or higher is required to set this field, but it is returned in `ListInvoices` and `RetrieveInvoice` requests for all Square versions. + +* **Cards API** + * Added the `CARD_DECLINED_VERIFICATION_REQUIRED` error code to the list of error codes returned by [CreateCard](https://developer.squareup.com/reference/square_2021-12-15/cards-api/CreateCard). +* **Catalog API:** + * [CreateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/create-catalog-image) endpoint + * Updated to support attaching multiple images to a [Catalogbject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) instance. + * Added `is_primary` option to let the caller choose to attach an image as the primary image on the object for display with the Square Point of Sale and other first-party Square applications. For more information, see [Upload and Attach Images.](https://developer.squareup.com/docs/catalog-api/upload-and-attach-images) + * [CatalogObject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) object + * Retired the `image_id` field, used to hold a single image object attached to an image-supporting object of the `ITEM`, `ITEM_VARIATION`, `CATEGORY`, or `MODIFIER_LIST` type, in Square API version 2021-12-15 and later, which supports attachment of multiple images. The `image_id` field is still supported in Square API version prior to 2021-12-15. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview) + * [CatalogItem](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItem), [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItemVariation), [CatalogCategory](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogCategory) or [CatalogModifierList](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogModifierList) object + * Added `image_ids` list to hold attached image objects. The first element of `image_ids` list refers to the primary image attached to the catalog object. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview) + * [UpdateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/update-catalog-image) endpoint + * Added to support replacing the image file encapsulated by an existing [CatalogImage](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogImage) object. For more information, see [Replace image file on a CatalogImage object.](https://developer.squareup.com/docs/catalog-api/manage-images#replace-the-image-file-of-a-catalogimage-object) + + * [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule) object + * Added [minimum_order_subtotal_money](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule#definition__property-minimum_order_subtotal_money) field to require that the minimum order subtotal be reached before the pricing rule may be applied. + +### Documentation updates +* Added a new top-level node for Developer Tools. This node includes such features as Sandbox, API Logs, and Webhooks. +* Added [Webhook Event Logs (beta)](https://developer.squareup.com/docs/devtools/webhook-logs) documentation to the Developer Tools node. + + ## Version 16.0.0.20211117 (2021-11-17) ## API updates diff --git a/doc/api/catalog.md b/doc/api/catalog.md index 781f72f5..990c3008 100644 --- a/doc/api/catalog.md +++ b/doc/api/catalog.md @@ -14,6 +14,7 @@ catalog_api = client.catalog * [Batch Retrieve Catalog Objects](/doc/api/catalog.md#batch-retrieve-catalog-objects) * [Batch Upsert Catalog Objects](/doc/api/catalog.md#batch-upsert-catalog-objects) * [Create Catalog Image](/doc/api/catalog.md#create-catalog-image) +* [Update Catalog Image](/doc/api/catalog.md#update-catalog-image) * [Catalog Info](/doc/api/catalog.md#catalog-info) * [List Catalog](/doc/api/catalog.md#list-catalog) * [Upsert Catalog Object](/doc/api/catalog.md#upsert-catalog-object) @@ -302,6 +303,7 @@ body['batches'][0]['objects'][2]['catalog_v1_ids'][2]['location_id'] = 'location body['batches'][0]['objects'][2]['present_at_all_locations'] = True body['batches'][0]['objects'][2]['category_data'] = {} body['batches'][0]['objects'][2]['category_data']['name'] = 'Beverages' +body['batches'][0]['objects'][2]['category_data']['image_ids'] = ['image_ids1', 'image_ids2'] body['batches'][0]['objects'].append({}) body['batches'][0]['objects'][3]['type'] = 'TAX' @@ -338,9 +340,9 @@ elif result.is_error(): # Create Catalog Image -Uploads an image file to be represented by a [CatalogImage](/doc/models/catalog-image.md) object linked to an existing -[CatalogObject](/doc/models/catalog-object.md) instance. A call to this endpoint can upload an image, link an image to -a catalog object, or do both. +Uploads an image file to be represented by a [CatalogImage](/doc/models/catalog-image.md) object that can be linked to an existing +[CatalogObject](/doc/models/catalog-object.md) instance. The resulting `CatalogImage` is unattached to any `CatalogObject` if the `object_id` +is not specified. This `CreateCatalogImage` endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB. @@ -385,6 +387,8 @@ request['image']['image_data'] = {} request['image']['image_data']['name'] = 'name0' request['image']['image_data']['url'] = 'url4' request['image']['image_data']['caption'] = 'A picture of a cup of coffee' +request['image']['image_data']['photo_studio_order_id'] = 'photo_studio_order_id2' +request['is_primary'] = False image_file = FileWrapper(open('dummy_file', 'rb'), 'optional-content-type') result = catalog_api.create_catalog_image(request, image_file) @@ -396,6 +400,49 @@ elif result.is_error(): ``` +# Update Catalog Image + +Uploads a new image file to replace the existing one in the specified [CatalogImage](/doc/models/catalog-image.md) object. + +This `UpdateCatalogImage` endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in +JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB. + +```python +def update_catalog_image(self, + image_id, + request=None, + image_file=None) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `image_id` | `string` | Template, Required | The ID of the `CatalogImage` object to update the encapsulated image file. | +| `request` | [`Update Catalog Image Request`](/doc/models/update-catalog-image-request.md) | Form, Optional | - | +| `image_file` | `typing.BinaryIO` | Form, Optional | - | + +## Response Type + +[`Update Catalog Image Response`](/doc/models/update-catalog-image-response.md) + +## Example Usage + +```python +image_id = 'image_id4' +request = {} +request['idempotency_key'] = '528dea59-7bfb-43c1-bd48-4a6bba7dd61f86' +image_file = FileWrapper(open('dummy_file', 'rb'), 'optional-content-type') + +result = catalog_api.update_catalog_image(image_id, request, image_file) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + # Catalog Info Retrieves information about the Square Catalog API, such as batch size @@ -423,11 +470,10 @@ elif result.is_error(): # List Catalog -Returns a list of [CatalogObject](/doc/models/catalog-object.md)s that includes -all objects of a set of desired types (for example, all [CatalogItem](/doc/models/catalog-item.md) -and [CatalogTax](/doc/models/catalog-tax.md) objects) in the catalog. The `types` parameter -is specified as a comma-separated list of valid [CatalogObject](/doc/models/catalog-object.md) types: -`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`. +Returns a list of all [CatalogObject](/doc/models/catalog-object.md)s of the specified types in the catalog. + +The `types` parameter is specified as a comma-separated list of the [CatalogObjectType](/doc/models/catalog-object-type.md) values, +for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`". __Important:__ ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use [SearchCatalogObjects](/doc/api/catalog.md#search-catalog-objects) @@ -445,8 +491,8 @@ def list_catalog(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `string` | Query, Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
The page size is currently set to be 100.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `types` | `string` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](/doc/models/catalog-object-type.md) enum, including
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.

If this is unspecified, the operation returns objects of all the types at the version of the Square API used to make the request. | -| `catalog_version` | `long\|int` | Query, Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute. | +| `types` | `string` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](/doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | +| `catalog_version` | `long\|int` | Query, Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute. If not included, results will
be from the current version of the catalog. | ## Response Type @@ -644,8 +690,8 @@ def retrieve_catalog_object(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `object_id` | `string` | Template, Required | The object ID of any type of catalog objects to be retrieved. | -| `include_related_objects` | `bool` | Query, Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If the `object` field of the response contains a `CatalogItem`, its associated
`CatalogCategory`, `CatalogTax`, `CatalogImage` and `CatalogModifierList` objects will
be returned in the `related_objects` field of the response. If the `object` field of
the response contains a `CatalogItemVariation`, its parent `CatalogItem` will be returned
in the `related_objects` field of the response.

Default value: `false`
**Default**: `False` | -| `catalog_version` | `long\|int` | Query, Optional | Requests objects as of a specific version of the catalog. This allows you to retrieve historical
versions of objects. The value to retrieve a specific version of an object can be found
in the version field of [CatalogObject](/doc/models/catalog-object.md)s. | +| `include_related_objects` | `bool` | Query, Optional | If `true`, the response will include additional objects that are related to the
requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field
of the response. These objects are put in the `related_objects` field. Setting this to `true` is
helpful when the objects are needed for immediate display to a user.
This process only goes one level deep. Objects referenced by the related objects will not be included. For example,

if the `objects` field of the response contains a CatalogItem, its associated
CatalogCategory objects, CatalogTax objects, CatalogImage objects and
CatalogModifierLists will be returned in the `related_objects` field of the
response. If the `objects` field of the response contains a CatalogItemVariation,
its parent CatalogItem will be returned in the `related_objects` field of
the response.

Default value: `false`
**Default**: `False` | +| `catalog_version` | `long\|int` | Query, Optional | Requests objects as of a specific version of the catalog. This allows you to retrieve historical
versions of objects. The value to retrieve a specific version of an object can be found
in the version field of [CatalogObject](/doc/models/catalog-object.md)s. If not included, results will
be from the current version of the catalog. | ## Response Type diff --git a/doc/api/locations.md b/doc/api/locations.md index afbb666d..2260da93 100644 --- a/doc/api/locations.md +++ b/doc/api/locations.md @@ -18,11 +18,8 @@ locations_api = client.locations # List Locations -Provides information of all locations of a business. - -Many Square API endpoints require a `location_id` parameter. -The `id` field of the [`Location`](/doc/models/location.md) objects returned by this -endpoint correspond to that `location_id` parameter. +Provides details about all of the seller's locations, +including those with an inactive status. ```python def list_locations(self) @@ -46,7 +43,13 @@ elif result.is_error(): # Create Location -Creates a location. +Creates a [location](https://developer.squareup.com/docs/locations-api). +Creating new locations allows for separate configuration of receipt layouts, item prices, +and sales reports. Developers can use locations to separate sales activity via applications +that integrate with Square from sales activity elsewhere in a seller's account. +Locations created programmatically with the Locations API will last forever and +are visible to the seller for their own management, so ensure that +each location has a sensible and unique name. ```python def create_location(self, @@ -94,9 +97,8 @@ elif result.is_error(): # Retrieve Location -Retrieves details of a location. You can specify "main" -as the location ID to retrieve details of the -main location. +Retrieves details of a single location. Specify "main" +as the location ID to retrieve details of the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location). ```python def retrieve_location(self, @@ -107,7 +109,7 @@ def retrieve_location(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `location_id` | `string` | Template, Required | The ID of the location to retrieve. If you specify the string "main",
then the endpoint returns the main location. | +| `location_id` | `string` | Template, Required | The ID of the location to retrieve. Specify the string
"main" to return the main location. | ## Response Type diff --git a/doc/api/mobile-authorization.md b/doc/api/mobile-authorization.md index 52add9fa..b338e479 100644 --- a/doc/api/mobile-authorization.md +++ b/doc/api/mobile-authorization.md @@ -11,9 +11,9 @@ mobile_authorization_api = client.mobile_authorization # Create Mobile Authorization Code -Generates code to authorize a mobile application to connect to a Square card reader +Generates code to authorize a mobile application to connect to a Square card reader. -Authorization codes are one-time-use and expire __60 minutes__ after being issued. +Authorization codes are one-time-use codes and expire 60 minutes after being issued. __Important:__ The `Authorization` header you provide to this endpoint must have the following format: diff --git a/doc/api/o-auth.md b/doc/api/o-auth.md index b3f7d2c4..d16c4fa8 100644 --- a/doc/api/o-auth.md +++ b/doc/api/o-auth.md @@ -24,10 +24,10 @@ o_auth_api = client.o_auth Renews an OAuth access token before it expires. -OAuth access tokens besides your application's personal access token expire after __30 days__. -You can also renew expired tokens within __15 days__ of their expiration. +OAuth access tokens besides your application's personal access token expire after 30 days. +You can also renew expired tokens within 15 days of their expiration. You cannot renew an access token that has been expired for more than 15 days. -Instead, the associated user must re-complete the OAuth flow from the beginning. +Instead, the associated user must recomplete the OAuth flow from the beginning. __Important:__ The `Authorization` header for this endpoint must have the following format: @@ -37,7 +37,7 @@ Authorization: Client APPLICATION_SECRET ``` Replace `APPLICATION_SECRET` with the application secret on the Credentials -page in the [developer dashboard](https://developer.squareup.com/apps). +page in the [Developer Dashboard](https://developer.squareup.com/apps). :information_source: **Note** This endpoint does not require authentication. @@ -52,7 +52,7 @@ def renew_token(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `client_id` | `string` | Template, Required | Your application ID, available from the OAuth page for your
application on the Developer Dashboard. | +| `client_id` | `string` | Template, Required | Your application ID, which is available in the OAuth page in the [Developer Dashboard](https://developer.squareup.com/apps). | | `body` | [`Renew Token Request`](/doc/models/renew-token-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | | `authorization` | `string` | Header, Required | Client APPLICATION_SECRET | diff --git a/doc/client.md b/doc/client.md index 1b38cbb1..2d630180 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*: `'2021-11-17'` | +| `square_version` | `string` | Square Connect API versions
*Default*: `'2021-12-15'` | | `access_token` | `string` | The OAuth 2.0 Access Token to use for API requests. | | `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`** | @@ -17,6 +17,7 @@ The following parameters are configurable for the API Client: | `retry_statuses` | `Array of int` | The http statuses on which retry is to be done.
**Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]** | | `retry_methods` | `Array of string` | The http methods on which retry is to be done.
**Default: ['GET', 'PUT']** | | `additional_headers` | `dict` | Additional headers to add to each API request | +| `user_agent_detail` | `string` | User agent detail, to be appended with user-agent header. | The API client can be initialized as follows: @@ -24,7 +25,7 @@ The API client can be initialized as follows: from square.client import Client client = Client( - square_version='2021-11-17', + square_version='2021-12-15', access_token='AccessToken', environment='production', custom_url = 'https://connect.squareup.com',) @@ -49,7 +50,7 @@ API calls return an `ApiResponse` object that includes the following fields: from square.client import Client client = Client( - square_version='2021-11-17', + square_version='2021-12-15', access_token='AccessToken',) locations_api = client.locations diff --git a/doc/models/batch-retrieve-catalog-objects-request.md b/doc/models/batch-retrieve-catalog-objects-request.md index bfa6bb54..fbad60db 100644 --- a/doc/models/batch-retrieve-catalog-objects-request.md +++ b/doc/models/batch-retrieve-catalog-objects-request.md @@ -10,8 +10,8 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `object_ids` | `List of string` | Required | The IDs of the CatalogObjects to be retrieved. | -| `include_related_objects` | `bool` | Optional | If `true`, the response will include additional objects that are related to the
requested objects, as follows:

If the `objects` field of the response contains a CatalogItem, its associated
CatalogCategory objects, CatalogTax objects, CatalogImage objects and
CatalogModifierLists will be returned in the `related_objects` field of the
response. If the `objects` field of the response contains a CatalogItemVariation,
its parent CatalogItem will be returned in the `related_objects` field of
the response. | -| `catalog_version` | `long\|int` | Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical versions of objects. The specified version value is matched against
the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute. | +| `include_related_objects` | `bool` | Optional | If `true`, the response will include additional objects that are related to the
requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field
of the response. These objects are put in the `related_objects` field. Setting this to `true` is
helpful when the objects are needed for immediate display to a user.
This process only goes one level deep. Objects referenced by the related objects will not be included. For example,

if the `objects` field of the response contains a CatalogItem, its associated
CatalogCategory objects, CatalogTax objects, CatalogImage objects and
CatalogModifierLists will be returned in the `related_objects` field of the
response. If the `objects` field of the response contains a CatalogItemVariation,
its parent CatalogItem will be returned in the `related_objects` field of
the response.

Default value: `false` | +| `catalog_version` | `long\|int` | Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical versions of objects. The specified version value is matched against
the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute. If not included, results will
be from the current version of the catalog. | ## Example (as JSON) diff --git a/doc/models/business-hours.md b/doc/models/business-hours.md index 6f2cb57d..d4f179ff 100644 --- a/doc/models/business-hours.md +++ b/doc/models/business-hours.md @@ -1,7 +1,7 @@ # Business Hours -Represents the hours of operation for a business location. +The hours of operation for a location. ## Structure diff --git a/doc/models/catalog-category.md b/doc/models/catalog-category.md index 75d66c71..4f026ab2 100644 --- a/doc/models/catalog-category.md +++ b/doc/models/catalog-category.md @@ -12,6 +12,7 @@ A category to which a `CatalogItem` instance belongs. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `name` | `string` | Optional | The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
**Constraints**: *Maximum Length*: `255` | +| `image_ids` | `List of string` | Optional | The IDs of images associated with this `CatalogCategory` instance.
Currently these images are not displayed by Square, but are free to be displayed in 3rd party applications. | ## Example (as JSON) diff --git a/doc/models/catalog-image.md b/doc/models/catalog-image.md index 70443d74..8e738784 100644 --- a/doc/models/catalog-image.md +++ b/doc/models/catalog-image.md @@ -19,6 +19,7 @@ Images on other object types are for use by 3rd party application developers. | `name` | `string` | Optional | The internal name to identify this image in calls to the Square API.
This is a searchable attribute for use in applicable query filters
using the [SearchCatalogObjects](/doc/api/catalog.md#search-catalog-objects).
It is not unique and should not be shown in a buyer facing context. | | `url` | `string` | Optional | The URL of this image, generated by Square after an image is uploaded
using the [CreateCatalogImage](/doc/api/catalog.md#create-catalog-image) endpoint.
To modify the image, use the UpdateCatalogImage endpoint. Do not change the URL field. | | `caption` | `string` | Optional | A caption that describes what is shown in the image. Displayed in the
Square Online Store. This is a searchable attribute for use in applicable query filters
using the [SearchCatalogObjects](/doc/api/catalog.md#search-catalog-objects). | +| `photo_studio_order_id` | `string` | Optional | The immutable order ID for this image object created by the Photo Studio service in Square Online Store. | ## Example (as JSON) @@ -26,7 +27,8 @@ Images on other object types are for use by 3rd party application developers. { "name": "name0", "url": "url4", - "caption": "caption4" + "caption": "caption4", + "photo_studio_order_id": "photo_studio_order_id2" } ``` diff --git a/doc/models/catalog-item-variation.md b/doc/models/catalog-item-variation.md index 3970f03e..ef8c2ae0 100644 --- a/doc/models/catalog-item-variation.md +++ b/doc/models/catalog-item-variation.md @@ -29,6 +29,7 @@ may have a maximum of 250 item variations. | `item_option_values` | [`List of Catalog Item Option Value for Item Variation`](/doc/models/catalog-item-option-value-for-item-variation.md) | Optional | List of item option values associated with this item variation. Listed
in the same order as the item options of the parent item. | | `measurement_unit_id` | `string` | Optional | ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity
sold of this item variation. If left unset, the item will be sold in
whole quantities. | | `stockable` | `bool` | Optional | Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE).
For backward compatibility missing values will be interpreted as TRUE. | +| `image_ids` | `List of string` | Optional | The IDs of images associated with this `CatalogItemVariation` instance.
These images will be shown to customers in Square Online Store. | | `team_member_ids` | `List of string` | Optional | Tokens of employees that can perform the service represented by this variation. Only valid for
variations of type `APPOINTMENTS_SERVICE`. | | `stockable_conversion` | [`Catalog Stock Conversion`](/doc/models/catalog-stock-conversion.md) | Optional | Represents the rule of conversion between a stockable [CatalogItemVariation](/doc/models/catalog-item-variation.md)
and a non-stockable sell-by or receive-by `CatalogItemVariation` that
share the same underlying stock. | diff --git a/doc/models/catalog-item.md b/doc/models/catalog-item.md index bfcdce52..2160eec7 100644 --- a/doc/models/catalog-item.md +++ b/doc/models/catalog-item.md @@ -25,6 +25,7 @@ A [CatalogObject](/doc/models/catalog-object.md) instance of the `ITEM` type, al | `product_type` | [`str (Catalog Item Product Type)`](/doc/models/catalog-item-product-type.md) | Optional | The type of a CatalogItem. Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items. | | `skip_modifier_screen` | `bool` | Optional | If `false`, the Square Point of Sale app will present the `CatalogItem`'s
details screen immediately, allowing the merchant to choose `CatalogModifier`s
before adding the item to the cart. This is the default behavior.

If `true`, the Square Point of Sale app will immediately add the item to the cart with the pre-selected
modifiers, and merchants can edit modifiers by drilling down onto the item's details.

Third-party clients are encouraged to implement similar behaviors. | | `item_options` | [`List of Catalog Item Option for Item`](/doc/models/catalog-item-option-for-item.md) | Optional | List of item options IDs for this item. Used to manage and group item
variations in a specified order.

Maximum: 6 item options. | +| `image_ids` | `List of string` | Optional | The IDs of images associated with this `CatalogItem` instance.
These images will be shown to customers in Square Online Store.
The first image will show up as the icon for this item in POS. | | `sort_name` | `string` | Optional | A name to sort the item by. If this name is unspecified, namely, the `sort_name` field is absent, the regular `name` field is used for sorting.

It is currently supported for sellers of the Japanese locale only. | ## Example (as JSON) diff --git a/doc/models/catalog-modifier-list.md b/doc/models/catalog-modifier-list.md index 553989e8..fddcce36 100644 --- a/doc/models/catalog-modifier-list.md +++ b/doc/models/catalog-modifier-list.md @@ -20,6 +20,7 @@ the modifier list are allowed. | `ordinal` | `int` | Optional | Determines where this modifier list appears in a list of `CatalogModifierList` values. | | `selection_type` | [`str (Catalog Modifier List Selection Type)`](/doc/models/catalog-modifier-list-selection-type.md) | Optional | Indicates whether a CatalogModifierList supports multiple selections. | | `modifiers` | [`List of Catalog Object`](/doc/models/catalog-object.md) | Optional | The options included in the `CatalogModifierList`.
You must include at least one `CatalogModifier`.
Each CatalogObject must have type `MODIFIER` and contain
`CatalogModifier` data. | +| `image_ids` | `List of string` | Optional | The IDs of images associated with this `CatalogModifierList` instance.
Currently these images are not displayed by Square, but are free to be displayed in 3rd party applications. | ## Example (as JSON) diff --git a/doc/models/catalog-object.md b/doc/models/catalog-object.md index e744ad18..89851a17 100644 --- a/doc/models/catalog-object.md +++ b/doc/models/catalog-object.md @@ -30,7 +30,6 @@ For a more detailed discussion of the Catalog data model, please see the | `present_at_all_locations` | `bool` | Optional | If `true`, this object is present at all locations (including future locations), except where specified in
the `absent_at_location_ids` field. If `false`, this object is not present at any locations (including future locations),
except where specified in the `present_at_location_ids` field. If not specified, defaults to `true`. | | `present_at_location_ids` | `List of string` | Optional | A list of locations where the object is present, even if `present_at_all_locations` is `false`.
This can include locations that are deactivated. | | `absent_at_location_ids` | `List of string` | Optional | A list of locations where the object is not present, even if `present_at_all_locations` is `true`.
This can include locations that are deactivated. | -| `image_id` | `string` | Optional | Identifies the `CatalogImage` attached to this `CatalogObject`. | | `item_data` | [`Catalog Item`](/doc/models/catalog-item.md) | Optional | A [CatalogObject](/doc/models/catalog-object.md) instance of the `ITEM` type, also referred to as an item, in the catalog. | | `category_data` | [`Catalog Category`](/doc/models/catalog-category.md) | Optional | A category to which a `CatalogItem` instance belongs. | | `item_variation_data` | [`Catalog Item Variation`](/doc/models/catalog-item-variation.md) | Optional | An item variation (i.e., product) in the Catalog object model. Each item
may have a maximum of 250 item variations. | diff --git a/doc/models/catalog-pricing-rule.md b/doc/models/catalog-pricing-rule.md index 072c6d44..a0538919 100644 --- a/doc/models/catalog-pricing-rule.md +++ b/doc/models/catalog-pricing-rule.md @@ -23,6 +23,7 @@ during the active time period. | `valid_until_date` | `string` | Optional | Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD). | | `valid_until_local_time` | `string` | Optional | Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format
(HH:MM:SS). Partial seconds will be truncated. | | `exclude_strategy` | [`str (Exclude Strategy)`](/doc/models/exclude-strategy.md) | Optional | Indicates which products matched by a CatalogPricingRule
will be excluded if the pricing rule uses an exclude set. | +| `minimum_order_subtotal_money` | [`Money`](/doc/models/money.md) | Optional | 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. | | `customer_group_ids_any` | `List of string` | Optional | A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule.
Notice that a group ID is generated by the Customers API.
If this field is not set, the specified discount applies to matched products sold to anyone whether the buyer
has a customer profile created or not. If this `customer_group_ids_any` field is set, the specified discount
applies only to matched products sold to customers belonging to the specified customer groups. | ## Example (as JSON) diff --git a/doc/models/create-catalog-image-request.md b/doc/models/create-catalog-image-request.md index 140c10fd..4ed52159 100644 --- a/doc/models/create-catalog-image-request.md +++ b/doc/models/create-catalog-image-request.md @@ -10,8 +10,9 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `idempotency_key` | `string` | Required | A unique string that identifies this CreateCatalogImage request.
Keys can be any valid string but must be unique for every CreateCatalogImage request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1` | -| `object_id` | `string` | Optional | Unique ID of the `CatalogObject` to attach to this `CatalogImage`. Leave this
field empty to create unattached images, for example if you are building an integration
where these images can be attached to catalog items at a later time. | +| `object_id` | `string` | Optional | Unique ID of the `CatalogObject` to attach this `CatalogImage` object to. Leave this
field empty to create unattached images, for example if you are building an integration
where an image can be attached to catalog items at a later time. | | `image` | [`Catalog Object`](/doc/models/catalog-object.md) | Required | The wrapper object for the catalog entries of a given object type.

Depending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object.

For example, if `type=ITEM`, the `CatalogObject` instance must have the ITEM-specific data set on the `item_data` attribute. The resulting `CatalogObject` instance is also a `CatalogItem` instance.

In general, if `type=`, the `CatalogObject` instance must have the ``-specific data set on the `_data` attribute. The resulting `CatalogObject` instance is also a `Catalog` instance.

For a more detailed discussion of the Catalog data model, please see the
[Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide. | +| `is_primary` | `bool` | Optional | If this is set to `true`, the image created will be the primary, or first image of the object referenced by `object_id`.
If the `CatalogObject` already has a primary `CatalogImage`, setting this field to `true` will replace the primary image.
If this is set to `false` and you use the Square API version 2021-12-15 or later, the image id will be appended to the list of `image_ids` on the object.

With Square API version 2021-12-15 or later, the default value is `false`. Otherwise, the effective default value is `true`. | ## Example (as JSON) diff --git a/doc/models/create-location-request.md b/doc/models/create-location-request.md index 80e372b8..7c4fb3d2 100644 --- a/doc/models/create-location-request.md +++ b/doc/models/create-location-request.md @@ -11,7 +11,7 @@ Request object for the [CreateLocation](/doc/api/locations.md#create-location) e | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's [locations](https://developer.squareup.com/docs/locations-api). | ## Example (as JSON) diff --git a/doc/models/create-location-response.md b/doc/models/create-location-response.md index d647602f..60185a06 100644 --- a/doc/models/create-location-response.md +++ b/doc/models/create-location-response.md @@ -11,8 +11,8 @@ Response object returned by the [CreateLocation](/doc/api/locations.md#create-lo | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information on [errors](https://developer.squareup.com/docs/build-basics/handling-errors) encountered during the request. | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's [locations](https://developer.squareup.com/docs/locations-api). | ## Example (as JSON) @@ -36,11 +36,11 @@ Response object returned by the [CreateLocation](/doc/api/locations.md#create-lo "created_at": "2019-07-19T17:58:25Z", "currency": "USD", "description": "My new location.", - "id": "LOCATION_ID", + "id": "3Z4V4WHQK64X9", "instagram_username": "instagram", "language_code": "en-US", "mcc": "1234", - "merchant_id": "MERCHANT_ID", + "merchant_id": "BS11H1A5M511E", "name": "New location name", "status": "ACTIVE", "twitter_username": "twitter", diff --git a/doc/models/create-mobile-authorization-code-request.md b/doc/models/create-mobile-authorization-code-request.md index 5e54e718..978af589 100644 --- a/doc/models/create-mobile-authorization-code-request.md +++ b/doc/models/create-mobile-authorization-code-request.md @@ -2,7 +2,7 @@ # Create Mobile Authorization Code Request Defines the body parameters that can be provided in a request to the -__CreateMobileAuthorizationCode__ endpoint. +`CreateMobileAuthorizationCode` endpoint. ## Structure @@ -12,7 +12,7 @@ __CreateMobileAuthorizationCode__ endpoint. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `location_id` | `string` | Optional | The Square location ID the authorization code should be tied to.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | +| `location_id` | `string` | Optional | The Square location ID that the authorization code should be tied to.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | ## Example (as JSON) diff --git a/doc/models/create-mobile-authorization-code-response.md b/doc/models/create-mobile-authorization-code-response.md index dd07713c..a3fe8307 100644 --- a/doc/models/create-mobile-authorization-code-response.md +++ b/doc/models/create-mobile-authorization-code-response.md @@ -2,7 +2,7 @@ # Create Mobile Authorization Code Response Defines the fields that are included in the response body of -a request to the __CreateMobileAuthorizationCode__ endpoint. +a request to the `CreateMobileAuthorizationCode` endpoint. ## Structure @@ -12,8 +12,8 @@ a request to the __CreateMobileAuthorizationCode__ endpoint. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `authorization_code` | `string` | Optional | Generated authorization code that connects a mobile application instance
to a Square account.
**Constraints**: *Maximum Length*: `191` | -| `expires_at` | `string` | Optional | The timestamp when `authorization_code` expires in
[RFC 3339](https://tools.ietf.org/html/rfc3339) format, e.g., "2016-09-04T23:59:33.123Z".
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | +| `authorization_code` | `string` | Optional | The generated authorization code that connects a mobile application instance
to a Square account.
**Constraints**: *Maximum Length*: `191` | +| `expires_at` | `string` | Optional | The timestamp when `authorization_code` expires, in
[RFC 3339](https://tools.ietf.org/html/rfc3339) format (for example, "2016-09-04T23:59:33.123Z").
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | | `error` | [`Error`](/doc/models/error.md) | Optional | Represents an error encountered during a request to the Connect API.

See [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information. | ## Example (as JSON) diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index 7dfd9aa4..ed4b959a 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -13,7 +13,7 @@ Describes a request to create a payment using | Name | Type | Tags | Description | | --- | --- | --- | --- | | `source_id` | `string` | Required | The ID for the source of funds for this payment. This can be a payment token
(card nonce) generated by the Square payment form or a card on file made with the
Customers API. If recording a payment that the seller
received outside of Square, specify either "CASH" or "EXTERNAL".
For more information, see
[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).
**Constraints**: *Minimum Length*: `1` | -| `idempotency_key` | `string` | Required | A unique string that identifies this `CreatePayment` request. Keys can be any valid string
but must be unique for every `CreatePayment` request.

Max: 45 characters

Note: The number of allowed characters might be less than the stated maximum, if multi-byte
characters are used.

For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `45` | +| `idempotency_key` | `string` | Required | A unique string that identifies this `CreatePayment` request. Keys can be any valid string
but must be unique for every `CreatePayment` request.

Note: The number of allowed characters might be less than the stated maximum, if multi-byte
characters are used.

For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `45` | | `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. | | `tip_money` | [`Money`](/doc/models/money.md) | Optional | 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. | | `app_fee_money` | [`Money`](/doc/models/money.md) | Optional | 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. | @@ -23,13 +23,13 @@ Describes a request to create a payment using | `customer_id` | `string` | Optional | The [Customer](/doc/models/customer.md) ID of the customer associated with the payment.

This is required if the `source_id` refers to a card on file created using the Customers API. | | `location_id` | `string` | Optional | The location ID to associate with the payment. If not specified, the default location is
used. | | `team_member_id` | `string` | Optional | An optional [TeamMember](/doc/models/team-member.md) ID to associate with
this payment. | -| `reference_id` | `string` | Optional | A user-defined ID to associate with the payment.

You can use this field to associate the payment to an entity in an external system
(for example, you might specify an order ID that is generated by a third-party shopping cart).

Limit 40 characters.
**Constraints**: *Maximum Length*: `40` | +| `reference_id` | `string` | Optional | A user-defined ID to associate with the payment.

You can use this field to associate the payment to an entity in an external system
(for example, you might specify an order ID that is generated by a third-party shopping cart).
**Constraints**: *Maximum Length*: `40` | | `verification_token` | `string` | Optional | An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).
Verification tokens encapsulate customer device information and 3-D Secure
challenge results to indicate that Square has verified the buyer identity.

For more information, see [SCA Overview](https://developer.squareup.com/docs/sca-overview). | | `accept_partial_authorization` | `bool` | Optional | If set to `true` and charging a Square Gift Card, a payment might be returned with
`amount_money` equal to less than what was requested. For example, a request for $20 when charging
a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose
to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card
payment. This field cannot be `true` when `autocomplete = true`.

For more information, see
[Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

Default: false | | `buyer_email_address` | `string` | Optional | The buyer's email address.
**Constraints**: *Maximum Length*: `255` | | `billing_address` | [`Address`](/doc/models/address.md) | Optional | Represents a postal address in a country. The address format is based
on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
`Address` object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.

For the remaining address components, the `Address` type provides the
`address_line_1` and `address_line_2` fields for free-form data entry.
These fields are free-form because the remaining address components have
too many variations around the world and typical software does not parse
these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other `Address` type fields are blank.
These include `address_line_3`, `sublocality_2`, `sublocality_3`,
`administrative_district_level_2`, `administrative_district_level_3`,
`first_name`, `last_name`, and `organization`.

When it comes to localization, the seller's language preferences
(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
are ignored for addresses. Even though Square products (such as Square Point of Sale
and the Seller Dashboard) mostly use a seller's language preference in
communication, when it comes to addresses, they will use English for a US address,
Japanese for an address in Japan, and so on. | | `shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a postal address in a country. The address format is based
on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
`Address` object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.

For the remaining address components, the `Address` type provides the
`address_line_1` and `address_line_2` fields for free-form data entry.
These fields are free-form because the remaining address components have
too many variations around the world and typical software does not parse
these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other `Address` type fields are blank.
These include `address_line_3`, `sublocality_2`, `sublocality_3`,
`administrative_district_level_2`, `administrative_district_level_3`,
`first_name`, `last_name`, and `organization`.

When it comes to localization, the seller's language preferences
(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
are ignored for addresses. Even though Square products (such as Square Point of Sale
and the Seller Dashboard) mostly use a seller's language preference in
communication, when it comes to addresses, they will use English for a US address,
Japanese for an address in Japan, and so on. | -| `note` | `string` | Optional | An optional note to be entered by the developer when creating a payment.

Limit 500 characters.
**Constraints**: *Maximum Length*: `500` | +| `note` | `string` | Optional | An optional note to be entered by the developer when creating a payment.
**Constraints**: *Maximum Length*: `500` | | `statement_description_identifier` | `string` | Optional | Optional additional payment information to include on the customer's card statement
as part of the statement description. This can be, for example, an invoice number, ticket number,
or short description that uniquely identifies the purchase.

Note that the `statement_description_identifier` might get truncated on the statement description
to fit the required information including the Square identifier (SQ *) and name of the
seller taking the payment.
**Constraints**: *Maximum Length*: `20` | | `cash_details` | [`Cash Payment Details`](/doc/models/cash-payment-details.md) | Optional | Stores details about a cash payment. Contains only non-confidential information. For more information, see
[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments). | | `external_details` | [`External Payment Details`](/doc/models/external-payment-details.md) | Optional | Stores details about an external payment. Contains only non-confidential information.
For more information, see
[Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments). | diff --git a/doc/models/custom-attribute-filter.md b/doc/models/custom-attribute-filter.md index 20c461f0..cf7d81c5 100644 --- a/doc/models/custom-attribute-filter.md +++ b/doc/models/custom-attribute-filter.md @@ -13,12 +13,12 @@ endpoint to search for items or item variations. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `custom_attribute_definition_id` | `string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`custom_attribute_definition_id`
property value against the the specified id. | -| `key` | `string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`key` property value against
the specified key. | -| `string_filter` | `string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`string_value` property value
against the specified text. | +| `custom_attribute_definition_id` | `string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`custom_attribute_definition_id` property value against the the specified id.
Exactly one of `custom_attribute_definition_id` or `key` must be specified. | +| `key` | `string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`key` property value against the specified key.
Exactly one of `custom_attribute_definition_id` or `key` must be specified. | +| `string_filter` | `string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`string_value` property value against the specified text.
Exactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified. | | `number_filter` | [`Range`](/doc/models/range.md) | Optional | The range of a number value between the specified lower and upper bounds. | -| `selection_uids_filter` | `List of string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`selection_uid_values`
values against the specified selection uids. | -| `bool_filter` | `bool` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`boolean_value` property values
against the specified Boolean expression. | +| `selection_uids_filter` | `List of string` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`selection_uid_values` values against the specified selection uids.
Exactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified. | +| `bool_filter` | `bool` | Optional | A query expression to filter items or item variations by matching their custom attributes'
`boolean_value` property values against the specified Boolean expression.
Exactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified. | ## Example (as JSON) diff --git a/doc/models/invoice.md b/doc/models/invoice.md index 54b52fb6..fc608cbe 100644 --- a/doc/models/invoice.md +++ b/doc/models/invoice.md @@ -19,9 +19,9 @@ invoices. For more information, see [Manage Invoices Using the Invoices API](htt | `primary_recipient` | [`Invoice Recipient`](/doc/models/invoice-recipient.md) | Optional | Represents a snapshot of customer data. This object stores customer data that is displayed on the invoice
and that Square uses to deliver the invoice.

When you provide a customer ID for a draft invoice, Square retrieves the associated customer profile and populates
the remaining `InvoiceRecipient` fields. You cannot update these fields after the invoice is published.
Square updates the customer ID in response to a merge operation, but does not update other fields. | | `payment_requests` | [`List of Invoice Payment Request`](/doc/models/invoice-payment-request.md) | Optional | The payment schedule for the invoice, represented by one or more payment requests that
define payment settings, such as amount due and due date. An invoice supports the following payment request combinations:

- One balance
- One deposit with one balance
- 2–12 installments
- One deposit with 2–12 installments

This field is required when creating an invoice. It must contain at least one payment request.
All payment requests for the invoice must equal the total order amount. For more information, see
[Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests).

Adding `INSTALLMENT` payment requests to an invoice requires an
[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription). | | `delivery_method` | [`str (Invoice Delivery Method)`](/doc/models/invoice-delivery-method.md) | Optional | Indicates how Square delivers the [invoice](/doc/models/invoice.md) to the customer. | -| `invoice_number` | `string` | Optional | A user-friendly invoice number. The value is unique within a location.
If not provided when creating an invoice, Square assigns a value.
It increments from 1 and padded with zeros making it 7 characters long
(for example, 0000001 and 0000002).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | -| `title` | `string` | Optional | The title of the invoice.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `255` | -| `description` | `string` | Optional | The description of the invoice. This is visible to the customer receiving the invoice.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `65536` | +| `invoice_number` | `string` | Optional | A user-friendly invoice number that is displayed on the invoice. The value is unique within a location.
If not provided when creating an invoice, Square assigns a value.
It increments from 1 and is padded with zeros making it 7 characters long
(for example, 0000001 and 0000002).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | +| `title` | `string` | Optional | The title of the invoice, which is displayed on the invoice.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `255` | +| `description` | `string` | Optional | The description of the invoice, which is displayed on the invoice.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `65536` | | `scheduled_at` | `string` | Optional | The timestamp when the invoice is scheduled for processing, in RFC 3339 format.
After the invoice is published, Square processes the invoice on the specified date,
according to the delivery method and payment request settings.

If the field is not set, Square processes the invoice immediately after it is published. | | `public_url` | `string` | Optional | The URL of the Square-hosted invoice page.
After you publish the invoice using the `PublishInvoice` endpoint, Square hosts the invoice
page and returns the page URL in the response. | | `next_payment_amount_money` | [`Money`](/doc/models/money.md) | Optional | 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. | @@ -30,9 +30,10 @@ invoices. For more information, see [Manage Invoices Using the Invoices API](htt | `created_at` | `string` | Optional | The timestamp when the invoice was created, in RFC 3339 format. | | `updated_at` | `string` | Optional | The timestamp when the invoice was last updated, in RFC 3339 format. | | `accepted_payment_methods` | [`Invoice Accepted Payment Methods`](/doc/models/invoice-accepted-payment-methods.md) | Optional | The payment methods that customers can use to pay an invoice on the Square-hosted invoice page. | -| `custom_fields` | [`List of Invoice Custom Field`](/doc/models/invoice-custom-field.md) | Optional | Additional seller-defined fields to render on the invoice. These fields are visible to sellers and buyers
on the Square-hosted invoice page and in emailed or PDF copies of invoices. For more information, see
[Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).

Adding custom fields to an invoice requires an
[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).

Max: 2 custom fields | +| `custom_fields` | [`List of Invoice Custom Field`](/doc/models/invoice-custom-field.md) | Optional | Additional seller-defined fields that are displayed on the invoice. For more information, see
[Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).

Adding custom fields to an invoice requires an
[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).

Max: 2 custom fields | | `subscription_id` | `string` | Optional | The ID of the [subscription](/doc/models/subscription.md) associated with the invoice.
This field is present only on subscription billing invoices. | | `sale_or_service_date` | `string` | Optional | The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format.
This field can be used to specify a past or future date which is displayed on the invoice. | +| `payment_conditions` | `string` | Optional | **France only.** The payment terms and conditions that are displayed on the invoice. For more information,
see [Payment conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions).

For countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and
"Payment conditions are not supported for this location's country" detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `2000` | ## Example (as JSON) diff --git a/doc/models/list-catalog-request.md b/doc/models/list-catalog-request.md index 098476d9..9f8b61b0 100644 --- a/doc/models/list-catalog-request.md +++ b/doc/models/list-catalog-request.md @@ -10,8 +10,8 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `string` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
The page size is currently set to be 100.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `types` | `string` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](/doc/models/catalog-object-type.md) enum, including
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.

If this is unspecified, the operation returns objects of all the types at the version of the Square API used to make the request. | -| `catalog_version` | `long\|int` | Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute. | +| `types` | `string` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](/doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | +| `catalog_version` | `long\|int` | Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](/doc/models/catalog-object.md)s' `version` attribute. If not included, results will
be from the current version of the catalog. | ## Example (as JSON) diff --git a/doc/models/list-locations-response.md b/doc/models/list-locations-response.md index 283ac3fc..d3b39121 100644 --- a/doc/models/list-locations-response.md +++ b/doc/models/list-locations-response.md @@ -1,8 +1,8 @@ # List Locations Response -Defines the fields that are included in the response body of -a request to the __ListLocations__ endpoint. +Defines the fields that are included in the response body of a request +to the [ListLocations](/doc/api/locations.md#list-locations) endpoint. One of `errors` or `locations` is present in a given response (never both). @@ -30,7 +30,7 @@ One of `errors` or `locations` is present in a given response (never both). "locality": "San Francisco", "postal_code": "94114" }, - "business_name": "Pumbaa's business name", + "business_name": "Jet Fuel Coffee", "capabilities": [ "CREDIT_CARD_PROCESSING" ], @@ -40,7 +40,7 @@ One of `errors` or `locations` is present in a given response (never both). "id": "18YC4JDH91E1H", "language_code": "en-US", "merchant_id": "3MYCJG5GVYQ8Q", - "name": "your location name", + "name": "Grant Park", "phone_number": "+1 650-354-7217", "status": "ACTIVE", "timezone": "America/Los_Angeles" diff --git a/doc/models/location-capability.md b/doc/models/location-capability.md index 19de383f..11907ce4 100644 --- a/doc/models/location-capability.md +++ b/doc/models/location-capability.md @@ -11,6 +11,6 @@ The capabilities a location may have. | Name | Description | | --- | --- | -| `CREDIT_CARD_PROCESSING` | The permission to process credit card transactions with Square.

The location can process credit cards if this value is present
in the `capabilities` array of the `Location`. | -| `AUTOMATIC_TRANSFERS` | The capability to receive automatic transfers from Square.

The location can receive automatic transfers of their balance from Square if this value
is present in the `capabilities` array of the `Location`. | +| `CREDIT_CARD_PROCESSING` | The capability to process credit card transactions with Square. | +| `AUTOMATIC_TRANSFERS` | The capability to receive automatic transfers from Square. | diff --git a/doc/models/location-status.md b/doc/models/location-status.md index 8ab3e82f..02db59cb 100644 --- a/doc/models/location-status.md +++ b/doc/models/location-status.md @@ -1,7 +1,7 @@ # Location Status -The status of the location, whether a location is active or inactive. +A location's status. ## Enumeration @@ -12,5 +12,5 @@ The status of the location, whether a location is active or inactive. | Name | Description | | --- | --- | | `ACTIVE` | A location that is active for business. | -| `INACTIVE` | A location that is not active for business. Inactive locations just provide historical
information, so typically clients limit interaction with or hide these locations. | +| `INACTIVE` | A location that is not active for business. Inactive locations provide historical
information. Hide inactive locations unless the user has requested to see them. | diff --git a/doc/models/location-type.md b/doc/models/location-type.md index 62e9ee32..ecab781d 100644 --- a/doc/models/location-type.md +++ b/doc/models/location-type.md @@ -1,7 +1,7 @@ # Location Type -A location's physical or mobile type. +A location's type. ## Enumeration diff --git a/doc/models/location.md b/doc/models/location.md index 9b8fc58e..a653f441 100644 --- a/doc/models/location.md +++ b/doc/models/location.md @@ -1,7 +1,7 @@ # Location -Represents one of a business's locations. +Represents one of a business's [locations](https://developer.squareup.com/docs/locations-api). ## Structure @@ -11,32 +11,32 @@ Represents one of a business's locations. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `id` | `string` | Optional | The Square-issued ID of the location. | +| `id` | `string` | Optional | A short, generated string of letters and numbers that uniquely identifies this location instance. | | `name` | `string` | Optional | The name of the location.
This information appears in the dashboard as the nickname.
A location name must be unique within a seller account. | | `address` | [`Address`](/doc/models/address.md) | Optional | Represents a postal address in a country. The address format is based
on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
`Address` object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.

For the remaining address components, the `Address` type provides the
`address_line_1` and `address_line_2` fields for free-form data entry.
These fields are free-form because the remaining address components have
too many variations around the world and typical software does not parse
these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other `Address` type fields are blank.
These include `address_line_3`, `sublocality_2`, `sublocality_3`,
`administrative_district_level_2`, `administrative_district_level_3`,
`first_name`, `last_name`, and `organization`.

When it comes to localization, the seller's language preferences
(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
are ignored for addresses. Even though Square products (such as Square Point of Sale
and the Seller Dashboard) mostly use a seller's language preference in
communication, when it comes to addresses, they will use English for a US address,
Japanese for an address in Japan, and so on. | -| `timezone` | `string` | Optional | The [IANA Timezone](https://www.iana.org/time-zones) identifier for
the timezone of the location. | +| `timezone` | `string` | Optional | The [IANA Timezone](https://www.iana.org/time-zones) identifier for
the timezone of the location. For example, `"America/Los_Angeles"`. | | `capabilities` | [`List of str (Location Capability)`](/doc/models/location-capability.md) | Optional | The Square features that are enabled for the location.
See [LocationCapability](/doc/models/location-capability.md) for possible values.
See [LocationCapability](#type-locationcapability) for possible values | -| `status` | [`str (Location Status)`](/doc/models/location-status.md) | Optional | The status of the location, whether a location is active or inactive. | +| `status` | [`str (Location Status)`](/doc/models/location-status.md) | Optional | A location's status. | | `created_at` | `string` | Optional | The time when the location was created, in RFC 3339 format.
For more information, see [Working with Dates](https://developer.squareup.com/docs/build-basics/working-with-dates). | | `merchant_id` | `string` | Optional | The ID of the merchant that owns the location. | | `country` | [`str (Country)`](/doc/models/country.md) | Optional | Indicates the country associated with another entity, such as a business.
Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm). | | `language_code` | `string` | Optional | The language associated with the location, in
[BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A).
For more information, see [Location language code](https://developer.squareup.com/docs/locations-api#location-language-code). | | `currency` | [`str (Currency)`](/doc/models/currency.md) | Optional | Indicates the associated currency for an amount of money. Values correspond
to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). | | `phone_number` | `string` | Optional | The phone number of the location in human readable format. For example, `+353 80 0 098 8099`. | -| `business_name` | `string` | Optional | The business name of the location
This is the name visible to the customers of the location.
For example, this name appears on customer receipts. | -| `type` | [`str (Location Type)`](/doc/models/location-type.md) | Optional | A location's physical or mobile type. | +| `business_name` | `string` | Optional | The business name of the location, visible to the location's customers. | +| `type` | [`str (Location Type)`](/doc/models/location-type.md) | Optional | A location's type. | | `website_url` | `string` | Optional | The website URL of the location. For example, `https://squareup.com`. | -| `business_hours` | [`Business Hours`](/doc/models/business-hours.md) | Optional | Represents the hours of operation for a business location. | -| `business_email` | `string` | Optional | The email of the location.
This email is visible to the customers of the location.
For example, the email appears on customer receipts.
For example, `help@squareup.com`. | -| `description` | `string` | Optional | The description of the location. | +| `business_hours` | [`Business Hours`](/doc/models/business-hours.md) | Optional | The hours of operation for a location. | +| `business_email` | `string` | Optional | The email address of the location, visible to the location's customers.
This can be unique to the location, and is not always the email address for the business owner or admin. | +| `description` | `string` | Optional | The description of the location. For example, `Main Street location`. | | `twitter_username` | `string` | Optional | The Twitter username of the location without the '@' symbol. For example, `Square`. | | `instagram_username` | `string` | Optional | The Instagram username of the location without the '@' symbol. For example, `square`. | | `facebook_url` | `string` | Optional | The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example, `https://www.facebook.com/square`. | | `coordinates` | [`Coordinates`](/doc/models/coordinates.md) | Optional | Latitude and longitude coordinates. | -| `logo_url` | `string` | Optional | The URL of the logo image for the location. The Seller must choose this logo in the Seller
dashboard (Receipts section) for the logo to appear on transactions (such as receipts, invoices)
that Square generates on behalf of the Seller. This image should have an aspect ratio
close to 1:1 and is recommended to be at least 200x200 pixels. | +| `logo_url` | `string` | Optional | The URL of the logo image for the location. When configured in the Seller
dashboard (Receipts section), the logo appears on transactions (such as receipts and invoices)
that Square generates on behalf of the Seller. This image should have a roughly square (1:1) aspect ratio
and is recommended to be at least 200x200 pixels. | | `pos_background_url` | `string` | Optional | The URL of the Point of Sale background image for the location. | -| `mcc` | `string` | Optional | The merchant category code (MCC) of the location, as standardized by ISO 18245.
The MCC describes the kind of goods or services sold at the location. | -| `full_format_logo_url` | `string` | Optional | The URL of a full-format logo image for the location. The Seller must choose this logo in the
Seller dashboard (Receipts section) for the logo to appear on transactions (such as receipts, invoices)
that Square generates on behalf of the Seller. This image can have an aspect ratio of 2:1 or greater
and is recommended to be at least 1280x648 pixels. | +| `mcc` | `string` | Optional | A four-digit number that describes the kind of goods or services sold at the location.
The merchant category code (MCC) of the location is standardized by ISO 18245.
For example, `5045`. | +| `full_format_logo_url` | `string` | Optional | The URL of a full-format logo image for the location. When configured in the Seller
dashboard (Receipts section), the logo appears on transactions (such as receipts and invoices)
that Square generates on behalf of the Seller. This image can be wider than it is tall,
and is recommended to be at least 1280x648 pixels. | | `tax_ids` | [`Tax Ids`](/doc/models/tax-ids.md) | Optional | The tax IDs that a Location is operating under. | ## Example (as JSON) diff --git a/doc/models/obtain-token-request.md b/doc/models/obtain-token-request.md index 70df4228..897a630f 100644 --- a/doc/models/obtain-token-request.md +++ b/doc/models/obtain-token-request.md @@ -9,15 +9,15 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `client_id` | `string` | Required | The Square-issued ID of your application, available from the OAuth page
for your application on the Developer Dashboard.
**Constraints**: *Maximum Length*: `191` | -| `client_secret` | `string` | Required | The Square-issued application secret for your application, available
from the OAuth page for your application on the Developer Dashboard.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | -| `code` | `string` | Optional | The authorization code to exchange.
This is required if `grant_type` is set to `authorization_code`, to indicate that
the application wants to exchange an authorization code for an OAuth access token.
**Constraints**: *Maximum Length*: `191` | -| `redirect_uri` | `string` | Optional | The redirect URL assigned in the OAuth page for your application on the Developer Dashboard.
**Constraints**: *Maximum Length*: `2048` | -| `grant_type` | `string` | Required | Specifies the method to request an OAuth access token.
Valid values are: `authorization_code`, `refresh_token`, and `migration_token`
**Constraints**: *Minimum Length*: `10`, *Maximum Length*: `20` | -| `refresh_token` | `string` | Optional | A valid refresh token for generating a new OAuth access token.
A valid refresh token is required if `grant_type` is set to `refresh_token` , to indicate the application wants a replacement for an expired OAuth access token.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | -| `migration_token` | `string` | Optional | Legacy OAuth access token obtained using a Connect API version prior
to 2019-03-13. This parameter is required if `grant_type` is set to
`migration_token` to indicate that the application wants to get a replacement
OAuth access token. The response also returns a refresh token.
For more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | -| `scopes` | `List of string` | Optional | A JSON list of strings representing the permissions the application is requesting.
For example: "`["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]`"
The access token returned in the response is granted the permissions
that comprise the intersection between the requested list of permissions, and those
that belong to the provided refresh token. | -| `short_lived` | `bool` | Optional | A boolean indicating a request for a short-lived access token.
The short-lived access token returned in the response expires in 24 hours. | +| `client_id` | `string` | Required | The Square-issued ID of your application, which is available in the OAuth page in the
[Developer Dashboard](https://developer.squareup.com/apps).
**Constraints**: *Maximum Length*: `191` | +| `client_secret` | `string` | Required | The Square-issued application secret for your application, which is available in the OAuth page
in the [Developer Dashboard](https://developer.squareup.com/apps).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | +| `code` | `string` | Optional | The authorization code to exchange.
This code is required if `grant_type` is set to `authorization_code` to indicate that
the application wants to exchange an authorization code for an OAuth access token.
**Constraints**: *Maximum Length*: `191` | +| `redirect_uri` | `string` | Optional | The redirect URL assigned in the OAuth page for your application in the [Developer Dashboard](https://developer.squareup.com/apps).
**Constraints**: *Maximum Length*: `2048` | +| `grant_type` | `string` | Required | Specifies the method to request an OAuth access token.
Valid values are `authorization_code`, `refresh_token`, and `migration_token`.
**Constraints**: *Minimum Length*: `10`, *Maximum Length*: `20` | +| `refresh_token` | `string` | Optional | A valid refresh token for generating a new OAuth access token.

A valid refresh token is required if `grant_type` is set to `refresh_token`
to indicate that the application wants a replacement for an expired OAuth access token.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | +| `migration_token` | `string` | Optional | A legacy OAuth access token obtained using a Connect API version prior
to 2019-03-13. This parameter is required if `grant_type` is set to
`migration_token` to indicate that the application wants to get a replacement
OAuth access token. The response also returns a refresh token.
For more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | +| `scopes` | `List of string` | Optional | A JSON list of strings representing the permissions that the application is requesting.
For example, "`["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]`".

The access token returned in the response is granted the permissions
that comprise the intersection between the requested list of permissions and those
that belong to the provided refresh token. | +| `short_lived` | `bool` | Optional | A Boolean indicating a request for a short-lived access token.

The short-lived access token returned in the response expires in 24 hours. | ## Example (as JSON) diff --git a/doc/models/obtain-token-response.md b/doc/models/obtain-token-response.md index 217205b8..3cddc066 100644 --- a/doc/models/obtain-token-response.md +++ b/doc/models/obtain-token-response.md @@ -9,15 +9,15 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `access_token` | `string` | Optional | A valid OAuth access token. OAuth access tokens are 64 bytes long.
Provide the access token in a header with every request to Connect API
endpoints. See [OAuth API: Walkthrough](https://developer.squareup.com/docs/oauth-api/walkthrough)
for more information.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | +| `access_token` | `string` | Optional | A valid OAuth access token. OAuth access tokens are 64 bytes long.
Provide the access token in a header with every request to Connect API
endpoints. For more information, see [OAuth API: Walkthrough](https://developer.squareup.com/docs/oauth-api/walkthrough).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | | `token_type` | `string` | Optional | This value is always _bearer_.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `10` | -| `expires_at` | `string` | Optional | The date when the access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | +| `expires_at` | `string` | Optional | The date when the `access_token` expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | | `merchant_id` | `string` | Optional | The ID of the authorizing merchant's business.
**Constraints**: *Minimum Length*: `8`, *Maximum Length*: `191` | -| `subscription_id` | `string` | Optional | __LEGACY FIELD__. The ID of a subscription plan the merchant signed up
for. Only present if the merchant signed up for a subscription during authorization. | -| `plan_id` | `string` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. Only present if the merchant signed up for a subscription during
authorization. | -| `id_token` | `string` | Optional | The OpenID token belonging to this person. Only present if the
OPENID scope is included in the authorization request. | +| `subscription_id` | `string` | Optional | __LEGACY FIELD__. The ID of a subscription plan the merchant signed up
for. The ID is only present if the merchant signed up for a subscription plan during authorization. | +| `plan_id` | `string` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. The ID is only present if the merchant signed up for a subscription plan during
authorization. | +| `id_token` | `string` | Optional | The OpenID token belonging to this person. This token is only present if the
OPENID scope is included in the authorization request. | | `refresh_token` | `string` | Optional | A refresh token. OAuth refresh tokens are 64 bytes long.
For more information, see [Refresh, Revoke, and Limit the Scope of OAuth Tokens](https://developer.squareup.com/docs/oauth-api/refresh-revoke-limit-scope).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | -| `short_lived` | `bool` | Optional | A boolean indicating the access token is a short-lived access token.
The short-lived access token returned in the response will expire in 24 hours. | +| `short_lived` | `bool` | Optional | A Boolean indicating that the access token is a short-lived access token.
The short-lived access token returned in the response expires in 24 hours. | ## Example (as JSON) diff --git a/doc/models/range.md b/doc/models/range.md index e7d155e2..b7874bbe 100644 --- a/doc/models/range.md +++ b/doc/models/range.md @@ -11,8 +11,8 @@ The range of a number value between the specified lower and upper bounds. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `min` | `string` | Optional | The lower bound of the number range. | -| `max` | `string` | Optional | The upper bound of the number range. | +| `min` | `string` | Optional | The lower bound of the number range. At least one of `min` or `max` must be specified.
If unspecified, the results will have no minimum value. | +| `max` | `string` | Optional | The upper bound of the number range. At least one of `min` or `max` must be specified.
If unspecified, the results will have no maximum value. | ## Example (as JSON) diff --git a/doc/models/renew-token-response.md b/doc/models/renew-token-response.md index efeeabc7..0c4ec3be 100644 --- a/doc/models/renew-token-response.md +++ b/doc/models/renew-token-response.md @@ -11,10 +11,10 @@ | --- | --- | --- | --- | | `access_token` | `string` | Optional | The renewed access token.
This value might be different from the `access_token` you provided in your request.
You provide this token in a header with every request to Connect API endpoints.
See [Request and response headers](https://developer.squareup.com/docs/api/connect/v2/#requestandresponseheaders) for the format of this header.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | | `token_type` | `string` | Optional | This value is always _bearer_.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `10` | -| `expires_at` | `string` | Optional | The date when access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | +| `expires_at` | `string` | Optional | The date when the `access_token` expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
**Constraints**: *Minimum Length*: `20`, *Maximum Length*: `48` | | `merchant_id` | `string` | Optional | The ID of the authorizing merchant's business.
**Constraints**: *Minimum Length*: `8`, *Maximum Length*: `191` | -| `subscription_id` | `string` | Optional | __LEGACY FIELD__. The ID of the merchant subscription associated with
the authorization. Only present if the merchant signed up for a subscription
during authorization.. | -| `plan_id` | `string` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. Only present if the merchant signed up for a subscription during
authorization. | +| `subscription_id` | `string` | Optional | __LEGACY FIELD__. The ID of the merchant subscription associated with
the authorization. The ID is only present if the merchant signed up for a subscription
during authorization. | +| `plan_id` | `string` | Optional | __LEGACY FIELD__. The ID of the subscription plan the merchant signed
up for. The ID is only present if the merchant signed up for a subscription plan during
authorization. | ## Example (as JSON) diff --git a/doc/models/retrieve-catalog-object-request.md b/doc/models/retrieve-catalog-object-request.md index 04a70fff..19827240 100644 --- a/doc/models/retrieve-catalog-object-request.md +++ b/doc/models/retrieve-catalog-object-request.md @@ -9,8 +9,8 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `include_related_objects` | `bool` | Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If the `object` field of the response contains a `CatalogItem`, its associated
`CatalogCategory`, `CatalogTax`, `CatalogImage` and `CatalogModifierList` objects will
be returned in the `related_objects` field of the response. If the `object` field of
the response contains a `CatalogItemVariation`, its parent `CatalogItem` will be returned
in the `related_objects` field of the response.

Default value: `false` | -| `catalog_version` | `long\|int` | Optional | Requests objects as of a specific version of the catalog. This allows you to retrieve historical
versions of objects. The value to retrieve a specific version of an object can be found
in the version field of [CatalogObject](/doc/models/catalog-object.md)s. | +| `include_related_objects` | `bool` | Optional | If `true`, the response will include additional objects that are related to the
requested objects. Related objects are defined as any objects referenced by ID by the results in the `objects` field
of the response. These objects are put in the `related_objects` field. Setting this to `true` is
helpful when the objects are needed for immediate display to a user.
This process only goes one level deep. Objects referenced by the related objects will not be included. For example,

if the `objects` field of the response contains a CatalogItem, its associated
CatalogCategory objects, CatalogTax objects, CatalogImage objects and
CatalogModifierLists will be returned in the `related_objects` field of the
response. If the `objects` field of the response contains a CatalogItemVariation,
its parent CatalogItem will be returned in the `related_objects` field of
the response.

Default value: `false` | +| `catalog_version` | `long\|int` | Optional | Requests objects as of a specific version of the catalog. This allows you to retrieve historical
versions of objects. The value to retrieve a specific version of an object can be found
in the version field of [CatalogObject](/doc/models/catalog-object.md)s. If not included, results will
be from the current version of the catalog. | ## Example (as JSON) diff --git a/doc/models/retrieve-location-response.md b/doc/models/retrieve-location-response.md index f786f220..73036962 100644 --- a/doc/models/retrieve-location-response.md +++ b/doc/models/retrieve-location-response.md @@ -1,9 +1,8 @@ # Retrieve Location Response -Defines the fields that the -[RetrieveLocation](/doc/api/locations.md#retrieve-location) endpoint returns -in a response. +Defines the fields that the [RetrieveLocation](/doc/api/locations.md#retrieve-location) +endpoint returns in a response. ## Structure @@ -14,7 +13,7 @@ in a response. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's [locations](https://developer.squareup.com/docs/locations-api). | ## Example (as JSON) @@ -38,7 +37,7 @@ in a response. "id": "18YC4JDH91E1H", "language_code": "en-US", "merchant_id": "3MYCJG5GVYQ8Q", - "name": "Jet Fuel Coffee - Grant Park", + "name": "Grant Park", "phone_number": "+1 650-354-7217", "status": "ACTIVE", "timezone": "America/Los_Angeles" diff --git a/doc/models/revoke-token-request.md b/doc/models/revoke-token-request.md index 22f17801..eb37fc00 100644 --- a/doc/models/revoke-token-request.md +++ b/doc/models/revoke-token-request.md @@ -9,9 +9,9 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `client_id` | `string` | Optional | The Square-issued ID for your application, available from
the OAuth page for your application on the Developer Dashboard.
**Constraints**: *Maximum Length*: `191` | -| `access_token` | `string` | Optional | The access token of the merchant whose token you want to revoke.
Do not provide a value for merchant_id if you provide this parameter.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | -| `merchant_id` | `string` | Optional | The ID of the merchant whose token you want to revoke.
Do not provide a value for access_token if you provide this parameter. | +| `client_id` | `string` | Optional | The Square-issued ID for your application, which is available in the OAuth page in the
[Developer Dashboard](https://developer.squareup.com/apps).
**Constraints**: *Maximum Length*: `191` | +| `access_token` | `string` | Optional | The access token of the merchant whose token you want to revoke.
Do not provide a value for `merchant_id` if you provide this parameter.
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` | +| `merchant_id` | `string` | Optional | The ID of the merchant whose token you want to revoke.
Do not provide a value for `access_token` if you provide this parameter. | | `revoke_only_access_token` | `bool` | Optional | If `true`, terminate the given single access token, but do not
terminate the entire authorization.
Default: `false` | ## Example (as JSON) diff --git a/doc/models/revoke-token-response.md b/doc/models/revoke-token-response.md index 6ef06fff..97081f88 100644 --- a/doc/models/revoke-token-response.md +++ b/doc/models/revoke-token-response.md @@ -9,7 +9,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `success` | `bool` | Optional | If the request is successful, this is true. | +| `success` | `bool` | Optional | If the request is successful, this is `true`. | ## Example (as JSON) diff --git a/doc/models/search-catalog-objects-request.md b/doc/models/search-catalog-objects-request.md index c5b22173..2ab20149 100644 --- a/doc/models/search-catalog-objects-request.md +++ b/doc/models/search-catalog-objects-request.md @@ -10,9 +10,9 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `string` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `object_types` | [`List of str (Catalog Object Type)`](/doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results.

If not specified, the following catalog object types will be used as default:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | +| `object_types` | [`List of str (Catalog Object Type)`](/doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | | `include_deleted_objects` | `bool` | Optional | If `true`, deleted objects will be included in the results. Deleted objects will have their
`is_deleted` field set to `true`. | -| `include_related_objects` | `bool` | Optional | If `true`, the response will include additional objects that are related to the
requested object, as follows:

If a CatalogItem is returned in the object field of the response,
its associated CatalogCategory, CatalogTax objects,
CatalogImage objects and CatalogModifierList objects
will be included in the `related_objects` field of the response.

If a CatalogItemVariation is returned in the object field of the
response, its parent CatalogItem will be included in the `related_objects` field of
the response. | +| `include_related_objects` | `bool` | Optional | If `true`, the response will include additional objects that are related to the
requested objects. Related objects are objects that are referenced by object ID by the objects
in the response. This is helpful if the objects are being fetched for immediate display to a user.
This process only goes one level deep. Objects referenced by the related objects will not be included.
For example:

If the `objects` field of the response contains a CatalogItem, its associated
CatalogCategory objects, CatalogTax objects, CatalogImage objects and
CatalogModifierLists will be returned in the `related_objects` field of the
response. If the `objects` field of the response contains a CatalogItemVariation,
its parent CatalogItem will be returned in the `related_objects` field of
the response.

Default value: `false` | | `begin_time` | `string` | Optional | Return objects modified after this [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), in RFC 3339
format, e.g., `2016-09-04T23:59:33.123Z`. The timestamp is exclusive - objects with a
timestamp equal to `begin_time` will not be included in the response. | | `query` | [`Catalog Query`](/doc/models/catalog-query.md) | Optional | A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the `SearchCatalogObjects` endpoint.

Although a query can have multiple filters, only certain query types can be combined per call to [SearchCatalogObjects](/doc/api/catalog.md#search-catalog-objects).
Any combination of the following types may be used together:

- [exact_query](/doc/models/catalog-query-exact.md)
- [prefix_query](/doc/models/catalog-query-prefix.md)
- [range_query](/doc/models/catalog-query-range.md)
- [sorted_attribute_query](/doc/models/catalog-query-sorted-attribute.md)
- [text_query](/doc/models/catalog-query-text.md)
All other query types cannot be combined with any others.

When a query filter is based on an attribute, the attribute must be searchable.
Searchable attributes are listed as follows, along their parent types that can be searched for with applicable query filters.

* Searchable attribute and objects queryable by searchable attributes **

- `name`: `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, `CatalogTax`, `CatalogDiscount`, `CatalogModifier`, 'CatalogModifierList`,`CatalogItemOption`,`CatalogItemOptionValue`
- `description`: `CatalogItem`, `CatalogItemOptionValue`
- `abbreviation`: `CatalogItem`
- `upc`: `CatalogItemVariation`
- `sku`: `CatalogItemVariation`
- `caption`: `CatalogImage`
- `display_name`: `CatalogItemOption`

For example, to search for [CatalogItem](/doc/models/catalog-item.md) objects by searchable attributes, you can use
the `"name"`, `"description"`, or `"abbreviation"` attribute in an applicable query filter. | | `limit` | `int` | Optional | A limit on the number of results to be returned in a single page. The limit is advisory -
the implementation may return more or fewer results. If the supplied limit is negative, zero, or
is higher than the maximum limit of 1,000, it will be ignored. | diff --git a/doc/models/search-subscriptions-request.md b/doc/models/search-subscriptions-request.md index 388596fa..178b01f7 100644 --- a/doc/models/search-subscriptions-request.md +++ b/doc/models/search-subscriptions-request.md @@ -15,7 +15,7 @@ Defines input parameters in a request to the | `cursor` | `string` | Optional | When the total number of resulting subscriptions exceeds the limit of a paged response,
specify the cursor returned from a preceding response here to fetch the next set of results.
If the cursor is unset, the response contains the last page of the results.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | | `limit` | `int` | Optional | The upper limit on the number of subscriptions to return
in a paged response.
**Constraints**: `>= 1` | | `query` | [`Search Subscriptions Query`](/doc/models/search-subscriptions-query.md) | Optional | Represents a query, consisting of specified query expressions, used to search for subscriptions. | -| `include` | `List of string` | Optional | A query parameter to specify related information to be included in the response.

The supported query parameter values are:

- `actions`: to include scheduled actions on the targeted subscriptions. | +| `include` | `List of string` | Optional | An option to include related information in the response.

The supported values are:

- `actions`: to include scheduled actions on the targeted subscriptions. | ## Example (as JSON) diff --git a/doc/models/subscription.md b/doc/models/subscription.md index 3bc17a66..af418ed1 100644 --- a/doc/models/subscription.md +++ b/doc/models/subscription.md @@ -30,7 +30,7 @@ For an overview of the `Subscription` type, see | `card_id` | `string` | Optional | The ID of the [subscriber's](/doc/models/customer.md) [card](/doc/models/card.md)
used to charge for the subscription. | | `timezone` | `string` | Optional | Timezone that will be used in date calculations for the subscription.
Defaults to the timezone of the location based on `location_id`.
Format: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`). | | `source` | [`Subscription Source`](/doc/models/subscription-source.md) | Optional | The origination details of the subscription. | -| `actions` | [`List of Subscription Action`](/doc/models/subscription-action.md) | Optional | The list of scheduled actions on this subscription. It is set only in the response from the
[RetrieveSubscription](/doc/api/subscriptions.md#retrieve-subscription) or
[SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) endpoint with the query parameter
of `include=actions`. | +| `actions` | [`List of Subscription Action`](/doc/models/subscription-action.md) | Optional | The list of scheduled actions on this subscription. It is set only in the response from
[RetrieveSubscription](/doc/api/subscriptions.md#retrieve-subscription) with the query parameter
of `include=actions` or from
[SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) with the input parameter
of `include:["actions"]`. | ## Example (as JSON) diff --git a/doc/models/update-catalog-image-request.md b/doc/models/update-catalog-image-request.md new file mode 100644 index 00000000..3e208d92 --- /dev/null +++ b/doc/models/update-catalog-image-request.md @@ -0,0 +1,29 @@ + +# Update Catalog Image Request + +## Structure + +`Update Catalog Image Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `idempotency_key` | `string` | Required | A unique string that identifies this UpdateCatalogImage request.
Keys can be any valid string but must be unique for every UpdateCatalogImage request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1` | + +## Example (as JSON) + +```json +{ + "idempotency_key": "528dea59-7bfb-43c1-bd48-4a6bba7dd61f86", + "image": { + "image_data": { + "caption": "A picture of a cup of coffee", + "name": "Coffee" + }, + "type": "IMAGE" + }, + "object_id": "ND6EA5AAJEO5WL3JNNIAQA32" +} +``` + diff --git a/doc/models/update-catalog-image-response.md b/doc/models/update-catalog-image-response.md new file mode 100644 index 00000000..6c1e58ef --- /dev/null +++ b/doc/models/update-catalog-image-response.md @@ -0,0 +1,30 @@ + +# Update Catalog Image Response + +## Structure + +`Update Catalog Image Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | +| `image` | [`Catalog Object`](/doc/models/catalog-object.md) | Optional | The wrapper object for the catalog entries of a given object type.

Depending on the `type` attribute value, a `CatalogObject` instance assumes a type-specific data to yield the corresponding type of catalog object.

For example, if `type=ITEM`, the `CatalogObject` instance must have the ITEM-specific data set on the `item_data` attribute. The resulting `CatalogObject` instance is also a `CatalogItem` instance.

In general, if `type=`, the `CatalogObject` instance must have the ``-specific data set on the `_data` attribute. The resulting `CatalogObject` instance is also a `Catalog` instance.

For a more detailed discussion of the Catalog data model, please see the
[Design a Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog) guide. | + +## Example (as JSON) + +```json +{ + "image": { + "id": "L52QOQN2SW3M5QTF9JOCQKNB", + "image_data": { + "caption": "A picture of a cup of coffee", + "name": "Coffee", + "url": "https://..." + }, + "type": "IMAGE" + } +} +``` + diff --git a/doc/models/update-item-modifier-lists-request.md b/doc/models/update-item-modifier-lists-request.md index a40f218c..f3189c7f 100644 --- a/doc/models/update-item-modifier-lists-request.md +++ b/doc/models/update-item-modifier-lists-request.md @@ -10,8 +10,8 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `item_ids` | `List of string` | Required | The IDs of the catalog items associated with the CatalogModifierList objects being updated. | -| `modifier_lists_to_enable` | `List of string` | Optional | The IDs of the CatalogModifierList objects to enable for the CatalogItem. | -| `modifier_lists_to_disable` | `List of string` | Optional | The IDs of the CatalogModifierList objects to disable for the CatalogItem. | +| `modifier_lists_to_enable` | `List of string` | Optional | The IDs of the CatalogModifierList objects to enable for the CatalogItem.
At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified. | +| `modifier_lists_to_disable` | `List of string` | Optional | The IDs of the CatalogModifierList objects to disable for the CatalogItem.
At least one of `modifier_lists_to_enable` or `modifier_lists_to_disable` must be specified. | ## Example (as JSON) diff --git a/doc/models/update-item-taxes-request.md b/doc/models/update-item-taxes-request.md index 5f0a6280..62467d77 100644 --- a/doc/models/update-item-taxes-request.md +++ b/doc/models/update-item-taxes-request.md @@ -9,9 +9,9 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `item_ids` | `List of string` | Required | IDs for the CatalogItems associated with the CatalogTax objects being updated. | -| `taxes_to_enable` | `List of string` | Optional | IDs of the CatalogTax objects to enable. | -| `taxes_to_disable` | `List of string` | Optional | IDs of the CatalogTax objects to disable. | +| `item_ids` | `List of string` | Required | IDs for the CatalogItems associated with the CatalogTax objects being updated.
No more than 1,000 IDs may be provided. | +| `taxes_to_enable` | `List of string` | Optional | IDs of the CatalogTax objects to enable.
At least one of `taxes_to_enable` or `taxes_to_disable` must be specified. | +| `taxes_to_disable` | `List of string` | Optional | IDs of the CatalogTax objects to disable.
At least one of `taxes_to_enable` or `taxes_to_disable` must be specified. | ## Example (as JSON) diff --git a/doc/models/update-location-request.md b/doc/models/update-location-request.md index 1a66d535..fe565416 100644 --- a/doc/models/update-location-request.md +++ b/doc/models/update-location-request.md @@ -11,7 +11,7 @@ Request object for the [UpdateLocation](/doc/api/locations.md#update-location) e | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's [locations](https://developer.squareup.com/docs/locations-api). | ## Example (as JSON) diff --git a/doc/models/update-location-response.md b/doc/models/update-location-response.md index f259b1d5..e3fafd1e 100644 --- a/doc/models/update-location-response.md +++ b/doc/models/update-location-response.md @@ -12,7 +12,7 @@ Response object returned by the [UpdateLocation](/doc/api/locations.md#update-lo | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's locations. | +| `location` | [`Location`](/doc/models/location.md) | Optional | Represents one of a business's [locations](https://developer.squareup.com/docs/locations-api). | ## Example (as JSON) diff --git a/doc/models/update-payment-request.md b/doc/models/update-payment-request.md index dae541e5..540e914e 100644 --- a/doc/models/update-payment-request.md +++ b/doc/models/update-payment-request.md @@ -13,7 +13,7 @@ Describes a request to update a payment using | Name | Type | Tags | Description | | --- | --- | --- | --- | | `payment` | [`Payment`](/doc/models/payment.md) | Optional | Represents a payment processed by the Square API. | -| `idempotency_key` | `string` | Required | A unique string that identifies this `UpdatePayment` request. Keys can be any valid string
but must be unique for every `UpdatePayment` request.

The maximum is 45 characters.

For more information, see [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `45` | +| `idempotency_key` | `string` | Required | A unique string that identifies this `UpdatePayment` request. Keys can be any valid string
but must be unique for every `UpdatePayment` request.

For more information, see [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `45` | ## Example (as JSON) diff --git a/setup.py b/setup.py index 7802e4d5..cbaf771d 100644 --- a/setup.py +++ b/setup.py @@ -12,7 +12,7 @@ setup( name='squareup', - version='16.0.0.20211117', + version='17.0.0.20211215', description='Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.', long_description=long_description, long_description_content_type="text/markdown", diff --git a/square/api/base_api.py b/square/api/base_api.py index 0ffc0172..27983ed9 100644 --- a/square/api/base_api.py +++ b/square/api/base_api.py @@ -1,5 +1,6 @@ # -*- coding: utf-8 -*- +import platform from square.api_helper import APIHelper @@ -21,7 +22,7 @@ class BaseApi(object): def global_headers(self): return { - 'user-agent': 'Square-Python-SDK/16.0.0.20211117', + 'user-agent': self.get_user_agent() , 'Square-Version': self.config.square_version } @@ -78,3 +79,11 @@ def execute_request(self, request, binary=False): self.http_call_back.on_after_response(response) return response + + def get_user_agent(self): + user_agent = 'Square-Python-SDK/17.0.0.20211215' + parameters = { + } + + agent = APIHelper.append_url_with_template_parameters(user_agent, parameters) + return agent.replace(' ', ' ') diff --git a/square/api/catalog_api.py b/square/api/catalog_api.py index 906b8bf4..ef3292bc 100644 --- a/square/api/catalog_api.py +++ b/square/api/catalog_api.py @@ -200,10 +200,12 @@ def create_catalog_image(self, """Does a POST request to /v2/catalog/images. Uploads an image file to be represented by a - [CatalogImage]($m/CatalogImage) object linked to an existing - [CatalogObject]($m/CatalogObject) instance. A call to this endpoint - can upload an image, link an image to - a catalog object, or do both. + [CatalogImage]($m/CatalogImage) object that can be linked to an + existing + [CatalogObject]($m/CatalogObject) instance. The resulting + `CatalogImage` is unattached to any `CatalogObject` if the + `object_id` + is not specified. This `CreateCatalogImage` endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB. @@ -263,6 +265,78 @@ def create_catalog_image(self, _result = ApiResponse(_response, body=decoded, errors=_errors) return _result + def update_catalog_image(self, + image_id, + request=None, + image_file=None): + """Does a PUT request to /v2/catalog/images/{image_id}. + + Uploads a new image file to replace the existing one in the specified + [CatalogImage]($m/CatalogImage) object. + This `UpdateCatalogImage` endpoint accepts HTTP multipart/form-data + requests with a JSON part and an image file part in + JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB. + + Args: + image_id (string): The ID of the `CatalogImage` object to update + the encapsulated image file. + request (UpdateCatalogImageRequest, optional): TODO: type + description here. + image_file (typing.BinaryIO, optional): TODO: type description + here. + + 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. + + """ + + # Prepare query URL + _url_path = '/v2/catalog/images/{image_id}' + _url_path = APIHelper.append_url_with_template_parameters(_url_path, { + 'image_id': {'value': image_id, 'encode': True} + }) + _query_builder = self.config.get_base_uri() + _query_builder += _url_path + _query_url = APIHelper.clean_url(_query_builder) + + if isinstance(image_file, FileWrapper): + image_file_wrapper = image_file.file_stream + image_file_content_type = image_file.content_type + else: + image_file_wrapper = image_file + image_file_content_type = 'image/jpeg' + + # Prepare files + _files = { + 'request': (None, APIHelper.json_serialize(request), 'application/json; charset=utf-8'), + 'image_file': (image_file_wrapper.name, image_file_wrapper, image_file_content_type) + } + + # Prepare headers + _headers = { + 'accept': 'application/json' + } + + # Prepare and execute request + _request = self.config.http_client.put(_query_url, headers=_headers, files=_files) + OAuth2.apply(self.config, _request) + _response = self.execute_request(_request) + + decoded = APIHelper.json_deserialize(_response.text) + if type(decoded) is dict: + _errors = decoded.get('errors') + else: + _errors = None + _result = ApiResponse(_response, body=decoded, errors=_errors) + return _result + def catalog_info(self): """Does a GET request to /v2/catalog/info. @@ -312,15 +386,12 @@ def list_catalog(self, catalog_version=None): """Does a GET request to /v2/catalog/list. - Returns a list of [CatalogObject]($m/CatalogObject)s that includes - all objects of a set of desired types (for example, all - [CatalogItem]($m/CatalogItem) - and [CatalogTax]($m/CatalogTax) objects) in the catalog. The `types` - parameter - is specified as a comma-separated list of valid - [CatalogObject]($m/CatalogObject) types: - `ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, - `DISCOUNT`, `TAX`, `IMAGE`. + Returns a list of all [CatalogObject]($m/CatalogObject)s of the + specified types in the catalog. + The `types` parameter is specified as a comma-separated list of the + [CatalogObjectType]($m/CatalogObjectType) values, + for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, + `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`". __Important:__ ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use @@ -336,16 +407,25 @@ def list_catalog(self, types (string, optional): An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the - [CatalogObjectType]($m/CatalogObjectType) enum, including + [CatalogObjectType]($m/CatalogObjectType) enum, for example, `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, - `MODIFIER`, `MODIFIER_LIST`, or `IMAGE`. If this is - unspecified, the operation returns objects of all the types at - the version of the Square API used to make the request. + `MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc. If this is + unspecified, the operation returns objects of all the top + level types at the version of the Square API used to make the + request. Object types that are nested onto other object types + are not included in the defaults. At the current API version + the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, + MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, SERVICE_CHARGE, + PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, + QUICK_AMOUNT_SETTINGS. catalog_version (long|int, optional): The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the - [CatalogObject]($m/CatalogObject)s' `version` attribute. + [CatalogObject]($m/CatalogObject)s' `version` attribute. If + not included, results will be from the current version of the + catalog. Returns: ApiResponse: An object with the response value as well as other @@ -521,19 +601,26 @@ def retrieve_catalog_object(self, to be retrieved. include_related_objects (bool, optional): If `true`, the response will include additional objects that are related to the - requested object, as follows: If the `object` field of the - response contains a `CatalogItem`, its associated - `CatalogCategory`, `CatalogTax`, `CatalogImage` and - `CatalogModifierList` objects will be returned in the - `related_objects` field of the response. If the `object` field - of the response contains a `CatalogItemVariation`, its parent - `CatalogItem` will be returned in the `related_objects` field - of the response. Default value: `false` + requested objects. Related objects are defined as any objects + referenced by ID by the results in the `objects` field of the + response. These objects are put in the `related_objects` + field. Setting this to `true` is helpful when the objects are + needed for immediate display to a user. This process only goes + one level deep. Objects referenced by the related objects will + not be included. For example, if the `objects` field of the + response contains a CatalogItem, its associated + CatalogCategory objects, CatalogTax objects, CatalogImage + objects and CatalogModifierLists will be returned in the + `related_objects` field of the response. If the `objects` + field of the response contains a CatalogItemVariation, its + parent CatalogItem will be returned in the `related_objects` + field of the response. Default value: `false` catalog_version (long|int, optional): Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version - field of [CatalogObject]($m/CatalogObject)s. + field of [CatalogObject]($m/CatalogObject)s. If not included, + results will be from the current version of the catalog. Returns: ApiResponse: An object with the response value as well as other diff --git a/square/api/locations_api.py b/square/api/locations_api.py index f2cf7e5a..0899d169 100644 --- a/square/api/locations_api.py +++ b/square/api/locations_api.py @@ -16,11 +16,8 @@ def __init__(self, config, call_back=None): def list_locations(self): """Does a GET request to /v2/locations. - Provides information of all locations of a business. - Many Square API endpoints require a `location_id` parameter. - The `id` field of the [`Location`]($m/Location) objects returned by - this - endpoint correspond to that `location_id` parameter. + Provides details about all of the seller's locations, + including those with an inactive status. Returns: ApiResponse: An object with the response value as well as other @@ -62,7 +59,18 @@ def create_location(self, body): """Does a POST request to /v2/locations. - Creates a location. + Creates a + [location](https://developer.squareup.com/docs/locations-api). + Creating new locations allows for separate configuration of receipt + layouts, item prices, + and sales reports. Developers can use locations to separate sales + activity via applications + that integrate with Square from sales activity elsewhere in a seller's + account. + Locations created programmatically with the Locations API will last + forever and + are visible to the seller for their own management, so ensure that + each location has a sensible and unique name. Args: body (CreateLocationRequest): An object containing the fields to @@ -110,14 +118,14 @@ def retrieve_location(self, location_id): """Does a GET request to /v2/locations/{location_id}. - Retrieves details of a location. You can specify "main" - as the location ID to retrieve details of the - main location. + Retrieves details of a single location. Specify "main" + as the location ID to retrieve details of the [main + location](https://developer.squareup.com/docs/locations-api#about-the-m + ain-location). Args: - location_id (string): The ID of the location to retrieve. If you - specify the string "main", then the endpoint returns the main - location. + location_id (string): The ID of the location to retrieve. Specify + the string "main" to return the main location. Returns: ApiResponse: An object with the response value as well as other diff --git a/square/api/mobile_authorization_api.py b/square/api/mobile_authorization_api.py index 5d42fcad..d026fe57 100644 --- a/square/api/mobile_authorization_api.py +++ b/square/api/mobile_authorization_api.py @@ -18,8 +18,8 @@ def create_mobile_authorization_code(self, """Does a POST request to /mobile/authorization-code. Generates code to authorize a mobile application to connect to a - Square card reader - Authorization codes are one-time-use and expire __60 minutes__ after + Square card reader. + Authorization codes are one-time-use codes and expire 60 minutes after being issued. __Important:__ The `Authorization` header you provide to this endpoint must have the following format: diff --git a/square/api/o_auth_api.py b/square/api/o_auth_api.py index b065a4f8..55de81e8 100644 --- a/square/api/o_auth_api.py +++ b/square/api/o_auth_api.py @@ -27,12 +27,11 @@ def renew_token(self, h-tokens). Renews an OAuth access token before it expires. OAuth access tokens besides your application's personal access token - expire after __30 days__. - You can also renew expired tokens within __15 days__ of their - expiration. + expire after 30 days. + You can also renew expired tokens within 15 days of their expiration. You cannot renew an access token that has been expired for more than 15 days. - Instead, the associated user must re-complete the OAuth flow from the + Instead, the associated user must recomplete the OAuth flow from the beginning. __Important:__ The `Authorization` header for this endpoint must have the @@ -42,12 +41,13 @@ def renew_token(self, ``` Replace `APPLICATION_SECRET` with the application secret on the Credentials - page in the [developer - dashboard](https://developer.squareup.com/apps). + page in the [Developer + Dashboard](https://developer.squareup.com/apps). Args: - client_id (string): Your application ID, available from the OAuth - page for your application on the Developer Dashboard. + client_id (string): Your application ID, which is available in the + OAuth page in the [Developer + Dashboard](https://developer.squareup.com/apps). body (RenewTokenRequest): An object containing the fields to POST for the request. See the corresponding object definition for field details. diff --git a/square/api_helper.py b/square/api_helper.py index 8ff579a7..c7ae9d5f 100644 --- a/square/api_helper.py +++ b/square/api_helper.py @@ -101,6 +101,39 @@ def json_deserialize(json, unboxing_function=None, as_dict=False): else: return unboxing_function(decoded) + @staticmethod + def get_content_type(value): + """Get content type header for oneof. + + Args: + value: The value passed by the user. + + Returns: + dict: A dictionary representing the data contained in the + JSON serialized string. + + """ + if value is None: + return None + primitive = (int, str, bool, float) + + if type(value) in primitive: + return 'text/plain; charset=utf-8' + + else: + return 'application/json; charset=utf-8' + + @staticmethod + def get_schema_path(path): + """Return the Schema's path + + Returns: + string : returns Correct schema path + + """ + path = path.replace('\\models', '\\schemas').replace('/models', '/schemas').replace(".py", ".json") + return path + @staticmethod def serialize_array(key, array, formatting="indexed"): """Converts an array parameter to a list of key value tuples. diff --git a/square/client.py b/square/client.py index 898c964d..fea49998 100644 --- a/square/client.py +++ b/square/client.py @@ -41,11 +41,14 @@ class Client(object): @staticmethod def sdk_version(): - return '16.0.0.20211117' + return '17.0.0.20211215' @staticmethod def square_version(): - return '2021-11-17' + return '2021-12-15' + + def user_agent_detail(self): + return self.config.user_agent_detail @lazy_property def mobile_authorization(self): @@ -185,8 +188,8 @@ 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', - square_version='2021-11-17', access_token='', - additional_headers={}, config=None): + square_version='2021-12-15', access_token='', + additional_headers={}, user_agent_detail='', config=None): if config is None: self.config = Configuration( http_client_instance=http_client_instance, @@ -200,6 +203,7 @@ def __init__(self, http_client_instance=None, custom_url=custom_url, square_version=square_version, access_token=access_token, - additional_headers=additional_headers) + additional_headers=additional_headers, + user_agent_detail=user_agent_detail) else: self.config = config diff --git a/square/configuration.py b/square/configuration.py index c6877197..692f6e20 100644 --- a/square/configuration.py +++ b/square/configuration.py @@ -61,14 +61,18 @@ def access_token(self): def additional_headers(self): return deepcopy(self._additional_headers) + @property + def user_agent_detail(self): + return self._user_agent_detail + def __init__( self, http_client_instance=None, override_http_client_configuration=False, timeout=60, max_retries=0, backoff_factor=2, retry_statuses=[408, 413, 429, 500, 502, 503, 504, 521, 522, 524], retry_methods=['GET', 'PUT'], environment='production', - custom_url='https://connect.squareup.com', square_version='2021-11-17', - access_token='', additional_headers={} + custom_url='https://connect.squareup.com', square_version='2021-12-15', + access_token='', additional_headers={}, user_agent_detail='' ): # The Http Client passed from the sdk user for making requests self._http_client_instance = http_client_instance @@ -116,7 +120,7 @@ def clone_with(self, http_client_instance=None, max_retries=None, backoff_factor=None, retry_statuses=None, retry_methods=None, environment=None, custom_url=None, square_version=None, access_token=None, - additional_headers=None): + additional_headers=None, user_agent_detail=None): http_client_instance = http_client_instance or self.http_client_instance override_http_client_configuration = override_http_client_configuration or self.override_http_client_configuration timeout = timeout or self.timeout @@ -129,6 +133,7 @@ def clone_with(self, http_client_instance=None, square_version = square_version or self.square_version access_token = access_token or self.access_token additional_headers = additional_headers or self.additional_headers + user_agent_detail = user_agent_detail or self.user_agent_detail return Configuration( http_client_instance=http_client_instance, @@ -137,7 +142,8 @@ def clone_with(self, http_client_instance=None, backoff_factor=backoff_factor, retry_statuses=retry_statuses, retry_methods=retry_methods, environment=environment, custom_url=custom_url, square_version=square_version, - access_token=access_token, additional_headers=additional_headers + access_token=access_token, additional_headers=additional_headers, + user_agent_detail=user_agent_detail ) def create_http_client(self): diff --git a/tests/api/api_test_base.py b/tests/api/api_test_base.py index 51d4424e..9115fb82 100644 --- a/tests/api/api_test_base.py +++ b/tests/api/api_test_base.py @@ -2,7 +2,6 @@ import os import unittest - from square.configuration import Configuration from square.client import Client diff --git a/tests/api/test_locations_api.py b/tests/api/test_locations_api.py index 780ecd9c..76c85e4e 100644 --- a/tests/api/test_locations_api.py +++ b/tests/api/test_locations_api.py @@ -18,11 +18,8 @@ def setUpClass(cls): cls.response_catcher = HttpResponseCatcher() cls.controller = LocationsApi(cls.config, cls.response_catcher) - # Provides information of all locations of a business. - # - #Many Square API endpoints require a `location_id` parameter. - #The `id` field of the [`Location`]($m/Location) objects returned by this - #endpoint correspond to that `location_id` parameter. + # Provides details about all of the seller's locations, + #including those with an inactive status. def test_list_locations(self): # Perform the API call through the SDK function