` 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.
@@ -33,7 +20,7 @@ For a more detailed discussion of the Catalog data model, please see the
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `type` | [`str (Catalog Object Type)`](/doc/models/catalog-object-type.md) | Required | Possible types of CatalogObjects returned from the Catalog, each
containing type-specific properties in the `*_data` field corresponding to the object type. |
+| `type` | [`str (Catalog Object Type)`](/doc/models/catalog-object-type.md) | Required | Possible types of CatalogObjects returned from the catalog, each
containing type-specific properties in the `*_data` field corresponding to the specfied object type. |
| `id` | `string` | Required | An identifier to reference this object in the catalog. When a new `CatalogObject`
is inserted, the client should set the id to a temporary identifier starting with
a "`#`" character. Other objects being inserted or updated within the same request
may use this identifier to refer to the new object.
When the server receives the new object, it will supply a unique identifier that
replaces the temporary identifier for all future references.
**Constraints**: *Minimum Length*: `1` |
| `updated_at` | `string` | Optional | Last modification [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates) in RFC 3339 format, e.g., `"2016-08-15T23:59:33.123Z"`
would indicate the UTC time (denoted by `Z`) of August 15, 2016 at 23:59:33 and 123 milliseconds. |
| `version` | `long\|int` | Optional | The version of the object. When updating an object, the version supplied
must match the version in the database, otherwise the write will be rejected as conflicting. |
@@ -54,7 +41,7 @@ For a more detailed discussion of the Catalog data model, please see the
| `time_period_data` | [`Catalog Time Period`](/doc/models/catalog-time-period.md) | Optional | Represents a time period - either a single period or a repeating period. |
| `product_set_data` | [`Catalog Product Set`](/doc/models/catalog-product-set.md) | Optional | Represents a collection of catalog objects for the purpose of applying a
`PricingRule`. Including a catalog object will include all of its subtypes.
For example, including a category in a product set will include all of its
items and associated item variations in the product set. Including an item in
a product set will also include its item variations. |
| `pricing_rule_data` | [`Catalog Pricing Rule`](/doc/models/catalog-pricing-rule.md) | Optional | Defines how discounts are automatically applied to a set of items that match the pricing rule
during the active time period. |
-| `image_data` | [`Catalog Image`](/doc/models/catalog-image.md) | Optional | An image file to use in Square catalogs. It can be associated with catalog
items, item variations, and categories. |
+| `image_data` | [`Catalog Image`](/doc/models/catalog-image.md) | Optional | An image file to use in Square catalogs. It can be associated with
`CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, and `CatalogModifierList` objects.
Only the images on items and item variations are exposed in Dashboard.
Only the first image on an item is displayed in Square Point of Sale (SPOS).
Images on items and variations are displayed through Square Online Store.
Images on other object types are for use by 3rd party application developers. |
| `measurement_unit_data` | [`Catalog Measurement Unit`](/doc/models/catalog-measurement-unit.md) | Optional | Represents the unit used to measure a `CatalogItemVariation` and
specifies the precision for decimal quantities. |
| `subscription_plan_data` | [`Catalog Subscription Plan`](/doc/models/catalog-subscription-plan.md) | Optional | Describes a subscription plan. For more information, see
[Set Up and Manage a Subscription Plan](https://developer.squareup.com/docs/subscriptions-api/setup-plan). |
| `item_option_data` | [`Catalog Item Option`](/doc/models/catalog-item-option.md) | Optional | A group of variations for a `CatalogItem`. |
diff --git a/doc/models/charge-request.md b/doc/models/charge-request.md
index af92efb2..b6043e08 100644
--- a/doc/models/charge-request.md
+++ b/doc/models/charge-request.md
@@ -22,8 +22,8 @@ Deprecated - recommend using [CreatePayment](/doc/api/payments.md#create-payment
| `reference_id` | `string` | Optional | An optional ID you can associate with the transaction for your own
purposes (such as to associate the transaction with an entity ID in your
own database).
This value cannot exceed 40 characters.
**Constraints**: *Maximum Length*: `40` |
| `note` | `string` | Optional | An optional note to associate with the transaction.
This value cannot exceed 60 characters.
**Constraints**: *Maximum Length*: `60` |
| `customer_id` | `string` | Optional | The ID of the customer to associate this transaction with. This field
is required if you provide a value for `customer_card_id`, and optional
otherwise.
**Constraints**: *Maximum Length*: `50` |
-| `billing_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
-| `shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `buyer_email_address` | `string` | Optional | The buyer's email address, if available. This value is optional,
but this transaction is ineligible for chargeback protection if it is not
provided. |
| `order_id` | `string` | Optional | The ID of the order to associate with this transaction.
If you provide this value, the `amount_money` value of your request must
__exactly match__ the value of the order's `total_money` field.
**Constraints**: *Maximum Length*: `192` |
| `additional_recipients` | [`List of Charge Request Additional Recipient`](/doc/models/charge-request-additional-recipient.md) | Optional | The basic primitive of multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.
If you provide this value, the `amount_money` value in your additional_recipients
must not be more than 90% of the `amount_money` value in the charge request.
The `location_id` must be the valid location of the app owner merchant.
This field requires the `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.
This field is currently not supported in sandbox. |
diff --git a/doc/models/checkout.md b/doc/models/checkout.md
index 3683b3a6..1096fd5b 100644
--- a/doc/models/checkout.md
+++ b/doc/models/checkout.md
@@ -17,7 +17,7 @@ payment types using a checkout workflow hosted on squareup.com.
| `ask_for_shipping_address` | `bool` | Optional | If `true`, Square Checkout will collect shipping information on your
behalf and store that information with the transaction information in your
Square Dashboard.
Default: `false`. |
| `merchant_support_email` | `string` | Optional | The email address to display on the Square Checkout confirmation page
and confirmation email that the buyer can use to contact the merchant.
If this value is not set, the confirmation page and email will display the
primary email address associated with the merchant's Square account.
Default: none; only exists if explicitly set. |
| `pre_populate_buyer_email` | `string` | Optional | If provided, the buyer's email is pre-populated on the checkout page
as an editable text field.
Default: none; only exists if explicitly set. |
-| `pre_populate_shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `pre_populate_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. |
| `redirect_url` | `string` | Optional | The URL to redirect to after checkout is completed with `checkoutId`,
Square's `orderId`, `transactionId`, and `referenceId` appended as URL
parameters. For example, if the provided redirect_url is
`http://www.example.com/order-complete`, a successful transaction redirects
the customer to:
http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx
If you do not provide a redirect URL, Square Checkout will display an order
confirmation page on your behalf; however Square strongly recommends that
you provide a redirect URL so you can verify the transaction results and
finalize the order through your existing/normal confirmation workflow. |
| `order` | [`Order`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. `Order` objects also
include information about any associated tenders, refunds, and returns.
All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. |
| `created_at` | `string` | Optional | The time when the checkout was created, in RFC 3339 format. |
diff --git a/doc/models/clone-order-request.md b/doc/models/clone-order-request.md
new file mode 100644
index 00000000..d8617e20
--- /dev/null
+++ b/doc/models/clone-order-request.md
@@ -0,0 +1,28 @@
+
+# Clone Order Request
+
+Defines the fields that are included in requests to the
+[CloneOrder](/doc/api/orders.md#clone-order) endpoint.
+
+## Structure
+
+`Clone Order Request`
+
+## Fields
+
+| Name | Type | Tags | Description |
+| --- | --- | --- | --- |
+| `order_id` | `string` | Required | The ID of the order to clone. |
+| `version` | `int` | Optional | An optional order version for concurrency protection.
If a version is provided, it must match the latest stored version of the order to clone.
If a version is not provided, the API clones the latest version. |
+| `idempotency_key` | `string` | Optional | A value you specify that uniquely identifies this clone request.
If you are unsure whether a particular order was cloned successfully,
you can reattempt the call with the same idempotency key without
worrying about creating duplicate cloned orders.
The originally cloned order is returned.
For more information, see [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency). |
+
+## Example (as JSON)
+
+```json
+{
+ "idempotency_key": "UNIQUE_STRING",
+ "order_id": "ZAISEM52YcpmcWAzERDOyiWS123",
+ "version": 3
+}
+```
+
diff --git a/doc/models/clone-order-response.md b/doc/models/clone-order-response.md
new file mode 100644
index 00000000..dee424a8
--- /dev/null
+++ b/doc/models/clone-order-response.md
@@ -0,0 +1,271 @@
+
+# Clone Order Response
+
+Defines the fields that are included in the response body of
+a request to the [CloneOrder](/doc/api/orders.md#clone-order) endpoint.
+
+## Structure
+
+`Clone Order Response`
+
+## Fields
+
+| Name | Type | Tags | Description |
+| --- | --- | --- | --- |
+| `order` | [`Order`](/doc/models/order.md) | Optional | Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. `Order` objects also
include information about any associated tenders, refunds, and returns.
All Connect V2 Transactions have all been converted to Orders including all associated
itemization data. |
+| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
+
+## Example (as JSON)
+
+```json
+{
+ "order": {
+ "created_at": "2020-01-17T20:47:53.293Z",
+ "discounts": [
+ {
+ "applied_money": {
+ "amount": 30,
+ "currency": "USD"
+ },
+ "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
+ "name": "Membership Discount",
+ "percentage": "0.5",
+ "scope": "ORDER",
+ "type": "FIXED_PERCENTAGE",
+ "uid": "membership-discount"
+ },
+ {
+ "applied_money": {
+ "amount": 303,
+ "currency": "USD"
+ },
+ "name": "Labor Day Sale",
+ "percentage": "5",
+ "scope": "ORDER",
+ "type": "FIXED_PERCENTAGE",
+ "uid": "labor-day-sale"
+ },
+ {
+ "amount_money": {
+ "amount": 100,
+ "currency": "USD"
+ },
+ "applied_money": {
+ "amount": 100,
+ "currency": "USD"
+ },
+ "name": "Sale - $1.00 off",
+ "scope": "LINE_ITEM",
+ "type": "FIXED_AMOUNT",
+ "uid": "one-dollar-off"
+ }
+ ],
+ "id": "CAISENgvlJ6jLWAzERDzjyHVybY",
+ "line_items": [
+ {
+ "applied_discounts": [
+ {
+ "applied_money": {
+ "amount": 8,
+ "currency": "USD"
+ },
+ "discount_uid": "membership-discount",
+ "uid": "jWdgP1TpHPFBuVrz81mXVC"
+ },
+ {
+ "applied_money": {
+ "amount": 79,
+ "currency": "USD"
+ },
+ "discount_uid": "labor-day-sale",
+ "uid": "jnZOjjVY57eRcQAVgEwFuC"
+ }
+ ],
+ "applied_taxes": [
+ {
+ "applied_money": {
+ "amount": 136,
+ "currency": "USD"
+ },
+ "tax_uid": "state-sales-tax",
+ "uid": "aKG87ArnDpvMLSZJHxWUl"
+ }
+ ],
+ "base_price_money": {
+ "amount": 1599,
+ "currency": "USD"
+ },
+ "gross_sales_money": {
+ "amount": 1599,
+ "currency": "USD"
+ },
+ "name": "New York Strip Steak",
+ "quantity": "1",
+ "total_discount_money": {
+ "amount": 87,
+ "currency": "USD"
+ },
+ "total_money": {
+ "amount": 1648,
+ "currency": "USD"
+ },
+ "total_tax_money": {
+ "amount": 136,
+ "currency": "USD"
+ },
+ "uid": "8uSwfzvUImn3IRrvciqlXC",
+ "variation_total_price_money": {
+ "amount": 1599,
+ "currency": "USD"
+ }
+ },
+ {
+ "applied_discounts": [
+ {
+ "applied_money": {
+ "amount": 22,
+ "currency": "USD"
+ },
+ "discount_uid": "membership-discount",
+ "uid": "nUXvdsIItfKko0dbYtY58C"
+ },
+ {
+ "applied_money": {
+ "amount": 224,
+ "currency": "USD"
+ },
+ "discount_uid": "labor-day-sale",
+ "uid": "qSdkOOOernlVQqsJ94SPjB"
+ },
+ {
+ "applied_money": {
+ "amount": 100,
+ "currency": "USD"
+ },
+ "discount_uid": "one-dollar-off",
+ "uid": "y7bVl4njrWAnfDwmz19izB"
+ }
+ ],
+ "applied_taxes": [
+ {
+ "applied_money": {
+ "amount": 374,
+ "currency": "USD"
+ },
+ "tax_uid": "state-sales-tax",
+ "uid": "v1dAgrfUVUPTnVTf9sRPz"
+ }
+ ],
+ "base_price_money": {
+ "amount": 2200,
+ "currency": "USD"
+ },
+ "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
+ "gross_sales_money": {
+ "amount": 4500,
+ "currency": "USD"
+ },
+ "modifiers": [
+ {
+ "base_price_money": {
+ "amount": 50,
+ "currency": "USD"
+ },
+ "catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ",
+ "name": "Well",
+ "total_price_money": {
+ "amount": 100,
+ "currency": "USD"
+ },
+ "uid": "Lo3qMMckDluu9Qsb58d4CC"
+ }
+ ],
+ "name": "New York Steak",
+ "quantity": "2",
+ "total_discount_money": {
+ "amount": 346,
+ "currency": "USD"
+ },
+ "total_money": {
+ "amount": 4528,
+ "currency": "USD"
+ },
+ "total_tax_money": {
+ "amount": 374,
+ "currency": "USD"
+ },
+ "uid": "v8ZuEXpOJpb0bazLuvrLDB",
+ "variation_name": "Larger",
+ "variation_total_price_money": {
+ "amount": 4400,
+ "currency": "USD"
+ }
+ }
+ ],
+ "location_id": "057P5VYJ4A5X1",
+ "net_amounts": {
+ "discount_money": {
+ "amount": 433,
+ "currency": "USD"
+ },
+ "service_charge_money": {
+ "amount": 0,
+ "currency": "USD"
+ },
+ "tax_money": {
+ "amount": 510,
+ "currency": "USD"
+ },
+ "tip_money": {
+ "amount": 0,
+ "currency": "USD"
+ },
+ "total_money": {
+ "amount": 6176,
+ "currency": "USD"
+ }
+ },
+ "reference_id": "my-order-001",
+ "source": {
+ "name": "My App"
+ },
+ "state": "DRAFT",
+ "taxes": [
+ {
+ "applied_money": {
+ "amount": 510,
+ "currency": "USD"
+ },
+ "name": "State Sales Tax",
+ "percentage": "9",
+ "scope": "ORDER",
+ "type": "ADDITIVE",
+ "uid": "state-sales-tax"
+ }
+ ],
+ "total_discount_money": {
+ "amount": 433,
+ "currency": "USD"
+ },
+ "total_money": {
+ "amount": 6176,
+ "currency": "USD"
+ },
+ "total_service_charge_money": {
+ "amount": 0,
+ "currency": "USD"
+ },
+ "total_tax_money": {
+ "amount": 510,
+ "currency": "USD"
+ },
+ "total_tip_money": {
+ "amount": 0,
+ "currency": "USD"
+ },
+ "updated_at": "2020-01-17T20:47:53.293Z",
+ "version": 1
+ }
+}
+```
+
diff --git a/doc/models/create-break-type-request.md b/doc/models/create-break-type-request.md
index 7aca456e..8d1545bc 100644
--- a/doc/models/create-break-type-request.md
+++ b/doc/models/create-break-type-request.md
@@ -1,7 +1,7 @@
# Create Break Type Request
-A request to create a new `BreakType`
+A request to create a new `BreakType`.
## Structure
@@ -11,7 +11,7 @@ A request to create a new `BreakType`
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `idempotency_key` | `string` | Optional | Unique string value to insure idempotency of the operation
**Constraints**: *Maximum Length*: `128` |
+| `idempotency_key` | `string` | Optional | A unique string value to ensure the idempotency of the operation.
**Constraints**: *Maximum Length*: `128` |
| `break_type` | [`Break Type`](/doc/models/break-type.md) | Required | A defined break template that sets an expectation for possible `Break`
instances on a `Shift`. |
## Example (as JSON)
diff --git a/doc/models/create-break-type-response.md b/doc/models/create-break-type-response.md
index a07853f4..8a8ca9e6 100644
--- a/doc/models/create-break-type-response.md
+++ b/doc/models/create-break-type-response.md
@@ -1,8 +1,8 @@
# Create Break Type Response
-The response to the request to create a `BreakType`. Contains
-the created `BreakType` object. May contain a set of `Error` objects if
+The response to the request to create a `BreakType`. The response contains
+the created `BreakType` object and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
diff --git a/doc/models/create-catalog-image-request.md b/doc/models/create-catalog-image-request.md
index f8232c7f..140c10fd 100644
--- a/doc/models/create-catalog-image-request.md
+++ b/doc/models/create-catalog-image-request.md
@@ -11,7 +11,7 @@
| --- | --- | --- | --- |
| `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. |
-| `image` | [`Catalog Object`](/doc/models/catalog-object.md) | Optional | The wrapper object for the Catalog entries of a given object type.
The type of a particular `CatalogObject` is determined by the value of the
`type` attribute and only the corresponding data attribute can be set on the `CatalogObject` instance.
For example, the following list shows some instances of `CatalogObject` of a given `type` and
their corresponding data attribute that can be set:
- For a `CatalogObject` of the `ITEM` type, set the `item_data` attribute to yield the `CatalogItem` object.
- For a `CatalogObject` of the `ITEM_VARIATION` type, set the `item_variation_data` attribute to yield the `CatalogItemVariation` object.
- For a `CatalogObject` of the `MODIFIER` type, set the `modifier_data` attribute to yield the `CatalogModifier` object.
- For a `CatalogObject` of the `MODIFIER_LIST` type, set the `modifier_list_data` attribute to yield the `CatalogModifierList` object.
- For a `CatalogObject` of the `CATEGORY` type, set the `category_data` attribute to yield the `CatalogCategory` object.
- For a `CatalogObject` of the `DISCOUNT` type, set the `discount_data` attribute to yield the `CatalogDiscount` object.
- For a `CatalogObject` of the `TAX` type, set the `tax_data` attribute to yield the `CatalogTax` object.
- For a `CatalogObject` of the `IMAGE` type, set the `image_data` attribute to yield the `CatalogImageData` object.
- For a `CatalogObject` of the `QUICK_AMOUNTS_SETTINGS` type, set the `quick_amounts_settings_data` attribute to yield the `CatalogQuickAmountsSettings` object.
- For a `CatalogObject` of the `PRICING_RULE` type, set the `pricing_rule_data` attribute to yield the `CatalogPricingRule` object.
- For a `CatalogObject` of the `TIME_PERIOD` type, set the `time_period_data` attribute to yield the `CatalogTimePeriod` object.
- For a `CatalogObject` of the `PRODUCT_SET` type, set the `product_set_data` attribute to yield the `CatalogProductSet` object.
- For a `CatalogObject` of the `SUBSCRIPTION_PLAN` type, set the `subscription_plan_data` attribute to yield the `CatalogSubscriptionPlan` object.
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. |
+| `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. |
## Example (as JSON)
diff --git a/doc/models/create-catalog-image-response.md b/doc/models/create-catalog-image-response.md
index ad9815e0..ca639dad 100644
--- a/doc/models/create-catalog-image-response.md
+++ b/doc/models/create-catalog-image-response.md
@@ -10,7 +10,7 @@
| 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.
The type of a particular `CatalogObject` is determined by the value of the
`type` attribute and only the corresponding data attribute can be set on the `CatalogObject` instance.
For example, the following list shows some instances of `CatalogObject` of a given `type` and
their corresponding data attribute that can be set:
- For a `CatalogObject` of the `ITEM` type, set the `item_data` attribute to yield the `CatalogItem` object.
- For a `CatalogObject` of the `ITEM_VARIATION` type, set the `item_variation_data` attribute to yield the `CatalogItemVariation` object.
- For a `CatalogObject` of the `MODIFIER` type, set the `modifier_data` attribute to yield the `CatalogModifier` object.
- For a `CatalogObject` of the `MODIFIER_LIST` type, set the `modifier_list_data` attribute to yield the `CatalogModifierList` object.
- For a `CatalogObject` of the `CATEGORY` type, set the `category_data` attribute to yield the `CatalogCategory` object.
- For a `CatalogObject` of the `DISCOUNT` type, set the `discount_data` attribute to yield the `CatalogDiscount` object.
- For a `CatalogObject` of the `TAX` type, set the `tax_data` attribute to yield the `CatalogTax` object.
- For a `CatalogObject` of the `IMAGE` type, set the `image_data` attribute to yield the `CatalogImageData` object.
- For a `CatalogObject` of the `QUICK_AMOUNTS_SETTINGS` type, set the `quick_amounts_settings_data` attribute to yield the `CatalogQuickAmountsSettings` object.
- For a `CatalogObject` of the `PRICING_RULE` type, set the `pricing_rule_data` attribute to yield the `CatalogPricingRule` object.
- For a `CatalogObject` of the `TIME_PERIOD` type, set the `time_period_data` attribute to yield the `CatalogTimePeriod` object.
- For a `CatalogObject` of the `PRODUCT_SET` type, set the `product_set_data` attribute to yield the `CatalogProductSet` object.
- For a `CatalogObject` of the `SUBSCRIPTION_PLAN` type, set the `subscription_plan_data` attribute to yield the `CatalogSubscriptionPlan` object.
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. |
+| `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)
diff --git a/doc/models/create-checkout-request.md b/doc/models/create-checkout-request.md
index a2c1b86b..561316fa 100644
--- a/doc/models/create-checkout-request.md
+++ b/doc/models/create-checkout-request.md
@@ -17,7 +17,7 @@ a request to the `CreateCheckout` endpoint.
| `ask_for_shipping_address` | `bool` | Optional | If `true`, Square Checkout collects shipping information on your behalf and stores
that information with the transaction information in the Square Seller Dashboard.
Default: `false`. |
| `merchant_support_email` | `string` | Optional | The email address to display on the Square Checkout confirmation page
and confirmation email that the buyer can use to contact the seller.
If this value is not set, the confirmation page and email display the
primary email address associated with the seller's Square account.
Default: none; only exists if explicitly set.
**Constraints**: *Maximum Length*: `254` |
| `pre_populate_buyer_email` | `string` | Optional | If provided, the buyer's email is prepopulated on the checkout page
as an editable text field.
Default: none; only exists if explicitly set.
**Constraints**: *Maximum Length*: `254` |
-| `pre_populate_shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `pre_populate_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. |
| `redirect_url` | `string` | Optional | The URL to redirect to after the checkout is completed with `checkoutId`,
`transactionId`, and `referenceId` appended as URL parameters. For example,
if the provided redirect URL is `http://www.example.com/order-complete`, a
successful transaction redirects the customer to:
http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx
If you do not provide a redirect URL, Square Checkout displays an order
confirmation page on your behalf; however, it is strongly recommended that
you provide a redirect URL so you can verify the transaction results and
finalize the order through your existing/normal confirmation workflow.
Default: none; only exists if explicitly set.
**Constraints**: *Maximum Length*: `800` |
| `additional_recipients` | [`List of Charge Request Additional Recipient`](/doc/models/charge-request-additional-recipient.md) | Optional | The basic primitive of a multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.
If you provide this value, the `amount_money` value in your `additional_recipients` field
cannot be more than 90% of the `total_money` calculated by Square for your order.
The `location_id` must be a valid seller location where the checkout is occurring.
This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.
This field is currently not supported in the Square Sandbox. |
| `note` | `string` | Optional | An optional note to associate with the `checkout` object.
This value cannot exceed 60 characters.
**Constraints**: *Maximum Length*: `60` |
diff --git a/doc/models/create-customer-card-request.md b/doc/models/create-customer-card-request.md
index 11e9e346..e724f82f 100644
--- a/doc/models/create-customer-card-request.md
+++ b/doc/models/create-customer-card-request.md
@@ -13,7 +13,7 @@ to the `CreateCustomerCard` endpoint.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `card_nonce` | `string` | Required | A card nonce representing the credit card to link to the customer.
Card nonces are generated by the Square payment form when customers enter
their card information. For more information, see
[Walkthrough: Integrate Square Payments in a Website](https://developer.squareup.com/docs/web-payments/take-card-payment).
__NOTE:__ Card nonces generated by digital wallets (such as Apple Pay)
cannot be used to create a customer card. |
-| `billing_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `cardholder_name` | `string` | Optional | The full name printed on the credit card. |
| `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. |
diff --git a/doc/models/create-customer-request.md b/doc/models/create-customer-request.md
index 0af0a71c..9cd37555 100644
--- a/doc/models/create-customer-request.md
+++ b/doc/models/create-customer-request.md
@@ -18,7 +18,7 @@ Defines the body parameters that can be included in a request to the
| `company_name` | `string` | Optional | A business name associated with the customer profile. |
| `nickname` | `string` | Optional | A nickname for the customer profile. |
| `email_address` | `string` | Optional | The email address associated with the customer profile. |
-| `address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `phone_number` | `string` | Optional | The 11-digit phone number associated with the customer profile. |
| `reference_id` | `string` | Optional | An optional second ID used to associate the customer profile with an
entity in another system. |
| `note` | `string` | Optional | A custom note associated with the customer profile. |
diff --git a/doc/models/create-invoice-request.md b/doc/models/create-invoice-request.md
index 14ddad17..d9d94717 100644
--- a/doc/models/create-invoice-request.md
+++ b/doc/models/create-invoice-request.md
@@ -59,6 +59,7 @@ Describes a `CreateInvoice` request.
"primary_recipient": {
"customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4"
},
+ "sale_or_service_date": "2030-01-24",
"scheduled_at": "2030-01-13T10:00:00Z",
"title": "Event Planning Services"
}
diff --git a/doc/models/create-invoice-response.md b/doc/models/create-invoice-response.md
index 75397933..1ed19a04 100644
--- a/doc/models/create-invoice-response.md
+++ b/doc/models/create-invoice-response.md
@@ -75,6 +75,7 @@ The response returned by the `CreateInvoice` request.
"given_name": "Amelia",
"phone_number": "1-212-555-4240"
},
+ "sale_or_service_date": "2030-01-24",
"scheduled_at": "2030-01-13T10:00:00Z",
"status": "DRAFT",
"timezone": "America/Los_Angeles",
diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md
index f4021c37..2cb63e3b 100644
--- a/doc/models/create-payment-request.md
+++ b/doc/models/create-payment-request.md
@@ -23,11 +23,11 @@ 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. |
| `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` |
-| `verification_token` | `string` | Optional | An identifying token generated by `SqPaymentForm.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). |
+| `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 physical address. |
-| `shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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` |
| `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). |
diff --git a/doc/models/create-shift-request.md b/doc/models/create-shift-request.md
index aa12c8f7..11f45b82 100644
--- a/doc/models/create-shift-request.md
+++ b/doc/models/create-shift-request.md
@@ -1,7 +1,7 @@
# Create Shift Request
-Represents a request to create a `Shift`
+Represents a request to create a `Shift`.
## Structure
@@ -11,8 +11,8 @@ Represents a request to create a `Shift`
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `idempotency_key` | `string` | Optional | Unique string value to insure the idempotency of the operation.
**Constraints**: *Maximum Length*: `128` |
-| `shift` | [`Shift`](/doc/models/shift.md) | Required | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. |
+| `idempotency_key` | `string` | Optional | A unique string value to ensure the idempotency of the operation.
**Constraints**: *Maximum Length*: `128` |
+| `shift` | [`Shift`](/doc/models/shift.md) | Required | A record of the hourly rate, start, and end times for a single work shift
for an employee. This might include a record of the start and end times for breaks
taken during the shift. |
## Example (as JSON)
diff --git a/doc/models/create-shift-response.md b/doc/models/create-shift-response.md
index cb97f1e1..2b9f9597 100644
--- a/doc/models/create-shift-response.md
+++ b/doc/models/create-shift-response.md
@@ -1,8 +1,8 @@
# Create Shift Response
-The response to the request to create a `Shift`. Contains
-the created `Shift` object. May contain a set of `Error` objects if
+The response to a request to create a `Shift`. The response contains
+the created `Shift` object and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,7 +13,7 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `shift` | [`Shift`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. |
+| `shift` | [`Shift`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. This might include a record of the start and end times for breaks
taken during the shift. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/customer-filter.md b/doc/models/customer-filter.md
index b0a076cf..2c3f991d 100644
--- a/doc/models/customer-filter.md
+++ b/doc/models/customer-filter.md
@@ -2,7 +2,7 @@
# Customer Filter
Represents a set of `CustomerQuery` filters used to limit the set of
-`Customers` returned by `SearchCustomers`.
+customers returned by the [SearchCustomers](/doc/api/customers.md#search-customers) endpoint.
## Structure
diff --git a/doc/models/customer-query.md b/doc/models/customer-query.md
index 130d5bee..e34307ed 100644
--- a/doc/models/customer-query.md
+++ b/doc/models/customer-query.md
@@ -12,7 +12,7 @@ for customer profiles.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `filter` | [`Customer Filter`](/doc/models/customer-filter.md) | Optional | Represents a set of `CustomerQuery` filters used to limit the set of
`Customers` returned by `SearchCustomers`. |
+| `filter` | [`Customer Filter`](/doc/models/customer-filter.md) | Optional | Represents a set of `CustomerQuery` filters used to limit the set of
customers returned by the [SearchCustomers](/doc/api/customers.md#search-customers) endpoint. |
| `sort` | [`Customer Sort`](/doc/models/customer-sort.md) | Optional | Specifies how searched customers profiles are sorted, including the sort key and sort order. |
## Example (as JSON)
diff --git a/doc/models/customer.md b/doc/models/customer.md
index c40a151e..521566d4 100644
--- a/doc/models/customer.md
+++ b/doc/models/customer.md
@@ -20,7 +20,7 @@ Represents a Square customer profile in the Customer Directory of a Square selle
| `nickname` | `string` | Optional | A nickname for the customer profile. |
| `company_name` | `string` | Optional | A business name associated with the customer profile. |
| `email_address` | `string` | Optional | The email address associated with the customer profile. |
-| `address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `phone_number` | `string` | Optional | The 11-digit phone number associated with the customer profile. |
| `birthday` | `string` | Optional | The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed.
For example, `0000-09-21T00:00:00-00:00` represents a birthday on September 21 and `1998-09-21T00:00:00-00:00` represents a birthday on September 21, 1998. |
| `reference_id` | `string` | Optional | An optional second ID used to associate the customer profile with an
entity in another system. |
diff --git a/doc/models/date-range.md b/doc/models/date-range.md
index 0f493172..dd7502f7 100644
--- a/doc/models/date-range.md
+++ b/doc/models/date-range.md
@@ -12,8 +12,8 @@ objects that have date properties.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `start_date` | `string` | Optional | String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601
extended format for calendar dates.
The beginning of a date range (inclusive) |
-| `end_date` | `string` | Optional | String in `YYYY-MM-DD` format, e.g. `2017-10-31` per the ISO 8601
extended format for calendar dates.
The end of a date range (inclusive) |
+| `start_date` | `string` | Optional | A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO 8601
extended format for calendar dates.
The beginning of a date range (inclusive). |
+| `end_date` | `string` | Optional | A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO 8601
extended format for calendar dates.
The end of a date range (inclusive). |
## Example (as JSON)
diff --git a/doc/models/delete-break-type-response.md b/doc/models/delete-break-type-response.md
index 152fa231..2aa992b4 100644
--- a/doc/models/delete-break-type-response.md
+++ b/doc/models/delete-break-type-response.md
@@ -1,7 +1,7 @@
# Delete Break Type Response
-The response to a request to delete a `BreakType`. May contain a set
+The response to a request to delete a `BreakType`. The response might contain a set
of `Error` objects if the request resulted in errors.
## Structure
diff --git a/doc/models/delete-shift-response.md b/doc/models/delete-shift-response.md
index 01687d46..a958bde9 100644
--- a/doc/models/delete-shift-response.md
+++ b/doc/models/delete-shift-response.md
@@ -1,7 +1,7 @@
# Delete Shift Response
-The response to a request to delete a `Shift`. May contain a set of
+The response to a request to delete a `Shift`. The response might contain a set of
`Error` objects if the request resulted in errors.
## Structure
diff --git a/doc/models/employee-wage.md b/doc/models/employee-wage.md
index adb3289d..dc54e39b 100644
--- a/doc/models/employee-wage.md
+++ b/doc/models/employee-wage.md
@@ -1,7 +1,7 @@
# Employee Wage
-The hourly wage rate that an employee will earn on a `Shift` for doing the job
+The hourly wage rate that an employee earns on a `Shift` for doing the job
specified by the `title` property of this object. Deprecated at version 2020-08-26. Use `TeamMemberWage` instead.
## Structure
@@ -12,7 +12,7 @@ specified by the `title` property of this object. Deprecated at version 2020-08-
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `id` | `string` | Optional | UUID for this object. |
+| `id` | `string` | Optional | The UUID for this object. |
| `employee_id` | `string` | Optional | The `Employee` that this wage is assigned to. |
| `title` | `string` | Optional | The job title that this wage relates to. |
| `hourly_rate` | [`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. |
diff --git a/doc/models/error-code.md b/doc/models/error-code.md
index 99dab9d0..ba93d3d2 100644
--- a/doc/models/error-code.md
+++ b/doc/models/error-code.md
@@ -85,6 +85,8 @@ Square API.
| `EXPIRATION_FAILURE` | The card expiration date is either invalid or indicates that the
card is expired. |
| `CARD_NOT_SUPPORTED` | The card is not supported either in the geographic region or by
the [merchant category code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) (MCC). |
| `INVALID_PIN` | The card issuer declined the request because the PIN is invalid. |
+| `MISSING_PIN` | The payment is missing a required PIN. |
+| `MISSING_ACCOUNT_TYPE` | The payment is missing a required ACCOUNT_TYPE parameter. |
| `INVALID_POSTAL_CODE` | The postal code is incorrectly formatted. |
| `INVALID_FEES` | The app_fee_money on a payment is too high. |
| `MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED` | The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined. |
diff --git a/doc/models/error.md b/doc/models/error.md
index 114da2ba..68520d03 100644
--- a/doc/models/error.md
+++ b/doc/models/error.md
@@ -23,7 +23,7 @@ See [Handling errors](https://developer.squareup.com/docs/build-basics/handling-
```json
{
"category": "RATE_LIMIT_ERROR",
- "code": "EXPECTED_OBJECT",
+ "code": "ARRAY_EMPTY",
"detail": "detail6",
"field": "field6"
}
diff --git a/doc/models/get-break-type-response.md b/doc/models/get-break-type-response.md
index 6a89c960..c9c9235c 100644
--- a/doc/models/get-break-type-response.md
+++ b/doc/models/get-break-type-response.md
@@ -1,8 +1,8 @@
# Get Break Type Response
-The response to a request to get a `BreakType`. Contains
-the requested `BreakType` objects. May contain a set of `Error` objects if
+The response to a request to get a `BreakType`. The response contains
+the requested `BreakType` objects and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
diff --git a/doc/models/get-employee-wage-response.md b/doc/models/get-employee-wage-response.md
index 51774f6e..ecd38024 100644
--- a/doc/models/get-employee-wage-response.md
+++ b/doc/models/get-employee-wage-response.md
@@ -1,8 +1,8 @@
# Get Employee Wage Response
-A response to a request to get an `EmployeeWage`. Contains
-the requested `EmployeeWage` objects. May contain a set of `Error` objects if
+A response to a request to get an `EmployeeWage`. The response contains
+the requested `EmployeeWage` objects and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,7 +13,7 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `employee_wage` | [`Employee Wage`](/doc/models/employee-wage.md) | Optional | The hourly wage rate that an employee will earn on a `Shift` for doing the job
specified by the `title` property of this object. Deprecated at version 2020-08-26. Use `TeamMemberWage` instead. |
+| `employee_wage` | [`Employee Wage`](/doc/models/employee-wage.md) | Optional | The hourly wage rate that an employee earns on a `Shift` for doing the job
specified by the `title` property of this object. Deprecated at version 2020-08-26. Use `TeamMemberWage` instead. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/get-invoice-response.md b/doc/models/get-invoice-response.md
index 2d447ceb..0d1c4ed9 100644
--- a/doc/models/get-invoice-response.md
+++ b/doc/models/get-invoice-response.md
@@ -75,6 +75,7 @@ Describes a `GetInvoice` response.
"given_name": "Amelia",
"phone_number": "1-212-555-4240"
},
+ "sale_or_service_date": "2030-01-24",
"scheduled_at": "2030-01-13T10:00:00Z",
"status": "DRAFT",
"timezone": "America/Los_Angeles",
diff --git a/doc/models/get-shift-response.md b/doc/models/get-shift-response.md
index d6cf9385..fb0c9aef 100644
--- a/doc/models/get-shift-response.md
+++ b/doc/models/get-shift-response.md
@@ -1,8 +1,8 @@
# Get Shift Response
-A response to request to get a `Shift`. Contains
-the requested `Shift` object. May contain a set of `Error` objects if
+A response to a request to get a `Shift`. The response contains
+the requested `Shift` object and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,7 +13,7 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `shift` | [`Shift`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. |
+| `shift` | [`Shift`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. This might include a record of the start and end times for breaks
taken during the shift. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/get-team-member-wage-response.md b/doc/models/get-team-member-wage-response.md
index 69b259b5..109d763e 100644
--- a/doc/models/get-team-member-wage-response.md
+++ b/doc/models/get-team-member-wage-response.md
@@ -1,8 +1,8 @@
# Get Team Member Wage Response
-A response to a request to get a `TeamMemberWage`. Contains
-the requested `TeamMemberWage` objects. May contain a set of `Error` objects if
+A response to a request to get a `TeamMemberWage`. The response contains
+the requested `TeamMemberWage` objects and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,7 +13,7 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `team_member_wage` | [`Team Member Wage`](/doc/models/team-member-wage.md) | Optional | The hourly wage rate that a team member will earn on a `Shift` for doing the job
specified by the `title` property of this object. |
+| `team_member_wage` | [`Team Member Wage`](/doc/models/team-member-wage.md) | Optional | The hourly wage rate that a team member earns on a `Shift` for doing the job
specified by the `title` property of this object. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/gift-card-activity-unlinked-activity-refund.md b/doc/models/gift-card-activity-unlinked-activity-refund.md
index 9397848e..12864901 100644
--- a/doc/models/gift-card-activity-unlinked-activity-refund.md
+++ b/doc/models/gift-card-activity-unlinked-activity-refund.md
@@ -12,8 +12,8 @@ Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `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. |
-| `reference_id` | `string` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Orders
API is not being used. |
-| `payment_id` | `string` | Optional | When the Square Payments API is used, Refund is not called on the Gift Cards API.
However, when Square reads a Refund activity from the Gift Cards API, the developer needs to know
the ID of the payment (made using this gift card) that is being refunded. |
+| `reference_id` | `string` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Payments
API is not being used. |
+| `payment_id` | `string` | Optional | When using the Square Payments API, the ID of the payment that was refunded to this gift
card. |
## Example (as JSON)
diff --git a/doc/models/inline-types.md b/doc/models/inline-types.md
deleted file mode 100644
index 017d3c76..00000000
--- a/doc/models/inline-types.md
+++ /dev/null
@@ -1,17 +0,0 @@
-
-# Inline Types
-
-Object types to inline under their respective parent object in certain connect v2 responses
-
-## Enumeration
-
-`Inline Types`
-
-## Fields
-
-| Name |
-| --- |
-| `INLINE_NONE` |
-| `INLINE_VARIATIONS` |
-| `INLINE_ALL` |
-
diff --git a/doc/models/invoice-custom-field.md b/doc/models/invoice-custom-field.md
index b882e4a2..d60d1f69 100644
--- a/doc/models/invoice-custom-field.md
+++ b/doc/models/invoice-custom-field.md
@@ -4,6 +4,9 @@
An additional seller-defined and customer-facing field to include 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).
+
## Structure
`Invoice Custom Field`
diff --git a/doc/models/invoice-payment-request.md b/doc/models/invoice-payment-request.md
index 4b2cc40a..4b18df72 100644
--- a/doc/models/invoice-payment-request.md
+++ b/doc/models/invoice-payment-request.md
@@ -2,11 +2,12 @@
# Invoice Payment Request
Represents a payment request for an [invoice](/doc/models/invoice.md). Invoices can specify a maximum
-of 13 payment requests, with up to 12 `INSTALLMENT` request types.
-
-For more information,
+of 13 payment requests, with up to 12 `INSTALLMENT` request types. 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).
+
## Structure
`Invoice Payment Request`
@@ -17,7 +18,7 @@ see [Payment requests](https://developer.squareup.com/docs/invoices-api/overview
| --- | --- | --- | --- |
| `uid` | `string` | Optional | The Square-generated ID of the payment request in an [invoice](/doc/models/invoice.md).
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `255` |
| `request_method` | [`str (Invoice Request Method)`](/doc/models/invoice-request-method.md) | Optional | Specifies the action for Square to take for processing the invoice. For example,
email the invoice, charge a customer's card on file, or do nothing. DEPRECATED at
version 2021-01-21. The corresponding `request_method` field is replaced by the
`Invoice.delivery_method` and `InvoicePaymentRequest.automatic_payment_source` fields. |
-| `request_type` | [`str (Invoice Request Type)`](/doc/models/invoice-request-type.md) | Optional | Indicates the type of the payment request. An invoice supports the following payment request combinations:
- 1 balance
- 1 deposit with 1 balance
- 2 - 12 installments
- 1 deposit with 2 - 12 installments
For more information,
see [Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests). |
+| `request_type` | [`str (Invoice Request Type)`](/doc/models/invoice-request-type.md) | Optional | Indicates the type of the payment request. For more information, see
[Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests). |
| `due_date` | `string` | Optional | The due date (in the invoice's time zone) for the payment request, in `YYYY-MM-DD` format. This field
is required to create a payment request.
After this date, the invoice becomes overdue. For example, a payment `due_date` of 2021-03-09 with a `timezone`
of America/Los\_Angeles becomes overdue at midnight on March 9 in America/Los\_Angeles (which equals a UTC
timestamp of 2021-03-10T08:00:00Z). |
| `fixed_amount_requested_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. |
| `percentage_requested` | `string` | Optional | Specifies the amount for the payment request in percentage:
- When the payment `request_type` is `DEPOSIT`, it is the percentage of the order's total amount.
- When the payment `request_type` is `INSTALLMENT`, it is the percentage of the order's total less
the deposit, if requested. The sum of the `percentage_requested` in all installment
payment requests must be equal to 100.
You cannot specify this when the payment `request_type` is `BALANCE` or when the
payment request specifies the `fixed_amount_requested_money` field. |
diff --git a/doc/models/invoice-recipient.md b/doc/models/invoice-recipient.md
index 000fa56a..5b2516d5 100644
--- a/doc/models/invoice-recipient.md
+++ b/doc/models/invoice-recipient.md
@@ -15,7 +15,7 @@ Provides customer data that Square uses to deliver an invoice.
| `given_name` | `string` | Optional | The recipient's given (that is, first) name. |
| `family_name` | `string` | Optional | The recipient's family (that is, last) name. |
| `email_address` | `string` | Optional | The recipient's email address. |
-| `address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `phone_number` | `string` | Optional | The recipient's phone number. |
| `company_name` | `string` | Optional | The name of the recipient's company. |
diff --git a/doc/models/invoice-request-type.md b/doc/models/invoice-request-type.md
index 21d67b3c..d07801f8 100644
--- a/doc/models/invoice-request-type.md
+++ b/doc/models/invoice-request-type.md
@@ -1,15 +1,8 @@
# Invoice Request Type
-Indicates the type of the payment request. An invoice supports the following payment request combinations:
-
-- 1 balance
-- 1 deposit with 1 balance
-- 2 - 12 installments
-- 1 deposit with 2 - 12 installments
-
-For more information,
-see [Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests).
+Indicates the type of the payment request. For more information, see
+[Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests).
## Enumeration
@@ -19,7 +12,7 @@ see [Payment requests](https://developer.squareup.com/docs/invoices-api/overview
| Name | Description |
| --- | --- |
-| `BALANCE` | Identifies that the payment request is for the balance amount, after accounting for any
other payment requests in the invoice:
- If the invoice specifies only a balance payment request, it refers to the
total amount identified by the associated order.
- If the invoice also specifies a deposit request, the balance payment request refers to
the remaining amount.
- `INSTALLMENT` and `BALANCE` are not allowed together. |
-| `DEPOSIT` | Identifies that the payment request is for a deposit. You have the option of specifying
an exact amount or a percentage of the total order amount. If you request a deposit,
it must be due before any other payment requests. |
-| `INSTALLMENT` | Identifies that the payment request is for an installment. An invoice can request payments in installments.
Along with installments, you can request an optional deposit. All these payment requests must equal the total order amount. |
+| `BALANCE` | A request for a balance payment. The balance amount is computed as follows:
- If the invoice specifies only a balance payment request, the balance amount is the
total amount of the associated order.
- If the invoice also specifies a deposit request, the balance amount is the amount
remaining after the deposit.
`INSTALLMENT` and `BALANCE` payment requests are not allowed in the same invoice. |
+| `DEPOSIT` | A request for a deposit payment. You have the option of specifying
an exact amount or a percentage of the total order amount. If you request a deposit,
it must be due before any other payment requests. |
+| `INSTALLMENT` | A request for an installment payment. Installments allow buyers to pay the invoice over time. Installments can optionally be combined with a deposit.
Adding `INSTALLMENT` payment requests to an invoice requires an
[Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription). |
diff --git a/doc/models/invoice.md b/doc/models/invoice.md
index 72968c12..2ee4e038 100644
--- a/doc/models/invoice.md
+++ b/doc/models/invoice.md
@@ -17,7 +17,7 @@ invoices. For more information, see [Manage Invoices Using the Invoices API](htt
| `location_id` | `string` | Optional | The ID of the location that this invoice is associated with.
If specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `255` |
| `order_id` | `string` | Optional | The ID of the [order](/doc/models/order.md) for which the invoice is created.
This field is required when creating an invoice, and the order must be in the `OPEN` state.
To view the line items and other information for the associated order, call the
[RetrieveOrder](/doc/api/orders.md#retrieve-order) endpoint using the order ID.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `255` |
| `primary_recipient` | [`Invoice Recipient`](/doc/models/invoice-recipient.md) | Optional | Provides customer data that Square uses to deliver an invoice. |
-| `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. You can specify a maximum of 13
payment requests, with up to 12 `INSTALLMENT` request types. For more information, see
[Payment requests](https://developer.squareup.com/docs/invoices-api/overview#payment-requests).
This field is required when creating an invoice. It must contain at least one payment request. |
+| `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` |
@@ -30,8 +30,9 @@ 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).
Max: 2 custom fields |
+| `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 |
| `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. |
## Example (as JSON)
diff --git a/doc/models/list-break-types-request.md b/doc/models/list-break-types-request.md
index 7c4601fe..5ca15b29 100644
--- a/doc/models/list-break-types-request.md
+++ b/doc/models/list-break-types-request.md
@@ -1,7 +1,7 @@
# List Break Types Request
-A request for a filtered set of `BreakType` objects
+A request for a filtered set of `BreakType` objects.
## Structure
@@ -11,9 +11,9 @@ A request for a filtered set of `BreakType` objects
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `location_id` | `string` | Optional | Filter Break Types returned to only those that are associated with the
specified location. |
-| `limit` | `int` | Optional | Maximum number of Break Types to return per page. Can range between 1
and 200. The default is the maximum at 200.
**Constraints**: `>= 1`, `<= 200` |
-| `cursor` | `string` | Optional | Pointer to the next page of Break Type results to fetch. |
+| `location_id` | `string` | Optional | Filter the returned `BreakType` results to only those that are associated with the
specified location. |
+| `limit` | `int` | Optional | The maximum number of `BreakType` results to return per page. The number can range between 1
and 200. The default is 200.
**Constraints**: `>= 1`, `<= 200` |
+| `cursor` | `string` | Optional | A pointer to the next page of `BreakType` results to fetch. |
## Example (as JSON)
diff --git a/doc/models/list-break-types-response.md b/doc/models/list-break-types-response.md
index c53fb19d..586e3c83 100644
--- a/doc/models/list-break-types-response.md
+++ b/doc/models/list-break-types-response.md
@@ -1,8 +1,8 @@
# List Break Types Response
-The response to a request for a set of `BreakTypes`. Contains
-the requested `BreakType` objects. May contain a set of `Error` objects if
+The response to a request for a set of `BreakType` objects. The response contains
+the requested `BreakType` objects and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -14,7 +14,7 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `break_types` | [`List of Break Type`](/doc/models/break-type.md) | Optional | A page of `BreakType` results. |
-| `cursor` | `string` | Optional | Value supplied in the subsequent request to fetch the next next page
of Break Type results. |
+| `cursor` | `string` | Optional | The value supplied in the subsequent request to fetch the next page
of `BreakType` results. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/list-customer-groups-request.md b/doc/models/list-customer-groups-request.md
index 9b66d9cc..063dba5d 100644
--- a/doc/models/list-customer-groups-request.md
+++ b/doc/models/list-customer-groups-request.md
@@ -13,6 +13,7 @@ Defines the query parameters that can be included in a request to the
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for your original query.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `limit` | `int` | Optional | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.
The limit is ignored if it is less than 1 or greater than 50. The default value is 50.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
**Constraints**: `>= 1`, `<= 50` |
## Example (as JSON)
diff --git a/doc/models/list-customer-segments-request.md b/doc/models/list-customer-segments-request.md
index 93b81bb6..9e5cee11 100644
--- a/doc/models/list-customer-segments-request.md
+++ b/doc/models/list-customer-segments-request.md
@@ -12,6 +12,7 @@ Defines the valid parameters for requests to the `ListCustomerSegments` endpoint
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | Optional | A pagination cursor returned by previous calls to `ListCustomerSegments`.
This cursor is used to retrieve the next set of query results.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `limit` | `int` | Optional | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.
The limit is ignored if it is less than 1 or greater than 50. The default value is 50.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
**Constraints**: `>= 1`, `<= 50` |
## Example (as JSON)
diff --git a/doc/models/list-customers-request.md b/doc/models/list-customers-request.md
index cf013922..9670c423 100644
--- a/doc/models/list-customers-request.md
+++ b/doc/models/list-customers-request.md
@@ -13,6 +13,7 @@ Defines the query parameters that can be included in a request to the
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for your original query.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `limit` | `int` | Optional | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.
The limit is ignored if it is less than 1 or greater than 100. The default value is 100.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
**Constraints**: `>= 1`, `<= 100` |
| `sort_field` | [`str (Customer Sort Field)`](/doc/models/customer-sort-field.md) | Optional | Specifies customer attributes as the sort key to customer profiles returned from a search. |
| `sort_order` | [`str (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. |
@@ -21,6 +22,7 @@ Defines the query parameters that can be included in a request to the
```json
{
"cursor": "cursor6",
+ "limit": 172,
"sort_field": "DEFAULT",
"sort_order": "DESC"
}
diff --git a/doc/models/list-employee-wages-request.md b/doc/models/list-employee-wages-request.md
index d731ecfd..8593678a 100644
--- a/doc/models/list-employee-wages-request.md
+++ b/doc/models/list-employee-wages-request.md
@@ -1,7 +1,7 @@
# List Employee Wages Request
-A request for a set of `EmployeeWage` objects
+A request for a set of `EmployeeWage` objects.
## Structure
@@ -11,9 +11,9 @@ A request for a set of `EmployeeWage` objects
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `employee_id` | `string` | Optional | Filter wages returned to only those that are associated with the specified employee. |
-| `limit` | `int` | Optional | Maximum number of Employee Wages to return per page. Can range between
1 and 200. The default is the maximum at 200.
**Constraints**: `>= 1`, `<= 200` |
-| `cursor` | `string` | Optional | Pointer to the next page of Employee Wage results to fetch. |
+| `employee_id` | `string` | Optional | Filter the returned wages to only those that are associated with the specified employee. |
+| `limit` | `int` | Optional | The maximum number of `EmployeeWage` results to return per page. The number can range between
1 and 200. The default is 200.
**Constraints**: `>= 1`, `<= 200` |
+| `cursor` | `string` | Optional | A pointer to the next page of `EmployeeWage` results to fetch. |
## Example (as JSON)
diff --git a/doc/models/list-employee-wages-response.md b/doc/models/list-employee-wages-response.md
index ae986bd9..81e63a8a 100644
--- a/doc/models/list-employee-wages-response.md
+++ b/doc/models/list-employee-wages-response.md
@@ -1,8 +1,8 @@
# List Employee Wages Response
-The response to a request for a set of `EmployeeWage` objects. Contains
-a set of `EmployeeWage`.
+The response to a request for a set of `EmployeeWage` objects. The response contains
+a set of `EmployeeWage` objects.
## Structure
@@ -12,8 +12,8 @@ a set of `EmployeeWage`.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `employee_wages` | [`List of Employee Wage`](/doc/models/employee-wage.md) | Optional | A page of Employee Wage results. |
-| `cursor` | `string` | Optional | Value supplied in the subsequent request to fetch the next next page
of Employee Wage results. |
+| `employee_wages` | [`List of Employee Wage`](/doc/models/employee-wage.md) | Optional | A page of `EmployeeWage` results. |
+| `cursor` | `string` | Optional | The value supplied in the subsequent request to fetch the next page
of `EmployeeWage` results. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/list-employees-response.md b/doc/models/list-employees-response.md
index 3fb7c3c1..ddd9b6b3 100644
--- a/doc/models/list-employees-response.md
+++ b/doc/models/list-employees-response.md
@@ -30,19 +30,19 @@
"errors": [
{
"category": "AUTHENTICATION_ERROR",
- "code": "NOT_ACCEPTABLE",
+ "code": "UNPROCESSABLE_ENTITY",
"detail": "detail1",
"field": "field9"
},
{
"category": "INVALID_REQUEST_ERROR",
- "code": "REQUEST_TIMEOUT",
+ "code": "RATE_LIMITED",
"detail": "detail2",
"field": "field0"
},
{
"category": "RATE_LIMIT_ERROR",
- "code": "CONFLICT",
+ "code": "NOT_IMPLEMENTED",
"detail": "detail3",
"field": "field1"
}
diff --git a/doc/models/list-invoices-response.md b/doc/models/list-invoices-response.md
index f31af14a..a7fcc6e0 100644
--- a/doc/models/list-invoices-response.md
+++ b/doc/models/list-invoices-response.md
@@ -78,6 +78,7 @@ Describes a `ListInvoice` response.
"given_name": "Amelia",
"phone_number": "1-212-555-4240"
},
+ "sale_or_service_date": "2030-01-24",
"scheduled_at": "2030-01-13T10:00:00Z",
"status": "DRAFT",
"timezone": "America/Los_Angeles",
@@ -144,6 +145,7 @@ Describes a `ListInvoice` response.
"phone_number": "1-212-555-4240"
},
"public_url": "https://squareup.com/pay-invoice/h9sfsfTGTSnYEhISUDBhEQ",
+ "sale_or_service_date": "2030-01-24",
"status": "PARTIALLY_PAID",
"timezone": "America/Los_Angeles",
"updated_at": "2021-01-23T15:29:56Z",
diff --git a/doc/models/list-team-member-wages-request.md b/doc/models/list-team-member-wages-request.md
index aecaa36f..225dd943 100644
--- a/doc/models/list-team-member-wages-request.md
+++ b/doc/models/list-team-member-wages-request.md
@@ -1,7 +1,7 @@
# List Team Member Wages Request
-A request for a set of `TeamMemberWage` objects
+A request for a set of `TeamMemberWage` objects.
## Structure
@@ -11,9 +11,9 @@ A request for a set of `TeamMemberWage` objects
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `team_member_id` | `string` | Optional | Filter wages returned to only those that are associated with the
specified team member. |
-| `limit` | `int` | Optional | Maximum number of Team Member Wages to return per page. Can range between
1 and 200. The default is the maximum at 200.
**Constraints**: `>= 1`, `<= 200` |
-| `cursor` | `string` | Optional | Pointer to the next page of Employee Wage results to fetch. |
+| `team_member_id` | `string` | Optional | Filter the returned wages to only those that are associated with the
specified team member. |
+| `limit` | `int` | Optional | The maximum number of `TeamMemberWage` results to return per page. The number can range between
1 and 200. The default is 200.
**Constraints**: `>= 1`, `<= 200` |
+| `cursor` | `string` | Optional | A pointer to the next page of `EmployeeWage` results to fetch. |
## Example (as JSON)
diff --git a/doc/models/list-team-member-wages-response.md b/doc/models/list-team-member-wages-response.md
index f7cf0785..f9dc4db3 100644
--- a/doc/models/list-team-member-wages-response.md
+++ b/doc/models/list-team-member-wages-response.md
@@ -1,8 +1,8 @@
# List Team Member Wages Response
-The response to a request for a set of `TeamMemberWage` objects. Contains
-a set of `TeamMemberWage`.
+The response to a request for a set of `TeamMemberWage` objects. The response contains
+a set of `TeamMemberWage` objects.
## Structure
@@ -12,8 +12,8 @@ a set of `TeamMemberWage`.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `team_member_wages` | [`List of Team Member Wage`](/doc/models/team-member-wage.md) | Optional | A page of Team Member Wage results. |
-| `cursor` | `string` | Optional | Value supplied in the subsequent request to fetch the next next page
of Team Member Wage results. |
+| `team_member_wages` | [`List of Team Member Wage`](/doc/models/team-member-wage.md) | Optional | A page of `TeamMemberWage` results. |
+| `cursor` | `string` | Optional | The value supplied in the subsequent request to fetch the next page
of `TeamMemberWage` results. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/list-workweek-configs-request.md b/doc/models/list-workweek-configs-request.md
index e699c8ef..e5c5fa6c 100644
--- a/doc/models/list-workweek-configs-request.md
+++ b/doc/models/list-workweek-configs-request.md
@@ -1,7 +1,7 @@
# List Workweek Configs Request
-A request for a set of `WorkweekConfig` objects
+A request for a set of `WorkweekConfig` objects.
## Structure
@@ -11,8 +11,8 @@ A request for a set of `WorkweekConfig` objects
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `limit` | `int` | Optional | Maximum number of Workweek Configs to return per page. |
-| `cursor` | `string` | Optional | Pointer to the next page of Workweek Config results to fetch. |
+| `limit` | `int` | Optional | The maximum number of `WorkweekConfigs` results to return per page. |
+| `cursor` | `string` | Optional | A pointer to the next page of `WorkweekConfig` results to fetch. |
## Example (as JSON)
diff --git a/doc/models/list-workweek-configs-response.md b/doc/models/list-workweek-configs-response.md
index ac113795..4fdc61c9 100644
--- a/doc/models/list-workweek-configs-response.md
+++ b/doc/models/list-workweek-configs-response.md
@@ -1,8 +1,8 @@
# List Workweek Configs Response
-The response to a request for a set of `WorkweekConfig` objects. Contains
-the requested `WorkweekConfig` objects. May contain a set of `Error` objects if
+The response to a request for a set of `WorkweekConfig` objects. The response contains
+the requested `WorkweekConfig` objects and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,8 +13,8 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `workweek_configs` | [`List of Workweek Config`](/doc/models/workweek-config.md) | Optional | A page of Employee Wage results. |
-| `cursor` | `string` | Optional | Value supplied in the subsequent request to fetch the next page of
Employee Wage results. |
+| `workweek_configs` | [`List of Workweek Config`](/doc/models/workweek-config.md) | Optional | A page of `EmployeeWage` results. |
+| `cursor` | `string` | Optional | The value supplied in the subsequent request to fetch the next page of
`EmployeeWage` results. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/location.md b/doc/models/location.md
index 0263bc8e..4510c995 100644
--- a/doc/models/location.md
+++ b/doc/models/location.md
@@ -11,25 +11,25 @@
| --- | --- | --- | --- |
| `id` | `string` | Optional | The Square-issued ID of the location. |
| `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 physical address. |
+| `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. |
| `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. |
-| `created_at` | `string` | Optional | The time when the location was created, in RFC 3339 format. |
+| `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. |
+| `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. |
-| `website_url` | `string` | Optional | The website URL of the location. |
+| `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. |
+| `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. |
-| `twitter_username` | `string` | Optional | The Twitter username of the location without the '@' symbol. |
-| `instagram_username` | `string` | Optional | The Instagram username of the location without the '@' symbol. |
-| `facebook_url` | `string` | Optional | The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. |
+| `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. |
| `pos_background_url` | `string` | Optional | The URL of the Point of Sale background image for the location. |
diff --git a/doc/models/loyalty-account-expiring-point-deadline.md b/doc/models/loyalty-account-expiring-point-deadline.md
new file mode 100644
index 00000000..945c59a4
--- /dev/null
+++ b/doc/models/loyalty-account-expiring-point-deadline.md
@@ -0,0 +1,25 @@
+
+# Loyalty Account Expiring Point Deadline
+
+Represents a set of points for a loyalty account that are scheduled to expire on a specific date.
+
+## Structure
+
+`Loyalty Account Expiring Point Deadline`
+
+## Fields
+
+| Name | Type | Tags | Description |
+| --- | --- | --- | --- |
+| `points` | `int` | Required | The number of points scheduled to expire at the `expires_at` timestamp. |
+| `expires_at` | `string` | Required | The timestamp of when the points are scheduled to expire, in RFC 3339 format.
**Constraints**: *Minimum Length*: `1` |
+
+## Example (as JSON)
+
+```json
+{
+ "points": 236,
+ "expires_at": "expires_at6"
+}
+```
+
diff --git a/doc/models/loyalty-account.md b/doc/models/loyalty-account.md
index 9eb6079e..4e1efb49 100644
--- a/doc/models/loyalty-account.md
+++ b/doc/models/loyalty-account.md
@@ -14,13 +14,14 @@ Describes a loyalty account. For more information, see
| --- | --- | --- | --- |
| `id` | `string` | Optional | The Square-assigned ID of the loyalty account.
**Constraints**: *Maximum Length*: `36` |
| `program_id` | `string` | Required | The Square-assigned ID of the [loyalty program](/doc/models/loyalty-program.md) to which the account belongs.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `36` |
-| `balance` | `int` | Optional | The available point balance in the loyalty account.
Your application should be able to handle loyalty accounts that have a negative point balance (`balance` is less than 0). This might occur if a seller makes a manual adjustment or as a result of a refund or exchange. |
+| `balance` | `int` | Optional | The available point balance in the loyalty account. If points are scheduled to expire, they are listed in the `expiring_point_deadlines` field.
Your application should be able to handle loyalty accounts that have a negative point balance (`balance` is less than 0). This might occur if a seller makes a manual adjustment or as a result of a refund or exchange. |
| `lifetime_points` | `int` | Optional | The total points accrued during the lifetime of the account. |
| `customer_id` | `string` | Optional | The Square-assigned ID of the [customer](/doc/models/customer.md) that is associated with the account. |
| `enrolled_at` | `string` | Optional | The timestamp when enrollment occurred, in RFC 3339 format. |
| `created_at` | `string` | Optional | The timestamp when the loyalty account was created, in RFC 3339 format. |
| `updated_at` | `string` | Optional | The timestamp when the loyalty account was last updated, in RFC 3339 format. |
| `mapping` | [`Loyalty Account Mapping`](/doc/models/loyalty-account-mapping.md) | Optional | Represents the mapping that associates a loyalty account with a buyer.
Currently, a loyalty account can only be mapped to a buyer by phone number. For more information, see
[Loyalty Overview](https://developer.squareup.com/docs/loyalty/overview). |
+| `expiring_point_deadlines` | [`List of Loyalty Account Expiring Point Deadline`](/doc/models/loyalty-account-expiring-point-deadline.md) | Optional | The schedule for when points expire in the loyalty account balance. This field is present only if the account has points that are scheduled to expire.
The total number of points in this field equals the number of points in the `balance` field. |
## Example (as JSON)
diff --git a/doc/models/loyalty-program-expiration-policy.md b/doc/models/loyalty-program-expiration-policy.md
index 1033424f..a5f3dfe6 100644
--- a/doc/models/loyalty-program-expiration-policy.md
+++ b/doc/models/loyalty-program-expiration-policy.md
@@ -11,7 +11,7 @@ Describes when the loyalty program expires.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `expiration_duration` | `string` | Required | The number of months before points expire, in RFC 3339 duration format. For example, a value of `P12M` represents a duration of 12 months.
**Constraints**: *Minimum Length*: `1` |
+| `expiration_duration` | `string` | Required | The number of months before points expire, in `P[n]M` RFC 3339 duration format. For example, a value of `P12M` represents a duration of 12 months.
Points are valid through the last day of the month in which they are scheduled to expire. For example, with a `P12M` duration, points earned on July 6, 2020 expire on August 1, 2021.
**Constraints**: *Minimum Length*: `1` |
## Example (as JSON)
diff --git a/doc/models/obtain-token-request.md b/doc/models/obtain-token-request.md
index 34078baa..70df4228 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
[developer dashboard](https://developer.squareup.com/apps).
**Constraints**: *Maximum Length*: `191` |
-| `client_secret` | `string` | Required | The Square-issued application secret for your application, available
from the [developer dashboard](https://developer.squareup.com/apps).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` |
+| `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 [developer dashboard](https://developer.squareup.com/apps).
**Constraints**: *Maximum Length*: `2048` |
+| `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 will expire in 24 hours. |
+| `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 acbed81a..04df161e 100644
--- a/doc/models/obtain-token-response.md
+++ b/doc/models/obtain-token-response.md
@@ -15,8 +15,8 @@
| `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 | Then OpenID token belonging to this this person. Only present if the
OPENID scope is included in the authorize request. |
-| `refresh_token` | `string` | Optional | A refresh token. OAuth refresh tokens are 64 bytes long.
For more information, see [OAuth access token management](https://developer.squareup.com/docs/oauth-api/how-it-works#oauth-access-token-management).
**Constraints**: *Minimum Length*: `2`, *Maximum Length*: `1024` |
+| `id_token` | `string` | Optional | Then OpenID token belonging to this person. 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. |
## Example (as JSON)
diff --git a/doc/models/order-created.md b/doc/models/order-created.md
index 346a817d..3edb5da7 100644
--- a/doc/models/order-created.md
+++ b/doc/models/order-created.md
@@ -22,7 +22,7 @@
"order_id": "order_id6",
"version": 172,
"location_id": "location_id4",
- "state": "CANCELED",
+ "state": "OPEN",
"created_at": "created_at2"
}
```
diff --git a/doc/models/order-fulfillment-recipient.md b/doc/models/order-fulfillment-recipient.md
index a61dbfe0..30e14012 100644
--- a/doc/models/order-fulfillment-recipient.md
+++ b/doc/models/order-fulfillment-recipient.md
@@ -15,7 +15,7 @@ Contains information about the recipient of a fulfillment.
| `display_name` | `string` | Optional | The display name of the fulfillment recipient.
If provided, the display name overrides the value pulled from the customer profile indicated by `customer_id`.
**Constraints**: *Maximum Length*: `255` |
| `email_address` | `string` | Optional | The email address of the fulfillment recipient.
If provided, the email address overrides the value pulled from the customer profile indicated by `customer_id`.
**Constraints**: *Maximum Length*: `255` |
| `phone_number` | `string` | Optional | The phone number of the fulfillment recipient.
If provided, the phone number overrides the value pulled from the customer profile indicated by `customer_id`.
**Constraints**: *Maximum Length*: `17` |
-| `address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
## Example (as JSON)
diff --git a/doc/models/order-fulfillment-updated.md b/doc/models/order-fulfillment-updated.md
index 039a17f7..3b5bd918 100644
--- a/doc/models/order-fulfillment-updated.md
+++ b/doc/models/order-fulfillment-updated.md
@@ -24,7 +24,7 @@
"order_id": "order_id6",
"version": 172,
"location_id": "location_id4",
- "state": "CANCELED",
+ "state": "OPEN",
"created_at": "created_at2"
}
```
diff --git a/doc/models/order-line-item.md b/doc/models/order-line-item.md
index 775167cc..aaf0c700 100644
--- a/doc/models/order-line-item.md
+++ b/doc/models/order-line-item.md
@@ -19,7 +19,7 @@ product to purchase, with its own quantity and price details.
| `note` | `string` | Optional | The note of the line item.
**Constraints**: *Maximum Length*: `2000` |
| `catalog_object_id` | `string` | Optional | The [CatalogItemVariation](/doc/models/catalog-item-variation.md) ID applied to this line item.
**Constraints**: *Maximum Length*: `192` |
| `catalog_version` | `long\|int` | Optional | The version of the catalog object that this line item references. |
-| `variation_name` | `string` | Optional | The name of the variation applied to this line item.
**Constraints**: *Maximum Length*: `255` |
+| `variation_name` | `string` | Optional | The name of the variation applied to this line item.
**Constraints**: *Maximum Length*: `400` |
| `item_type` | [`str (Order Line Item Item Type)`](/doc/models/order-line-item-item-type.md) | Optional | Represents the line item type. |
| `metadata` | `dict` | Optional | Application-defined data attached to this line item. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (such as personally
identifiable information or card details).
Keys written by applications must be 60 characters or less and must be in the character set
`[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed
with a namespace, separated from the key with a ':' character.
Values have a maximum length of 255 characters.
An application can have up to 10 entries per metadata field.
Entries written by applications are private and can only be read or modified by the same
application.
For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata). |
| `modifiers` | [`List of Order Line Item Modifier`](/doc/models/order-line-item-modifier.md) | Optional | The [CatalogModifier](/doc/models/catalog-modifier.md)s applied to this line item. |
@@ -52,6 +52,7 @@ product to purchase, with its own quantity and price details.
"weight_unit": "IMPERIAL_WEIGHT_OUNCE"
},
"precision": 54,
+ "catalog_object_id": "catalog_object_id0",
"catalog_version": 12
},
"note": "note4",
diff --git a/doc/models/order-quantity-unit.md b/doc/models/order-quantity-unit.md
index 43ec805f..5a7f2dce 100644
--- a/doc/models/order-quantity-unit.md
+++ b/doc/models/order-quantity-unit.md
@@ -14,6 +14,7 @@ specifies the number of digits after the decimal point for decimal quantities.
| --- | --- | --- | --- |
| `measurement_unit` | [`Measurement Unit`](/doc/models/measurement-unit.md) | Optional | Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: `custom_unit`,
`area_unit`, `length_unit`, `volume_unit`, and `weight_unit`. |
| `precision` | `int` | Optional | For non-integer quantities, represents the number of digits after the decimal point that are
recorded for this quantity.
For example, a precision of 1 allows quantities such as `"1.0"` and `"1.1"`, but not `"1.01"`.
Min: 0. Max: 5. |
+| `catalog_object_id` | `string` | Optional | The catalog object ID referencing the
[CatalogMeasurementUnit](/doc/models/catalog-measurement-unit.md).
This field is set when this is a catalog-backed measurement unit. |
| `catalog_version` | `long\|int` | Optional | The version of the catalog object that this measurement unit references.
This field is set when this is a catalog-backed measurement unit. |
## Example (as JSON)
@@ -31,6 +32,7 @@ specifies the number of digits after the decimal point for decimal quantities.
"weight_unit": "IMPERIAL_WEIGHT_OUNCE"
},
"precision": 196,
+ "catalog_object_id": "catalog_object_id6",
"catalog_version": 126
}
```
diff --git a/doc/models/order-return-line-item.md b/doc/models/order-return-line-item.md
index 88ea7935..950af451 100644
--- a/doc/models/order-return-line-item.md
+++ b/doc/models/order-return-line-item.md
@@ -19,7 +19,7 @@ The line item being returned in an order.
| `note` | `string` | Optional | The note of the return line item.
**Constraints**: *Maximum Length*: `2000` |
| `catalog_object_id` | `string` | Optional | The [CatalogItemVariation](/doc/models/catalog-item-variation.md) ID applied to this return line item.
**Constraints**: *Maximum Length*: `192` |
| `catalog_version` | `long\|int` | Optional | The version of the catalog object that this line item references. |
-| `variation_name` | `string` | Optional | The name of the variation applied to this return line item.
**Constraints**: *Maximum Length*: `255` |
+| `variation_name` | `string` | Optional | The name of the variation applied to this return line item.
**Constraints**: *Maximum Length*: `400` |
| `item_type` | [`str (Order Line Item Item Type)`](/doc/models/order-line-item-item-type.md) | Optional | Represents the line item type. |
| `return_modifiers` | [`List of Order Return Line Item Modifier`](/doc/models/order-return-line-item-modifier.md) | Optional | The [CatalogModifier](/doc/models/catalog-modifier.md)s applied to this line item. |
| `applied_taxes` | [`List of Order Line Item Applied Tax`](/doc/models/order-line-item-applied-tax.md) | Optional | The list of references to `OrderReturnTax` entities applied to the return line item. Each
`OrderLineItemAppliedTax` has a `tax_uid` that references the `uid` of a top-level
`OrderReturnTax` applied to the return line item. On reads, the applied amount
is populated. |
@@ -51,6 +51,7 @@ The line item being returned in an order.
"weight_unit": "IMPERIAL_WEIGHT_OUNCE"
},
"precision": 54,
+ "catalog_object_id": "catalog_object_id0",
"catalog_version": 12
},
"note": "note4"
diff --git a/doc/models/order-return.md b/doc/models/order-return.md
index cc5a6ae5..12c8c963 100644
--- a/doc/models/order-return.md
+++ b/doc/models/order-return.md
@@ -44,6 +44,7 @@ The set of line items, service charges, taxes, discounts, tips, and other items
"weight_unit": "METRIC_KILOGRAM"
},
"precision": 73,
+ "catalog_object_id": "catalog_object_id5",
"catalog_version": 249
},
"note": "note9"
@@ -65,6 +66,7 @@ The set of line items, service charges, taxes, discounts, tips, and other items
"weight_unit": "METRIC_GRAM"
},
"precision": 74,
+ "catalog_object_id": "catalog_object_id4",
"catalog_version": 248
},
"note": "note8"
@@ -86,6 +88,7 @@ The set of line items, service charges, taxes, discounts, tips, and other items
"weight_unit": "METRIC_MILLIGRAM"
},
"precision": 75,
+ "catalog_object_id": "catalog_object_id3",
"catalog_version": 247
},
"note": "note7"
diff --git a/doc/models/order-state.md b/doc/models/order-state.md
index 4a257f40..feb37082 100644
--- a/doc/models/order-state.md
+++ b/doc/models/order-state.md
@@ -14,4 +14,5 @@ The state of the order.
| `OPEN` | Indicates that the order is open. Open orders can be updated. |
| `COMPLETED` | Indicates that the order is completed. Completed orders are fully paid. This is a terminal state. |
| `CANCELED` | Indicates that the order is canceled. Canceled orders are not paid. This is a terminal state. |
+| `DRAFT` | Indicates that the order is in a draft state. Draft orders can be updated,
but cannot be paid or fulfilled.
For more information, see [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders). |
diff --git a/doc/models/order-updated-object.md b/doc/models/order-updated-object.md
index fc465c24..bd3835d2 100644
--- a/doc/models/order-updated-object.md
+++ b/doc/models/order-updated-object.md
@@ -19,7 +19,7 @@
"order_id": "order_id6",
"version": 176,
"location_id": "location_id4",
- "state": "COMPLETED",
+ "state": "OPEN",
"created_at": "created_at2"
}
}
diff --git a/doc/models/order-updated.md b/doc/models/order-updated.md
index 13041ffc..7479c456 100644
--- a/doc/models/order-updated.md
+++ b/doc/models/order-updated.md
@@ -23,7 +23,7 @@
"order_id": "order_id6",
"version": 172,
"location_id": "location_id4",
- "state": "CANCELED",
+ "state": "OPEN",
"created_at": "created_at2"
}
```
diff --git a/doc/models/order.md b/doc/models/order.md
index 780c90ca..5929b688 100644
--- a/doc/models/order.md
+++ b/doc/models/order.md
@@ -43,6 +43,7 @@ itemization data.
| `total_discount_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. |
| `total_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. |
| `total_service_charge_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. |
+| `ticket_name` | `string` | Optional | A short-term identifier for the order (such as a customer first name, table number, or
auto-generated order number that resets daily). For orders created in Square Point of Sale, the `ticket_name` is
printed on in-person tickets and stubs. It converts to the `kitchen_printing.name` field in the
bill cart feature details.
**Constraints**: *Maximum Length*: `30` |
| `pricing_options` | [`Order Pricing Options`](/doc/models/order-pricing-options.md) | Optional | Pricing options for an order. The options affect how the order's price is calculated.
They can be used, for example, to apply automatic price adjustments that are based on preconfigured
[pricing rules](/doc/models/catalog-pricing-rule.md). |
| `rewards` | [`List of Order Reward`](/doc/models/order-reward.md) | Optional | A set-like list of Rewards that have been added to the Order. |
@@ -74,6 +75,7 @@ itemization data.
"weight_unit": "METRIC_KILOGRAM"
},
"precision": 199,
+ "catalog_object_id": "catalog_object_id9",
"catalog_version": 133
},
"note": "note5",
@@ -95,6 +97,7 @@ itemization data.
"weight_unit": "METRIC_GRAM"
},
"precision": 200,
+ "catalog_object_id": "catalog_object_id0",
"catalog_version": 134
},
"note": "note6",
@@ -116,6 +119,7 @@ itemization data.
"weight_unit": "METRIC_MILLIGRAM"
},
"precision": 201,
+ "catalog_object_id": "catalog_object_id1",
"catalog_version": 135
},
"note": "note7",
diff --git a/doc/models/payment.md b/doc/models/payment.md
index b5e7ebc9..e14b00ab 100644
--- a/doc/models/payment.md
+++ b/doc/models/payment.md
@@ -39,8 +39,8 @@ Represents a payment processed by the Square API.
| `refund_ids` | `List of string` | Optional | A list of `refund_id`s identifying refunds for the payment. |
| `risk_evaluation` | [`Risk Evaluation`](/doc/models/risk-evaluation.md) | Optional | Represents fraud risk information for the associated payment.
When you take a payment through Square's Payments API (using the `CreatePayment`
endpoint), Square evaluates it and assigns a risk level to the payment. Sellers
can use this information to determine the course of action (for example,
provide the goods/services or refund the payment). |
| `buyer_email_address` | `string` | Optional | The buyer's email address.
**Constraints**: *Maximum Length*: `255` |
-| `billing_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
-| `shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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 include when creating a payment.
**Constraints**: *Maximum Length*: `500` |
| `statement_description_identifier` | `string` | Optional | Additional payment information that gets added to the customer's card statement
as part of the statement description.
Note that the `statement_description_identifier` might get truncated on the statement description
to fit the required information including the Square identifier (SQ *) and the name of the
seller taking the payment. |
| `capabilities` | `List of string` | Optional | Actions that can be performed on this payment:
- `EDIT_AMOUNT_UP` - The payment amount can be edited up.
- `EDIT_AMOUNT_DOWN` - The payment amount can be edited down.
- `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up.
- `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down. |
diff --git a/doc/models/publish-invoice-response.md b/doc/models/publish-invoice-response.md
index 7f24b055..01e99c96 100644
--- a/doc/models/publish-invoice-response.md
+++ b/doc/models/publish-invoice-response.md
@@ -76,6 +76,7 @@ Describes a `PublishInvoice` response.
"phone_number": "1-212-555-4240"
},
"public_url": "https://squareup.com/pay-invoice/inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
+ "sale_or_service_date": "2030-01-24",
"scheduled_at": "2030-01-13T10:00:00Z",
"status": "SCHEDULED",
"timezone": "America/Los_Angeles",
diff --git a/doc/models/retrieve-catalog-object-response.md b/doc/models/retrieve-catalog-object-response.md
index 10e556d5..580a2d19 100644
--- a/doc/models/retrieve-catalog-object-response.md
+++ b/doc/models/retrieve-catalog-object-response.md
@@ -10,7 +10,7 @@
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
-| `object` | [`Catalog Object`](/doc/models/catalog-object.md) | Optional | The wrapper object for the Catalog entries of a given object type.
The type of a particular `CatalogObject` is determined by the value of the
`type` attribute and only the corresponding data attribute can be set on the `CatalogObject` instance.
For example, the following list shows some instances of `CatalogObject` of a given `type` and
their corresponding data attribute that can be set:
- For a `CatalogObject` of the `ITEM` type, set the `item_data` attribute to yield the `CatalogItem` object.
- For a `CatalogObject` of the `ITEM_VARIATION` type, set the `item_variation_data` attribute to yield the `CatalogItemVariation` object.
- For a `CatalogObject` of the `MODIFIER` type, set the `modifier_data` attribute to yield the `CatalogModifier` object.
- For a `CatalogObject` of the `MODIFIER_LIST` type, set the `modifier_list_data` attribute to yield the `CatalogModifierList` object.
- For a `CatalogObject` of the `CATEGORY` type, set the `category_data` attribute to yield the `CatalogCategory` object.
- For a `CatalogObject` of the `DISCOUNT` type, set the `discount_data` attribute to yield the `CatalogDiscount` object.
- For a `CatalogObject` of the `TAX` type, set the `tax_data` attribute to yield the `CatalogTax` object.
- For a `CatalogObject` of the `IMAGE` type, set the `image_data` attribute to yield the `CatalogImageData` object.
- For a `CatalogObject` of the `QUICK_AMOUNTS_SETTINGS` type, set the `quick_amounts_settings_data` attribute to yield the `CatalogQuickAmountsSettings` object.
- For a `CatalogObject` of the `PRICING_RULE` type, set the `pricing_rule_data` attribute to yield the `CatalogPricingRule` object.
- For a `CatalogObject` of the `TIME_PERIOD` type, set the `time_period_data` attribute to yield the `CatalogTimePeriod` object.
- For a `CatalogObject` of the `PRODUCT_SET` type, set the `product_set_data` attribute to yield the `CatalogProductSet` object.
- For a `CatalogObject` of the `SUBSCRIPTION_PLAN` type, set the `subscription_plan_data` attribute to yield the `CatalogSubscriptionPlan` object.
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. |
+| `object` | [`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. |
| `related_objects` | [`List of Catalog Object`](/doc/models/catalog-object.md) | Optional | A list of `CatalogObject`s referenced by the object in the `object` field. |
## Example (as JSON)
diff --git a/doc/models/retrieve-employee-response.md b/doc/models/retrieve-employee-response.md
index f8ca381c..fbd43768 100644
--- a/doc/models/retrieve-employee-response.md
+++ b/doc/models/retrieve-employee-response.md
@@ -26,19 +26,19 @@
"errors": [
{
"category": "AUTHENTICATION_ERROR",
- "code": "NOT_ACCEPTABLE",
+ "code": "UNPROCESSABLE_ENTITY",
"detail": "detail1",
"field": "field9"
},
{
"category": "INVALID_REQUEST_ERROR",
- "code": "REQUEST_TIMEOUT",
+ "code": "RATE_LIMITED",
"detail": "detail2",
"field": "field0"
},
{
"category": "RATE_LIMIT_ERROR",
- "code": "CONFLICT",
+ "code": "NOT_IMPLEMENTED",
"detail": "detail3",
"field": "field1"
}
diff --git a/doc/models/revoke-token-request.md b/doc/models/revoke-token-request.md
index 0e2af130..22f17801 100644
--- a/doc/models/revoke-token-request.md
+++ b/doc/models/revoke-token-request.md
@@ -9,7 +9,7 @@
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `client_id` | `string` | Optional | The Square issued ID for your application, available from the
[developer dashboard](https://developer.squareup.com/apps).
**Constraints**: *Maximum Length*: `191` |
+| `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. |
| `revoke_only_access_token` | `bool` | Optional | If `true`, terminate the given single access token, but do not
terminate the entire authorization.
Default: `false` |
diff --git a/doc/models/search-catalog-items-response.md b/doc/models/search-catalog-items-response.md
index 9b8a4603..bd5d0a52 100644
--- a/doc/models/search-catalog-items-response.md
+++ b/doc/models/search-catalog-items-response.md
@@ -23,19 +23,19 @@ Defines the response body returned from the [SearchCatalogItems](/doc/api/catalo
"errors": [
{
"category": "AUTHENTICATION_ERROR",
- "code": "NOT_ACCEPTABLE",
+ "code": "UNPROCESSABLE_ENTITY",
"detail": "detail1",
"field": "field9"
},
{
"category": "INVALID_REQUEST_ERROR",
- "code": "REQUEST_TIMEOUT",
+ "code": "RATE_LIMITED",
"detail": "detail2",
"field": "field0"
},
{
"category": "RATE_LIMIT_ERROR",
- "code": "CONFLICT",
+ "code": "NOT_IMPLEMENTED",
"detail": "detail3",
"field": "field1"
}
diff --git a/doc/models/search-customers-request.md b/doc/models/search-customers-request.md
index 4774226f..86237213 100644
--- a/doc/models/search-customers-request.md
+++ b/doc/models/search-customers-request.md
@@ -13,7 +13,7 @@ Defines the fields that are included in the request body of a request to the
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | Optional | Include the pagination cursor in subsequent calls to this endpoint to retrieve
the next set of results associated with the original query.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
-| `limit` | `long\|int` | Optional | A limit on the number of results to be returned in a single page.
The limit is advisory. The implementation might return more or fewer results.
If the supplied limit is negative, zero, or higher than the maximum limit
of 100, it is ignored.
**Constraints**: `>= 1`, `<= 100` |
+| `limit` | `long\|int` | Optional | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results.
The limit is ignored if it is less than the minimum or greater than the maximum value. The default value is 100.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
**Constraints**: `>= 1`, `<= 100` |
| `query` | [`Customer Query`](/doc/models/customer-query.md) | Optional | Represents a query (including filtering criteria, sorting criteria, or both) used to search
for customer profiles. |
## Example (as JSON)
diff --git a/doc/models/search-invoices-response.md b/doc/models/search-invoices-response.md
index 463fc31c..fdcb7aa1 100644
--- a/doc/models/search-invoices-response.md
+++ b/doc/models/search-invoices-response.md
@@ -78,6 +78,7 @@ Describes a `SearchInvoices` response.
"given_name": "Amelia",
"phone_number": "1-212-555-4240"
},
+ "sale_or_service_date": "2030-01-24",
"scheduled_at": "2030-01-13T10:00:00Z",
"status": "DRAFT",
"timezone": "America/Los_Angeles",
@@ -144,6 +145,7 @@ Describes a `SearchInvoices` response.
"phone_number": "1-212-555-4240"
},
"public_url": "https://squareup.com/pay-invoice/h9sfsfTGTSnYEhISUDBhEQ",
+ "sale_or_service_date": "2030-01-24",
"status": "PARTIALLY_PAID",
"timezone": "America/Los_Angeles",
"updated_at": "2021-01-23T15:29:56Z",
diff --git a/doc/models/search-orders-filter.md b/doc/models/search-orders-filter.md
index 21fda911..f2ccf774 100644
--- a/doc/models/search-orders-filter.md
+++ b/doc/models/search-orders-filter.md
@@ -25,7 +25,7 @@ are ANDed together.
"state_filter": {
"states": [
"CANCELED",
- "OPEN"
+ "DRAFT"
]
},
"date_time_filter": {
diff --git a/doc/models/search-orders-query.md b/doc/models/search-orders-query.md
index a954d874..f40051d1 100644
--- a/doc/models/search-orders-query.md
+++ b/doc/models/search-orders-query.md
@@ -21,8 +21,8 @@ Contains query criteria for the search.
"filter": {
"state_filter": {
"states": [
- "COMPLETED",
- "OPEN"
+ "CANCELED",
+ "COMPLETED"
]
},
"date_time_filter": {
diff --git a/doc/models/search-orders-state-filter.md b/doc/models/search-orders-state-filter.md
index 941aab81..2a76f2a4 100644
--- a/doc/models/search-orders-state-filter.md
+++ b/doc/models/search-orders-state-filter.md
@@ -18,8 +18,8 @@ Filter by the current order `state`.
```json
{
"states": [
- "CANCELED",
- "OPEN"
+ "OPEN",
+ "COMPLETED"
]
}
```
diff --git a/doc/models/search-shifts-request.md b/doc/models/search-shifts-request.md
index 7a7236fc..30037a82 100644
--- a/doc/models/search-shifts-request.md
+++ b/doc/models/search-shifts-request.md
@@ -11,9 +11,9 @@ A request for a filtered and sorted set of `Shift` objects.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `query` | [`Shift Query`](/doc/models/shift-query.md) | Optional | The parameters of a `Shift` search query. Includes filter and sort options. |
-| `limit` | `int` | Optional | number of resources in a page (200 by default).
**Constraints**: `>= 1`, `<= 200` |
-| `cursor` | `string` | Optional | opaque cursor for fetching the next page. |
+| `query` | [`Shift Query`](/doc/models/shift-query.md) | Optional | The parameters of a `Shift` search query, which includes filter and sort options. |
+| `limit` | `int` | Optional | The number of resources in a page (200 by default).
**Constraints**: `>= 1`, `<= 200` |
+| `cursor` | `string` | Optional | An opaque cursor for fetching the next page. |
## Example (as JSON)
diff --git a/doc/models/search-shifts-response.md b/doc/models/search-shifts-response.md
index 895dfcfc..53595aea 100644
--- a/doc/models/search-shifts-response.md
+++ b/doc/models/search-shifts-response.md
@@ -1,8 +1,8 @@
# Search Shifts Response
-The response to a request for `Shift` objects. Contains
-the requested `Shift` objects. May contain a set of `Error` objects if
+The response to a request for `Shift` objects. The response contains
+the requested `Shift` objects and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,8 +13,8 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `shifts` | [`List of Shift`](/doc/models/shift.md) | Optional | Shifts |
-| `cursor` | `string` | Optional | Opaque cursor for fetching the next page. |
+| `shifts` | [`List of Shift`](/doc/models/shift.md) | Optional | Shifts. |
+| `cursor` | `string` | Optional | An opaque cursor for fetching the next page. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/search-team-members-filter.md b/doc/models/search-team-members-filter.md
index 54d45731..2ef35684 100644
--- a/doc/models/search-team-members-filter.md
+++ b/doc/models/search-team-members-filter.md
@@ -21,6 +21,7 @@ returns only active team members assigned to either location "A" or "B".
| --- | --- | --- | --- |
| `location_ids` | `List of string` | Optional | When present, filters by team members assigned to the specified locations.
When empty, includes team members assigned to any location. |
| `status` | [`str (Team Member Status)`](/doc/models/team-member-status.md) | Optional | Enumerates the possible statuses the team member can have within a business. |
+| `is_owner` | `bool` | Optional | When present and set to true, returns the team member who is the owner of the Square account. |
## Example (as JSON)
@@ -29,7 +30,8 @@ returns only active team members assigned to either location "A" or "B".
"location_ids": [
"location_ids0"
],
- "status": "ACTIVE"
+ "status": "ACTIVE",
+ "is_owner": false
}
```
diff --git a/doc/models/search-team-members-query.md b/doc/models/search-team-members-query.md
index c44cad36..0e6bf758 100644
--- a/doc/models/search-team-members-query.md
+++ b/doc/models/search-team-members-query.md
@@ -21,7 +21,8 @@ Represents the parameters in a search for `TeamMember` objects.
"location_ids": [
"location_ids4"
],
- "status": "ACTIVE"
+ "status": "ACTIVE",
+ "is_owner": false
}
}
```
diff --git a/doc/models/shift-filter.md b/doc/models/shift-filter.md
index d8539ab3..43ee52f3 100644
--- a/doc/models/shift-filter.md
+++ b/doc/models/shift-filter.md
@@ -13,12 +13,12 @@ used by Square's servers to apply each filter property specified.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `location_ids` | `List of string` | Required | Fetch shifts for the specified location. |
-| `employee_ids` | `List of string` | Optional | Fetch shifts for the specified employees. DEPRECATED at version 2020-08-26. Use `team_member_ids` instead |
+| `employee_ids` | `List of string` | Optional | Fetch shifts for the specified employees. DEPRECATED at version 2020-08-26. Use `team_member_ids` instead. |
| `status` | [`str (Shift Filter Status)`](/doc/models/shift-filter-status.md) | Optional | Specifies the `status` of `Shift` records to be returned. |
| `start` | [`Time Range`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC 3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevant endpoint-specific documentation to determine
how time ranges are handled. |
| `end` | [`Time Range`](/doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC 3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevant endpoint-specific documentation to determine
how time ranges are handled. |
| `workday` | [`Shift Workday`](/doc/models/shift-workday.md) | Optional | A `Shift` search query filter parameter that sets a range of days that
a `Shift` must start or end in before passing the filter condition. |
-| `team_member_ids` | `List of string` | Required | Fetch shifts for the specified team members. Replaced `employee_ids` at version "2020-08-26" |
+| `team_member_ids` | `List of string` | Required | Fetch shifts for the specified team members. Replaced `employee_ids` at version "2020-08-26". |
## Example (as JSON)
diff --git a/doc/models/shift-query.md b/doc/models/shift-query.md
index dfb0cb83..e806196b 100644
--- a/doc/models/shift-query.md
+++ b/doc/models/shift-query.md
@@ -1,7 +1,7 @@
# Shift Query
-The parameters of a `Shift` search query. Includes filter and sort options.
+The parameters of a `Shift` search query, which includes filter and sort options.
## Structure
diff --git a/doc/models/shift-status.md b/doc/models/shift-status.md
index 24d021a1..6520a743 100644
--- a/doc/models/shift-status.md
+++ b/doc/models/shift-status.md
@@ -1,7 +1,7 @@
# Shift Status
-Enumerates the possible status of a `Shift`
+Enumerates the possible status of a `Shift`.
## Enumeration
diff --git a/doc/models/shift-wage.md b/doc/models/shift-wage.md
index d84b44ed..fc1e4046 100644
--- a/doc/models/shift-wage.md
+++ b/doc/models/shift-wage.md
@@ -11,7 +11,7 @@ The hourly wage rate used to compensate an employee for this shift.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `title` | `string` | Optional | The name of the job performed during this shift. Square
labor-reporting UIs may group shifts together by title. |
+| `title` | `string` | Optional | The name of the job performed during this shift. Square
labor-reporting UIs might group shifts together by title. |
| `hourly_rate` | [`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. |
## Example (as JSON)
diff --git a/doc/models/shift-workday.md b/doc/models/shift-workday.md
index 16a2bb2a..eba9ae02 100644
--- a/doc/models/shift-workday.md
+++ b/doc/models/shift-workday.md
@@ -14,7 +14,7 @@ a `Shift` must start or end in before passing the filter condition.
| --- | --- | --- | --- |
| `date_range` | [`Date Range`](/doc/models/date-range.md) | Optional | A range defined by two dates. Used for filtering a query for Connect v2
objects that have date properties. |
| `match_shifts_by` | [`str (Shift Workday Matcher)`](/doc/models/shift-workday-matcher.md) | Optional | Defines the logic used to apply a workday filter. |
-| `default_timezone` | `string` | Optional | Location-specific timezones convert workdays to datetime filters.
Every location included in the query must have a timezone, or this field
must be provided as a fallback. Format: the IANA timezone database
identifier for the relevant timezone. |
+| `default_timezone` | `string` | Optional | Location-specific timezones convert workdays to datetime filters.
Every location included in the query must have a timezone or this field
must be provided as a fallback. Format: the IANA timezone database
identifier for the relevant timezone. |
## Example (as JSON)
diff --git a/doc/models/shift.md b/doc/models/shift.md
index 1e00f970..f823631e 100644
--- a/doc/models/shift.md
+++ b/doc/models/shift.md
@@ -2,7 +2,7 @@
# Shift
A record of the hourly rate, start, and end times for a single work shift
-for an employee. May include a record of the start and end times for breaks
+for an employee. This might include a record of the start and end times for breaks
taken during the shift.
## Structure
@@ -13,19 +13,19 @@ taken during the shift.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `id` | `string` | Optional | UUID for this object
**Constraints**: *Maximum Length*: `255` |
-| `employee_id` | `string` | Optional | The ID of the employee this shift belongs to. DEPRECATED at version 2020-08-26. Use `team_member_id` instead |
-| `location_id` | `string` | Optional | The ID of the location this shift occurred at. Should be based on
where the employee clocked in. |
-| `timezone` | `string` | Optional | Read-only convenience value that is calculated from the location based
on `location_id`. Format: the IANA Timezone Database identifier for the
location timezone. |
-| `start_at` | `string` | Required | RFC 3339; shifted to location timezone + offset. Precision up to the
minute is respected; seconds are truncated.
**Constraints**: *Minimum Length*: `1` |
-| `end_at` | `string` | Optional | RFC 3339; shifted to timezone + offset. Precision up to the minute is
respected; seconds are truncated. |
+| `id` | `string` | Optional | The UUID for this object.
**Constraints**: *Maximum Length*: `255` |
+| `employee_id` | `string` | Optional | The ID of the employee this shift belongs to. DEPRECATED at version 2020-08-26. Use `team_member_id` instead. |
+| `location_id` | `string` | Optional | The ID of the location this shift occurred at. The location should be based on
where the employee clocked in. |
+| `timezone` | `string` | Optional | The read-only convenience value that is calculated from the location based
on the `location_id`. Format: the IANA timezone database identifier for the
location timezone. |
+| `start_at` | `string` | Required | RFC 3339; shifted to the location timezone + offset. Precision up to the
minute is respected; seconds are truncated.
**Constraints**: *Minimum Length*: `1` |
+| `end_at` | `string` | Optional | RFC 3339; shifted to the timezone + offset. Precision up to the minute is
respected; seconds are truncated. |
| `wage` | [`Shift Wage`](/doc/models/shift-wage.md) | Optional | The hourly wage rate used to compensate an employee for this shift. |
-| `breaks` | [`List of Break`](/doc/models/break.md) | Optional | A list of any paid or unpaid breaks that were taken during this shift. |
-| `status` | [`str (Shift Status)`](/doc/models/shift-status.md) | Optional | Enumerates the possible status of a `Shift` |
-| `version` | `int` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. |
+| `breaks` | [`List of Break`](/doc/models/break.md) | Optional | A list of all the paid or unpaid breaks that were taken during this shift. |
+| `status` | [`str (Shift Status)`](/doc/models/shift-status.md) | Optional | Enumerates the possible status of a `Shift`. |
+| `version` | `int` | Optional | Used for resolving concurrency issues. The request fails if the version
provided does not match the server version at the time of the request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. |
| `created_at` | `string` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. |
| `updated_at` | `string` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. |
-| `team_member_id` | `string` | Optional | The ID of the team member this shift belongs to. Replaced `employee_id` at version "2020-08-26" |
+| `team_member_id` | `string` | Optional | The ID of the team member this shift belongs to. Replaced `employee_id` at version "2020-08-26". |
## Example (as JSON)
diff --git a/doc/models/snippet-response.md b/doc/models/snippet-response.md
index 4b2c9a17..febfdc9a 100644
--- a/doc/models/snippet-response.md
+++ b/doc/models/snippet-response.md
@@ -19,19 +19,19 @@
"errors": [
{
"category": "AUTHENTICATION_ERROR",
- "code": "NOT_ACCEPTABLE",
+ "code": "UNPROCESSABLE_ENTITY",
"detail": "detail1",
"field": "field9"
},
{
"category": "INVALID_REQUEST_ERROR",
- "code": "REQUEST_TIMEOUT",
+ "code": "RATE_LIMITED",
"detail": "detail2",
"field": "field0"
},
{
"category": "RATE_LIMIT_ERROR",
- "code": "CONFLICT",
+ "code": "NOT_IMPLEMENTED",
"detail": "detail3",
"field": "field1"
}
diff --git a/doc/models/team-member-wage.md b/doc/models/team-member-wage.md
index 7b19e21b..10d7a8a6 100644
--- a/doc/models/team-member-wage.md
+++ b/doc/models/team-member-wage.md
@@ -1,7 +1,7 @@
# Team Member Wage
-The hourly wage rate that a team member will earn on a `Shift` for doing the job
+The hourly wage rate that a team member earns on a `Shift` for doing the job
specified by the `title` property of this object.
## Structure
@@ -12,8 +12,8 @@ specified by the `title` property of this object.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `id` | `string` | Optional | UUID for this object. |
-| `team_member_id` | `string` | Optional | The `Team Member` that this wage is assigned to. |
+| `id` | `string` | Optional | The UUID for this object. |
+| `team_member_id` | `string` | Optional | The `TeamMember` that this wage is assigned to. |
| `title` | `string` | Optional | The job title that this wage relates to. |
| `hourly_rate` | [`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. |
diff --git a/doc/models/terminal-checkout.md b/doc/models/terminal-checkout.md
index ee122e47..ea9f651f 100644
--- a/doc/models/terminal-checkout.md
+++ b/doc/models/terminal-checkout.md
@@ -23,6 +23,7 @@
| `app_id` | `string` | Optional | The ID of the application that created the checkout. |
| `location_id` | `string` | Optional | The location of the device where the `TerminalCheckout` was directed. |
| `payment_type` | [`str (Checkout Options Payment Type)`](/doc/models/checkout-options-payment-type.md) | Optional | - |
+| `customer_id` | `string` | Optional | An optional ID of the customer associated with the checkout. |
## Example (as JSON)
diff --git a/doc/models/terminal-device-checkout-options.md b/doc/models/terminal-device-checkout-options.md
new file mode 100644
index 00000000..45129cbc
--- /dev/null
+++ b/doc/models/terminal-device-checkout-options.md
@@ -0,0 +1,31 @@
+
+# Terminal Device Checkout Options
+
+## Structure
+
+`Terminal Device Checkout Options`
+
+## Fields
+
+| Name | Type | Tags | Description |
+| --- | --- | --- | --- |
+| `skip_receipt_screen` | `bool` | Optional | Instructs the device to skip the receipt screen. Defaults to false. |
+| `tip_settings` | [`Tip Settings`](/doc/models/tip-settings.md) | Optional | - |
+
+## Example (as JSON)
+
+```json
+{
+ "skip_receipt_screen": false,
+ "tip_settings": {
+ "allow_tipping": false,
+ "separate_tip_screen": false,
+ "custom_tip_field": false,
+ "tip_percentages": [
+ 48
+ ],
+ "smart_tipping": false
+ }
+}
+```
+
diff --git a/doc/models/transaction.md b/doc/models/transaction.md
index 5580ffbf..07304353 100644
--- a/doc/models/transaction.md
+++ b/doc/models/transaction.md
@@ -23,7 +23,7 @@ the transaction.
| `reference_id` | `string` | Optional | If the transaction was created with the [Charge](/doc/api/transactions.md#charge)
endpoint, this value is the same as the value provided for the `reference_id`
parameter in the request to that endpoint. Otherwise, it is not set.
**Constraints**: *Maximum Length*: `40` |
| `product` | [`str (Transaction Product)`](/doc/models/transaction-product.md) | Optional | Indicates the Square product used to process a transaction. |
| `client_id` | `string` | Optional | If the transaction was created in the Square Point of Sale app, this value
is the ID generated for the transaction by Square Point of Sale.
This ID has no relationship to the transaction's canonical `id`, which is
generated by Square's backend servers. This value is generated for bookkeeping
purposes, in case the transaction cannot immediately be completed (for example,
if the transaction is processed in offline mode).
It is not currently possible with the Connect API to perform a transaction
lookup by this value.
**Constraints**: *Maximum Length*: `192` |
-| `shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `order_id` | `string` | Optional | The order_id is an identifier for the order associated with this transaction, if any.
**Constraints**: *Maximum Length*: `192` |
## Example (as JSON)
diff --git a/doc/models/update-break-type-request.md b/doc/models/update-break-type-request.md
index 67fbaa4f..797458f8 100644
--- a/doc/models/update-break-type-request.md
+++ b/doc/models/update-break-type-request.md
@@ -1,7 +1,7 @@
# Update Break Type Request
-A request to update a `BreakType`
+A request to update a `BreakType`.
## Structure
diff --git a/doc/models/update-break-type-response.md b/doc/models/update-break-type-response.md
index bbf6720d..b23de1a3 100644
--- a/doc/models/update-break-type-response.md
+++ b/doc/models/update-break-type-response.md
@@ -1,8 +1,8 @@
# Update Break Type Response
-A response to a request to update a `BreakType`. Contains
-the requested `BreakType` objects. May contain a set of `Error` objects if
+A response to a request to update a `BreakType`. The response contains
+the requested `BreakType` objects and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
diff --git a/doc/models/update-customer-request.md b/doc/models/update-customer-request.md
index 49760ffd..285887c9 100644
--- a/doc/models/update-customer-request.md
+++ b/doc/models/update-customer-request.md
@@ -17,7 +17,7 @@ Defines the body parameters that can be included in a request to the
| `company_name` | `string` | Optional | A business name associated with the customer profile. |
| `nickname` | `string` | Optional | A nickname for the customer profile. |
| `email_address` | `string` | Optional | The email address associated with the customer profile. |
-| `address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `phone_number` | `string` | Optional | The 11-digit phone number associated with the customer profile. |
| `reference_id` | `string` | Optional | An optional second ID used to associate the customer profile with an
entity in another system. |
| `note` | `string` | Optional | A custom note associated with the customer profile. |
diff --git a/doc/models/update-invoice-response.md b/doc/models/update-invoice-response.md
index 703ca255..f76a00e7 100644
--- a/doc/models/update-invoice-response.md
+++ b/doc/models/update-invoice-response.md
@@ -71,6 +71,7 @@ Describes a `UpdateInvoice` response.
"given_name": "Amelia",
"phone_number": "1-212-555-4240"
},
+ "sale_or_service_date": "2030-01-24",
"scheduled_at": "2030-01-13T10:00:00Z",
"status": "UNPAID",
"timezone": "America/Los_Angeles",
diff --git a/doc/models/update-order-request.md b/doc/models/update-order-request.md
index 2cc6d23f..3dd10bc9 100644
--- a/doc/models/update-order-request.md
+++ b/doc/models/update-order-request.md
@@ -45,6 +45,7 @@ Defines the fields that are included in requests to the
"weight_unit": "METRIC_KILOGRAM"
},
"precision": 201,
+ "catalog_object_id": "catalog_object_id1",
"catalog_version": 135
},
"note": "note3",
diff --git a/doc/models/update-shift-request.md b/doc/models/update-shift-request.md
index 5615bcef..65939330 100644
--- a/doc/models/update-shift-request.md
+++ b/doc/models/update-shift-request.md
@@ -11,7 +11,7 @@ A request to update a `Shift` object.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `shift` | [`Shift`](/doc/models/shift.md) | Required | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. |
+| `shift` | [`Shift`](/doc/models/shift.md) | Required | A record of the hourly rate, start, and end times for a single work shift
for an employee. This might include a record of the start and end times for breaks
taken during the shift. |
## Example (as JSON)
diff --git a/doc/models/update-shift-response.md b/doc/models/update-shift-response.md
index 79e54bfc..6acd9eaa 100644
--- a/doc/models/update-shift-response.md
+++ b/doc/models/update-shift-response.md
@@ -1,8 +1,8 @@
# Update Shift Response
-The response to a request to update a `Shift`. Contains
-the updated `Shift` object. May contain a set of `Error` objects if
+The response to a request to update a `Shift`. The response contains
+the updated `Shift` object and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,7 +13,7 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `shift` | [`Shift`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. May include a record of the start and end times for breaks
taken during the shift. |
+| `shift` | [`Shift`](/doc/models/shift.md) | Optional | A record of the hourly rate, start, and end times for a single work shift
for an employee. This might include a record of the start and end times for breaks
taken during the shift. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/update-workweek-config-request.md b/doc/models/update-workweek-config-request.md
index 32beef68..60d67844 100644
--- a/doc/models/update-workweek-config-request.md
+++ b/doc/models/update-workweek-config-request.md
@@ -1,7 +1,7 @@
# Update Workweek Config Request
-A request to update a `WorkweekConfig` object
+A request to update a `WorkweekConfig` object.
## Structure
@@ -11,7 +11,7 @@ A request to update a `WorkweekConfig` object
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `workweek_config` | [`Workweek Config`](/doc/models/workweek-config.md) | Required | Sets the Day of the week and hour of the day that a business starts a
work week. Used for the calculation of overtime pay. |
+| `workweek_config` | [`Workweek Config`](/doc/models/workweek-config.md) | Required | Sets the day of the week and hour of the day that a business starts a
workweek. This is used to calculate overtime pay. |
## Example (as JSON)
diff --git a/doc/models/update-workweek-config-response.md b/doc/models/update-workweek-config-response.md
index afe0aacf..5bc815ef 100644
--- a/doc/models/update-workweek-config-response.md
+++ b/doc/models/update-workweek-config-response.md
@@ -1,8 +1,8 @@
# Update Workweek Config Response
-The response to a request to update a `WorkweekConfig` object. Contains
-the updated `WorkweekConfig` object. May contain a set of `Error` objects if
+The response to a request to update a `WorkweekConfig` object. The response contains
+the updated `WorkweekConfig` object and might contain a set of `Error` objects if
the request resulted in errors.
## Structure
@@ -13,7 +13,7 @@ the request resulted in errors.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `workweek_config` | [`Workweek Config`](/doc/models/workweek-config.md) | Optional | Sets the Day of the week and hour of the day that a business starts a
work week. Used for the calculation of overtime pay. |
+| `workweek_config` | [`Workweek Config`](/doc/models/workweek-config.md) | Optional | Sets the day of the week and hour of the day that a business starts a
workweek. This is used to calculate overtime pay. |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
## Example (as JSON)
diff --git a/doc/models/upsert-catalog-object-request.md b/doc/models/upsert-catalog-object-request.md
index 35dba258..f3215c26 100644
--- a/doc/models/upsert-catalog-object-request.md
+++ b/doc/models/upsert-catalog-object-request.md
@@ -10,7 +10,7 @@
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `idempotency_key` | `string` | Required | A value you specify that uniquely identifies this
request among all your requests. A common way to create
a valid idempotency key is to use a Universally unique
identifier (UUID).
If you're unsure whether a particular request was successful,
you can reattempt it with the same idempotency key without
worrying about creating duplicate objects.
See [Idempotency](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1` |
-| `object` | [`Catalog Object`](/doc/models/catalog-object.md) | Required | The wrapper object for the Catalog entries of a given object type.
The type of a particular `CatalogObject` is determined by the value of the
`type` attribute and only the corresponding data attribute can be set on the `CatalogObject` instance.
For example, the following list shows some instances of `CatalogObject` of a given `type` and
their corresponding data attribute that can be set:
- For a `CatalogObject` of the `ITEM` type, set the `item_data` attribute to yield the `CatalogItem` object.
- For a `CatalogObject` of the `ITEM_VARIATION` type, set the `item_variation_data` attribute to yield the `CatalogItemVariation` object.
- For a `CatalogObject` of the `MODIFIER` type, set the `modifier_data` attribute to yield the `CatalogModifier` object.
- For a `CatalogObject` of the `MODIFIER_LIST` type, set the `modifier_list_data` attribute to yield the `CatalogModifierList` object.
- For a `CatalogObject` of the `CATEGORY` type, set the `category_data` attribute to yield the `CatalogCategory` object.
- For a `CatalogObject` of the `DISCOUNT` type, set the `discount_data` attribute to yield the `CatalogDiscount` object.
- For a `CatalogObject` of the `TAX` type, set the `tax_data` attribute to yield the `CatalogTax` object.
- For a `CatalogObject` of the `IMAGE` type, set the `image_data` attribute to yield the `CatalogImageData` object.
- For a `CatalogObject` of the `QUICK_AMOUNTS_SETTINGS` type, set the `quick_amounts_settings_data` attribute to yield the `CatalogQuickAmountsSettings` object.
- For a `CatalogObject` of the `PRICING_RULE` type, set the `pricing_rule_data` attribute to yield the `CatalogPricingRule` object.
- For a `CatalogObject` of the `TIME_PERIOD` type, set the `time_period_data` attribute to yield the `CatalogTimePeriod` object.
- For a `CatalogObject` of the `PRODUCT_SET` type, set the `product_set_data` attribute to yield the `CatalogProductSet` object.
- For a `CatalogObject` of the `SUBSCRIPTION_PLAN` type, set the `subscription_plan_data` attribute to yield the `CatalogSubscriptionPlan` object.
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. |
+| `object` | [`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. |
## Example (as JSON)
diff --git a/doc/models/upsert-catalog-object-response.md b/doc/models/upsert-catalog-object-response.md
index 3f359b12..9f7592dd 100644
--- a/doc/models/upsert-catalog-object-response.md
+++ b/doc/models/upsert-catalog-object-response.md
@@ -10,7 +10,7 @@
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. |
-| `catalog_object` | [`Catalog Object`](/doc/models/catalog-object.md) | Optional | The wrapper object for the Catalog entries of a given object type.
The type of a particular `CatalogObject` is determined by the value of the
`type` attribute and only the corresponding data attribute can be set on the `CatalogObject` instance.
For example, the following list shows some instances of `CatalogObject` of a given `type` and
their corresponding data attribute that can be set:
- For a `CatalogObject` of the `ITEM` type, set the `item_data` attribute to yield the `CatalogItem` object.
- For a `CatalogObject` of the `ITEM_VARIATION` type, set the `item_variation_data` attribute to yield the `CatalogItemVariation` object.
- For a `CatalogObject` of the `MODIFIER` type, set the `modifier_data` attribute to yield the `CatalogModifier` object.
- For a `CatalogObject` of the `MODIFIER_LIST` type, set the `modifier_list_data` attribute to yield the `CatalogModifierList` object.
- For a `CatalogObject` of the `CATEGORY` type, set the `category_data` attribute to yield the `CatalogCategory` object.
- For a `CatalogObject` of the `DISCOUNT` type, set the `discount_data` attribute to yield the `CatalogDiscount` object.
- For a `CatalogObject` of the `TAX` type, set the `tax_data` attribute to yield the `CatalogTax` object.
- For a `CatalogObject` of the `IMAGE` type, set the `image_data` attribute to yield the `CatalogImageData` object.
- For a `CatalogObject` of the `QUICK_AMOUNTS_SETTINGS` type, set the `quick_amounts_settings_data` attribute to yield the `CatalogQuickAmountsSettings` object.
- For a `CatalogObject` of the `PRICING_RULE` type, set the `pricing_rule_data` attribute to yield the `CatalogPricingRule` object.
- For a `CatalogObject` of the `TIME_PERIOD` type, set the `time_period_data` attribute to yield the `CatalogTimePeriod` object.
- For a `CatalogObject` of the `PRODUCT_SET` type, set the `product_set_data` attribute to yield the `CatalogProductSet` object.
- For a `CatalogObject` of the `SUBSCRIPTION_PLAN` type, set the `subscription_plan_data` attribute to yield the `CatalogSubscriptionPlan` object.
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. |
+| `catalog_object` | [`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. |
| `id_mappings` | [`List of Catalog Id Mapping`](/doc/models/catalog-id-mapping.md) | Optional | The mapping between client and server IDs for this upsert. |
## Example (as JSON)
diff --git a/doc/models/v1-create-employee-role-request.md b/doc/models/v1-create-employee-role-request.md
deleted file mode 100644
index bd638105..00000000
--- a/doc/models/v1-create-employee-role-request.md
+++ /dev/null
@@ -1,30 +0,0 @@
-
-# V1 Create Employee Role Request
-
-## Structure
-
-`V1 Create Employee Role Request`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `employee_role` | [`V1 Employee Role`](/doc/models/v1-employee-role.md) | Optional | V1EmployeeRole |
-
-## Example (as JSON)
-
-```json
-{
- "employee_role": {
- "id": "id2",
- "name": "name2",
- "permissions": [
- "REGISTER_CHANGE_SETTINGS"
- ],
- "is_owner": false,
- "created_at": "created_at0",
- "updated_at": "updated_at8"
- }
-}
-```
-
diff --git a/doc/models/v1-employee-role-permissions.md b/doc/models/v1-employee-role-permissions.md
deleted file mode 100644
index f8687379..00000000
--- a/doc/models/v1-employee-role-permissions.md
+++ /dev/null
@@ -1,19 +0,0 @@
-
-# V1 Employee Role Permissions
-
-## Enumeration
-
-`V1 Employee Role Permissions`
-
-## Fields
-
-| Name |
-| --- |
-| `REGISTER_ACCESS_SALES_HISTORY` |
-| `REGISTER_APPLY_RESTRICTED_DISCOUNTS` |
-| `REGISTER_CHANGE_SETTINGS` |
-| `REGISTER_EDIT_ITEM` |
-| `REGISTER_ISSUE_REFUNDS` |
-| `REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE` |
-| `REGISTER_VIEW_SUMMARY_REPORTS` |
-
diff --git a/doc/models/v1-employee-role.md b/doc/models/v1-employee-role.md
deleted file mode 100644
index 66effdc6..00000000
--- a/doc/models/v1-employee-role.md
+++ /dev/null
@@ -1,36 +0,0 @@
-
-# V1 Employee Role
-
-V1EmployeeRole
-
-## Structure
-
-`V1 Employee Role`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `id` | `string` | Optional | The role's unique ID, Can only be set by Square. |
-| `name` | `string` | Required | The role's merchant-defined name. |
-| `permissions` | [`List of str (V1 Employee Role Permissions)`](/doc/models/v1-employee-role-permissions.md) | Required | The role's permissions.
See [V1EmployeeRolePermissions](#type-v1employeerolepermissions) for possible values |
-| `is_owner` | `bool` | Optional | If true, employees with this role have all permissions, regardless of the values indicated in permissions. |
-| `created_at` | `string` | Optional | The time when the employee entity was created, in ISO 8601 format. Is set by Square when the Role is created. |
-| `updated_at` | `string` | Optional | The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated. |
-
-## Example (as JSON)
-
-```json
-{
- "id": "id0",
- "name": "name0",
- "permissions": [
- "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE",
- "REGISTER_VIEW_SUMMARY_REPORTS"
- ],
- "is_owner": false,
- "created_at": "created_at2",
- "updated_at": "updated_at4"
-}
-```
-
diff --git a/doc/models/v1-employee-status.md b/doc/models/v1-employee-status.md
deleted file mode 100644
index 9bf07736..00000000
--- a/doc/models/v1-employee-status.md
+++ /dev/null
@@ -1,14 +0,0 @@
-
-# V1 Employee Status
-
-## Enumeration
-
-`V1 Employee Status`
-
-## Fields
-
-| Name |
-| --- |
-| `ACTIVE` |
-| `INACTIVE` |
-
diff --git a/doc/models/v1-employee.md b/doc/models/v1-employee.md
deleted file mode 100644
index 45dacc5f..00000000
--- a/doc/models/v1-employee.md
+++ /dev/null
@@ -1,44 +0,0 @@
-
-# V1 Employee
-
-Represents one of a business's employees.
-
-## Structure
-
-`V1 Employee`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `id` | `string` | Optional | The employee's unique ID. |
-| `first_name` | `string` | Required | The employee's first name. |
-| `last_name` | `string` | Required | The employee's last name. |
-| `role_ids` | `List of string` | Optional | The ids of the employee's associated roles. Currently, you can specify only one or zero roles per employee. |
-| `authorized_location_ids` | `List of string` | Optional | The IDs of the locations the employee is allowed to clock in at. |
-| `email` | `string` | Optional | The employee's email address. |
-| `status` | [`str (V1 Employee Status)`](/doc/models/v1-employee-status.md) | Optional | - |
-| `external_id` | `string` | Optional | An ID the merchant can set to associate the employee with an entity in another system. |
-| `created_at` | `string` | Optional | The time when the employee entity was created, in ISO 8601 format. |
-| `updated_at` | `string` | Optional | The time when the employee entity was most recently updated, in ISO 8601 format. |
-
-## Example (as JSON)
-
-```json
-{
- "id": "id0",
- "first_name": "first_name0",
- "last_name": "last_name8",
- "role_ids": [
- "role_ids6",
- "role_ids7",
- "role_ids8"
- ],
- "authorized_location_ids": [
- "authorized_location_ids1"
- ],
- "email": "email6",
- "status": "ACTIVE"
-}
-```
-
diff --git a/doc/models/v1-list-employee-roles-request.md b/doc/models/v1-list-employee-roles-request.md
deleted file mode 100644
index a56f7382..00000000
--- a/doc/models/v1-list-employee-roles-request.md
+++ /dev/null
@@ -1,25 +0,0 @@
-
-# V1 List Employee Roles Request
-
-## Structure
-
-`V1 List Employee Roles Request`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `order` | [`str (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. |
-| `limit` | `int` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. |
-| `batch_token` | `string` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. |
-
-## Example (as JSON)
-
-```json
-{
- "order": "DESC",
- "limit": 172,
- "batch_token": "batch_token2"
-}
-```
-
diff --git a/doc/models/v1-list-employee-roles-response.md b/doc/models/v1-list-employee-roles-response.md
deleted file mode 100644
index 3dfed360..00000000
--- a/doc/models/v1-list-employee-roles-response.md
+++ /dev/null
@@ -1,45 +0,0 @@
-
-# V1 List Employee Roles Response
-
-## Structure
-
-`V1 List Employee Roles Response`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `items` | [`List of V1 Employee Role`](/doc/models/v1-employee-role.md) | Optional | - |
-
-## Example (as JSON)
-
-```json
-{
- "items": [
- {
- "id": "id7",
- "name": "name7",
- "permissions": [
- "REGISTER_EDIT_ITEM",
- "REGISTER_ISSUE_REFUNDS"
- ],
- "is_owner": true,
- "created_at": "created_at5",
- "updated_at": "updated_at7"
- },
- {
- "id": "id8",
- "name": "name8",
- "permissions": [
- "REGISTER_ISSUE_REFUNDS",
- "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE",
- "REGISTER_VIEW_SUMMARY_REPORTS"
- ],
- "is_owner": false,
- "created_at": "created_at6",
- "updated_at": "updated_at6"
- }
- ]
-}
-```
-
diff --git a/doc/models/v1-list-employees-request-status.md b/doc/models/v1-list-employees-request-status.md
deleted file mode 100644
index 1622f98f..00000000
--- a/doc/models/v1-list-employees-request-status.md
+++ /dev/null
@@ -1,14 +0,0 @@
-
-# V1 List Employees Request Status
-
-## Enumeration
-
-`V1 List Employees Request Status`
-
-## Fields
-
-| Name |
-| --- |
-| `ACTIVE` |
-| `INACTIVE` |
-
diff --git a/doc/models/v1-list-employees-request.md b/doc/models/v1-list-employees-request.md
deleted file mode 100644
index 2164315d..00000000
--- a/doc/models/v1-list-employees-request.md
+++ /dev/null
@@ -1,33 +0,0 @@
-
-# V1 List Employees Request
-
-## Structure
-
-`V1 List Employees Request`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `order` | [`str (Sort Order)`](/doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. |
-| `begin_updated_at` | `string` | Optional | If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format |
-| `end_updated_at` | `string` | Optional | If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format. |
-| `begin_created_at` | `string` | Optional | If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format. |
-| `end_created_at` | `string` | Optional | If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format. |
-| `status` | [`str (V1 List Employees Request Status)`](/doc/models/v1-list-employees-request-status.md) | Optional | - |
-| `external_id` | `string` | Optional | If provided, the endpoint returns only employee entities with the specified external_id. |
-| `limit` | `int` | Optional | The maximum integer number of employee entities to return in a single response. Default 100, maximum 200. |
-| `batch_token` | `string` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. |
-
-## Example (as JSON)
-
-```json
-{
- "order": "DESC",
- "begin_updated_at": "begin_updated_at6",
- "end_updated_at": "end_updated_at4",
- "begin_created_at": "begin_created_at6",
- "end_created_at": "end_created_at8"
-}
-```
-
diff --git a/doc/models/v1-list-employees-response.md b/doc/models/v1-list-employees-response.md
deleted file mode 100644
index 44642d7a..00000000
--- a/doc/models/v1-list-employees-response.md
+++ /dev/null
@@ -1,52 +0,0 @@
-
-# V1 List Employees Response
-
-## Structure
-
-`V1 List Employees Response`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `items` | [`List of V1 Employee`](/doc/models/v1-employee.md) | Optional | - |
-
-## Example (as JSON)
-
-```json
-{
- "items": [
- {
- "id": "id7",
- "first_name": "first_name7",
- "last_name": "last_name5",
- "role_ids": [
- "role_ids1",
- "role_ids0",
- "role_ids9"
- ],
- "authorized_location_ids": [
- "authorized_location_ids8"
- ],
- "email": "email9",
- "status": "INACTIVE"
- },
- {
- "id": "id8",
- "first_name": "first_name8",
- "last_name": "last_name6",
- "role_ids": [
- "role_ids2",
- "role_ids1"
- ],
- "authorized_location_ids": [
- "authorized_location_ids9",
- "authorized_location_ids0"
- ],
- "email": "email8",
- "status": "ACTIVE"
- }
- ]
-}
-```
-
diff --git a/doc/models/v1-list-orders-response.md b/doc/models/v1-list-orders-response.md
index 58c7004f..33be3754 100644
--- a/doc/models/v1-list-orders-response.md
+++ b/doc/models/v1-list-orders-response.md
@@ -20,19 +20,19 @@
"errors": [
{
"category": "MERCHANT_SUBSCRIPTION_ERROR",
- "code": "INVALID_CONTENT_TYPE",
+ "code": "INVALID_PHONE_NUMBER",
"detail": "detail8",
"field": "field6"
},
{
"category": "API_ERROR",
- "code": "INVALID_FORM_VALUE",
+ "code": "CHECKOUT_EXPIRED",
"detail": "detail9",
"field": "field7"
},
{
"category": "AUTHENTICATION_ERROR",
- "code": "CUSTOMER_NOT_FOUND",
+ "code": "BAD_CERTIFICATE",
"detail": "detail0",
"field": "field8"
}
@@ -46,7 +46,7 @@
"errors": [
{
"category": "API_ERROR",
- "code": "INVALID_FORM_VALUE",
+ "code": "CHECKOUT_EXPIRED",
"detail": "detail9",
"field": "field7"
}
diff --git a/doc/models/v1-order.md b/doc/models/v1-order.md
index 6427d68e..22f3fb62 100644
--- a/doc/models/v1-order.md
+++ b/doc/models/v1-order.md
@@ -17,7 +17,7 @@ V1Order
| `recipient_name` | `string` | Optional | The name of the order's buyer. |
| `recipient_phone_number` | `string` | Optional | The phone number to use for the order's delivery. |
| `state` | [`str (V1 Order State)`](/doc/models/v1-order-state.md) | Optional | - |
-| `shipping_address` | [`Address`](/doc/models/address.md) | Optional | Represents a physical address. |
+| `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. |
| `subtotal_money` | [`V1 Money`](/doc/models/v1-money.md) | Optional | - |
| `total_shipping_money` | [`V1 Money`](/doc/models/v1-money.md) | Optional | - |
| `total_tax_money` | [`V1 Money`](/doc/models/v1-money.md) | Optional | - |
@@ -44,19 +44,19 @@ V1Order
"errors": [
{
"category": "AUTHENTICATION_ERROR",
- "code": "NOT_ACCEPTABLE",
+ "code": "UNPROCESSABLE_ENTITY",
"detail": "detail1",
"field": "field9"
},
{
"category": "INVALID_REQUEST_ERROR",
- "code": "REQUEST_TIMEOUT",
+ "code": "RATE_LIMITED",
"detail": "detail2",
"field": "field0"
},
{
"category": "RATE_LIMIT_ERROR",
- "code": "CONFLICT",
+ "code": "NOT_IMPLEMENTED",
"detail": "detail3",
"field": "field1"
}
diff --git a/doc/models/v1-payment-tax.md b/doc/models/v1-payment-tax.md
index 869d42e8..9ce2dcba 100644
--- a/doc/models/v1-payment-tax.md
+++ b/doc/models/v1-payment-tax.md
@@ -25,19 +25,19 @@ V1PaymentTax
"errors": [
{
"category": "AUTHENTICATION_ERROR",
- "code": "NOT_ACCEPTABLE",
+ "code": "UNPROCESSABLE_ENTITY",
"detail": "detail1",
"field": "field9"
},
{
"category": "INVALID_REQUEST_ERROR",
- "code": "REQUEST_TIMEOUT",
+ "code": "RATE_LIMITED",
"detail": "detail2",
"field": "field0"
},
{
"category": "RATE_LIMIT_ERROR",
- "code": "CONFLICT",
+ "code": "NOT_IMPLEMENTED",
"detail": "detail3",
"field": "field1"
}
diff --git a/doc/models/v1-update-employee-request.md b/doc/models/v1-update-employee-request.md
deleted file mode 100644
index 0393f56d..00000000
--- a/doc/models/v1-update-employee-request.md
+++ /dev/null
@@ -1,35 +0,0 @@
-
-# V1 Update Employee Request
-
-## Structure
-
-`V1 Update Employee Request`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `body` | [`V1 Employee`](/doc/models/v1-employee.md) | Required | Represents one of a business's employees. |
-
-## Example (as JSON)
-
-```json
-{
- "body": {
- "id": "id6",
- "first_name": "first_name6",
- "last_name": "last_name4",
- "role_ids": [
- "role_ids0",
- "role_ids1"
- ],
- "authorized_location_ids": [
- "authorized_location_ids7",
- "authorized_location_ids8"
- ],
- "email": "email0",
- "status": "ACTIVE"
- }
-}
-```
-
diff --git a/doc/models/v1-update-employee-role-request.md b/doc/models/v1-update-employee-role-request.md
deleted file mode 100644
index 771e296b..00000000
--- a/doc/models/v1-update-employee-role-request.md
+++ /dev/null
@@ -1,32 +0,0 @@
-
-# V1 Update Employee Role Request
-
-## Structure
-
-`V1 Update Employee Role Request`
-
-## Fields
-
-| Name | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `body` | [`V1 Employee Role`](/doc/models/v1-employee-role.md) | Required | V1EmployeeRole |
-
-## Example (as JSON)
-
-```json
-{
- "body": {
- "id": "id6",
- "name": "name6",
- "permissions": [
- "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
- "REGISTER_CHANGE_SETTINGS",
- "REGISTER_EDIT_ITEM"
- ],
- "is_owner": false,
- "created_at": "created_at4",
- "updated_at": "updated_at8"
- }
-}
-```
-
diff --git a/doc/models/workweek-config.md b/doc/models/workweek-config.md
index c15dcaed..fdd28f17 100644
--- a/doc/models/workweek-config.md
+++ b/doc/models/workweek-config.md
@@ -1,8 +1,8 @@
# Workweek Config
-Sets the Day of the week and hour of the day that a business starts a
-work week. Used for the calculation of overtime pay.
+Sets the day of the week and hour of the day that a business starts a
+workweek. This is used to calculate overtime pay.
## Structure
@@ -12,12 +12,12 @@ work week. Used for the calculation of overtime pay.
| Name | Type | Tags | Description |
| --- | --- | --- | --- |
-| `id` | `string` | Optional | UUID for this object |
+| `id` | `string` | Optional | The UUID for this object. |
| `start_of_week` | [`str (Weekday)`](/doc/models/weekday.md) | Required | The days of the week. |
-| `start_of_day_local_time` | `string` | Required | The local time at which a business week cuts over. Represented as a
string in `HH:MM` format (`HH:MM:SS` is also accepted, but seconds are
truncated).
**Constraints**: *Minimum Length*: `1` |
-| `version` | `int` | Optional | Used for resolving concurrency issues; request will fail if version
provided does not match server version at time of request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. |
-| `created_at` | `string` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC |
-| `updated_at` | `string` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC |
+| `start_of_day_local_time` | `string` | Required | The local time at which a business week ends. Represented as a
string in `HH:MM` format (`HH:MM:SS` is also accepted, but seconds are
truncated).
**Constraints**: *Minimum Length*: `1` |
+| `version` | `int` | Optional | Used for resolving concurrency issues. The request fails if the version
provided does not match the server version at the time of the request. If not provided,
Square executes a blind write; potentially overwriting data from another
write. |
+| `created_at` | `string` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. |
+| `updated_at` | `string` | Optional | A read-only timestamp in RFC 3339 format; presented in UTC. |
## Example (as JSON)
diff --git a/setup.py b/setup.py
index 3b20372a..85a4957f 100644
--- a/setup.py
+++ b/setup.py
@@ -12,7 +12,7 @@
setup(
name='squareup',
- version='14.0.0.20210915',
+ version='14.1.0.20210915',
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/__init__.py b/square/api/__init__.py
index 635b38a7..9777336a 100644
--- a/square/api/__init__.py
+++ b/square/api/__init__.py
@@ -2,7 +2,6 @@
'base_api',
'mobile_authorization_api',
'o_auth_api',
- 'v1_employees_api',
'v1_transactions_api',
'apple_pay_api',
'bank_accounts_api',
diff --git a/square/api/base_api.py b/square/api/base_api.py
index be997a0f..1d62defd 100644
--- a/square/api/base_api.py
+++ b/square/api/base_api.py
@@ -21,7 +21,7 @@ class BaseApi(object):
def global_headers(self):
return {
- 'user-agent': 'Square-Python-SDK/14.0.0.20210915',
+ 'user-agent': 'Square-Python-SDK/14.1.0.20210915',
'Square-Version': self.config.square_version
}
diff --git a/square/api/catalog_api.py b/square/api/catalog_api.py
index a857f2c4..9381d20b 100644
--- a/square/api/catalog_api.py
+++ b/square/api/catalog_api.py
@@ -589,7 +589,7 @@ def search_catalog_objects(self,
Searches for [CatalogObject]($m/CatalogObject) of any type by matching
supported search attribute values,
excluding custom attribute values on items or item variations, against
- one or more of the specified query expressions.
+ one or more of the specified query filters.
This (`SearchCatalogObjects`) endpoint differs from the
[SearchCatalogItems]($e/Catalog/SearchCatalogItems)
endpoint in the following aspects:
@@ -654,7 +654,7 @@ def search_catalog_items(self,
Searches for catalog items or item variations by matching supported
search attribute values, including
custom attribute values, against one or more of the specified query
- expressions.
+ filters.
This (`SearchCatalogItems`) endpoint differs from the
[SearchCatalogObjects]($e/Catalog/SearchCatalogObjects)
endpoint in the following aspects:
diff --git a/square/api/customer_groups_api.py b/square/api/customer_groups_api.py
index e5c7cf8a..405be32d 100644
--- a/square/api/customer_groups_api.py
+++ b/square/api/customer_groups_api.py
@@ -14,7 +14,8 @@ def __init__(self, config, call_back=None):
super(CustomerGroupsApi, self).__init__(config, call_back)
def list_customer_groups(self,
- cursor=None):
+ cursor=None,
+ limit=None):
"""Does a GET request to /v2/customers/groups.
Retrieves the list of customer groups of a business.
@@ -26,6 +27,13 @@ def list_customer_groups(self,
more information, see
[Pagination](https://developer.squareup.com/docs/working-with-a
pis/pagination).
+ limit (int, optional): The maximum number of results to return in
+ a single page. This limit is advisory. The response might
+ contain more or fewer results. The limit is ignored if it is
+ less than 1 or greater than 50. The default value is 50. For
+ more information, see
+ [Pagination](https://developer.squareup.com/docs/working-with-a
+ pis/pagination).
Returns:
ApiResponse: An object with the response value as well as other
@@ -44,7 +52,8 @@ def list_customer_groups(self,
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
- 'cursor': cursor
+ 'cursor': cursor,
+ 'limit': limit
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder,
diff --git a/square/api/customer_segments_api.py b/square/api/customer_segments_api.py
index 15ab1787..b1dda360 100644
--- a/square/api/customer_segments_api.py
+++ b/square/api/customer_segments_api.py
@@ -14,7 +14,8 @@ def __init__(self, config, call_back=None):
super(CustomerSegmentsApi, self).__init__(config, call_back)
def list_customer_segments(self,
- cursor=None):
+ cursor=None,
+ limit=None):
"""Does a GET request to /v2/customers/segments.
Retrieves the list of customer segments of a business.
@@ -26,6 +27,13 @@ def list_customer_segments(self,
information, see
[Pagination](https://developer.squareup.com/docs/working-with-a
pis/pagination).
+ limit (int, optional): The maximum number of results to return in
+ a single page. This limit is advisory. The response might
+ contain more or fewer results. The limit is ignored if it is
+ less than 1 or greater than 50. The default value is 50. For
+ more information, see
+ [Pagination](https://developer.squareup.com/docs/working-with-a
+ pis/pagination).
Returns:
ApiResponse: An object with the response value as well as other
@@ -44,7 +52,8 @@ def list_customer_segments(self,
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
- 'cursor': cursor
+ 'cursor': cursor,
+ 'limit': limit
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder,
diff --git a/square/api/customers_api.py b/square/api/customers_api.py
index 5e25e4e6..4fdebceb 100644
--- a/square/api/customers_api.py
+++ b/square/api/customers_api.py
@@ -16,6 +16,7 @@ def __init__(self, config, call_back=None):
def list_customers(self,
cursor=None,
+ limit=None,
sort_field=None,
sort_order=None):
"""Does a GET request to /v2/customers.
@@ -35,11 +36,18 @@ def list_customers(self,
more information, see
[Pagination](https://developer.squareup.com/docs/working-with-a
pis/pagination).
+ limit (int, optional): The maximum number of results to return in
+ a single page. This limit is advisory. The response might
+ contain more or fewer results. The limit is ignored if it is
+ less than 1 or greater than 100. The default value is 100.
+ For more information, see
+ [Pagination](https://developer.squareup.com/docs/working-with-a
+ pis/pagination).
sort_field (CustomerSortField, optional): Indicates how customers
- should be sorted. Default: `DEFAULT`.
+ should be sorted. The default value is `DEFAULT`.
sort_order (SortOrder, optional): Indicates whether customers
should be sorted in ascending (`ASC`) or descending (`DESC`)
- order. Default: `ASC`.
+ order. The default value is `ASC`.
Returns:
ApiResponse: An object with the response value as well as other
@@ -59,6 +67,7 @@ def list_customers(self,
_query_builder += _url_path
_query_parameters = {
'cursor': cursor,
+ 'limit': limit,
'sort_field': sort_field,
'sort_order': sort_order
}
@@ -219,7 +228,7 @@ def delete_customer(self,
Args:
customer_id (string): The ID of the customer to delete.
version (long|int, optional): The current version of the customer
- profile. As a best practice, you should include this
+ profile. As a best practice, you should include this
parameter to enable [optimistic
concurrency](https://developer.squareup.com/docs/working-with-a
pis/optimistic-concurrency) control. For more information,
diff --git a/square/api/gift_cards_api.py b/square/api/gift_cards_api.py
index c5683855..2a6eae27 100644
--- a/square/api/gift_cards_api.py
+++ b/square/api/gift_cards_api.py
@@ -96,8 +96,9 @@ def create_gift_card(self,
body):
"""Does a POST request to /v2/gift-cards.
- Creates a digital gift card. You must activate the gift card before
- it can be used. For more information, see
+ Creates a digital gift card or registers a physical (plastic) gift
+ card. You must activate the gift card before
+ it can be used for payment. For more information, see
[Selling gift
cards](https://developer.squareup.com/docs/gift-cards/using-gift-cards-
api#selling-square-gift-cards).
diff --git a/square/api/labor_api.py b/square/api/labor_api.py
index f7784b3d..91e79ae5 100644
--- a/square/api/labor_api.py
+++ b/square/api/labor_api.py
@@ -23,13 +23,14 @@ def list_break_types(self,
Returns a paginated list of `BreakType` instances for a business.
Args:
- location_id (string, optional): Filter Break Types returned to
- only those that are associated with the specified location.
- limit (int, optional): Maximum number of Break Types to return per
- page. Can range between 1 and 200. The default is the maximum
- at 200.
- cursor (string, optional): Pointer to the next page of Break Type
- results to fetch.
+ location_id (string, optional): Filter the returned `BreakType`
+ results to only those that are associated with the specified
+ location.
+ limit (int, optional): The maximum number of `BreakType` results
+ to return per page. The number can range between 1 and 200.
+ The default is 200.
+ cursor (string, optional): A pointer to the next page of
+ `BreakType` results to fetch.
Returns:
ApiResponse: An object with the response value as well as other
@@ -88,8 +89,8 @@ def create_break_type(self,
- `break_name`
- `expected_duration`
- `is_paid`
- You can only have 3 `BreakType` instances per location. If you attempt
- to add a 4th
+ You can only have three `BreakType` instances per location. If you
+ attempt to add a fourth
`BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit
of 3 breaks per location."
is returned.
@@ -144,7 +145,7 @@ def delete_break_type(self,
A `BreakType` can be deleted even if it is referenced from a `Shift`.
Args:
- id (string): UUID for the `BreakType` being deleted.
+ id (string): The UUID for the `BreakType` being deleted.
Returns:
ApiResponse: An object with the response value as well as other
@@ -189,10 +190,10 @@ def get_break_type(self,
id):
"""Does a GET request to /v2/labor/break-types/{id}.
- Returns a single `BreakType` specified by id.
+ Returns a single `BreakType` specified by `id`.
Args:
- id (string): UUID for the `BreakType` being retrieved.
+ id (string): The UUID for the `BreakType` being retrieved.
Returns:
ApiResponse: An object with the response value as well as other
@@ -241,7 +242,7 @@ def update_break_type(self,
Updates an existing `BreakType`.
Args:
- id (string): UUID for the `BreakType` being updated.
+ id (string): The UUID for the `BreakType` being updated.
body (UpdateBreakTypeRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
@@ -296,13 +297,13 @@ def list_employee_wages(self,
Returns a paginated list of `EmployeeWage` instances for a business.
Args:
- employee_id (string, optional): Filter wages returned to only
+ employee_id (string, optional): Filter the returned wages to only
those that are associated with the specified employee.
- limit (int, optional): Maximum number of Employee Wages to return
- per page. Can range between 1 and 200. The default is the
- maximum at 200.
- cursor (string, optional): Pointer to the next page of Employee
- Wage results to fetch.
+ limit (int, optional): The maximum number of `EmployeeWage`
+ results to return per page. The number can range between 1 and
+ 200. The default is 200.
+ cursor (string, optional): A pointer to the next page of
+ `EmployeeWage` results to fetch.
Returns:
ApiResponse: An object with the response value as well as other
@@ -354,10 +355,10 @@ def get_employee_wage(self,
id):
"""Does a GET request to /v2/labor/employee-wages/{id}.
- Returns a single `EmployeeWage` specified by id.
+ Returns a single `EmployeeWage` specified by `id`.
Args:
- id (string): UUID for the `EmployeeWage` being retrieved.
+ id (string): The UUID for the `EmployeeWage` being retrieved.
Returns:
ApiResponse: An object with the response value as well as other
@@ -403,7 +404,7 @@ def create_shift(self,
"""Does a POST request to /v2/labor/shifts.
Creates a new `Shift`.
- A `Shift` represents a complete work day for a single employee.
+ A `Shift` represents a complete workday for a single employee.
You must provide the following values in your request to this
endpoint:
- `location_id`
@@ -414,13 +415,12 @@ def create_shift(self,
- The `status` of the new `Shift` is `OPEN` and the employee has
another
shift with an `OPEN` status.
- - The `start_at` date is in the future
- - the `start_at` or `end_at` overlaps another shift for the same
- employee
- - If `Break`s are set in the request, a break `start_at`
- must not be before the `Shift.start_at`. A break `end_at` must not be
- after
- the `Shift.end_at`
+ - The `start_at` date is in the future.
+ - The `start_at` or `end_at` date overlaps another shift for the same
+ employee.
+ - The `Break` instances are set in the request and a break `start_at`
+ is before the `Shift.start_at`, a break `end_at` is after
+ the `Shift.end_at`, or both.
Args:
body (CreateShiftRequest): An object containing the fields to POST
@@ -470,17 +470,17 @@ def search_shifts(self,
Returns a paginated list of `Shift` records for a business.
The list to be returned can be filtered by:
- - Location IDs **and**
- - employee IDs **and**
- - shift status (`OPEN`, `CLOSED`) **and**
- - shift start **and**
- - shift end **and**
- - work day details
+ - Location IDs.
+ - Employee IDs.
+ - Shift status (`OPEN` and `CLOSED`).
+ - Shift start.
+ - Shift end.
+ - Workday details.
The list can be sorted by:
- - `start_at`
- - `end_at`
- - `created_at`
- - `updated_at`
+ - `start_at`.
+ - `end_at`.
+ - `created_at`.
+ - `updated_at`.
Args:
body (SearchShiftsRequest): An object containing the fields to
@@ -531,7 +531,7 @@ def delete_shift(self,
Deletes a `Shift`.
Args:
- id (string): UUID for the `Shift` being deleted.
+ id (string): The UUID for the `Shift` being deleted.
Returns:
ApiResponse: An object with the response value as well as other
@@ -576,10 +576,10 @@ def get_shift(self,
id):
"""Does a GET request to /v2/labor/shifts/{id}.
- Returns a single `Shift` specified by id.
+ Returns a single `Shift` specified by `id`.
Args:
- id (string): UUID for the `Shift` being retrieved.
+ id (string): The UUID for the `Shift` being retrieved.
Returns:
ApiResponse: An object with the response value as well as other
@@ -626,15 +626,15 @@ def update_shift(self,
"""Does a PUT request to /v2/labor/shifts/{id}.
Updates an existing `Shift`.
- When adding a `Break` to a `Shift`, any earlier `Breaks` in the
- `Shift` have
+ When adding a `Break` to a `Shift`, any earlier `Break` instances in
+ the `Shift` have
the `end_at` property set to a valid RFC-3339 datetime string.
- When closing a `Shift`, all `Break` instances in the shift must be
+ When closing a `Shift`, all `Break` instances in the `Shift` must be
complete with `end_at`
set on each `Break`.
Args:
- id (string): ID of the object being updated.
+ id (string): The ID of the object being updated.
body (UpdateShiftRequest): An object containing the fields to POST
for the request. See the corresponding object definition for
field details.
@@ -689,13 +689,14 @@ def list_team_member_wages(self,
business.
Args:
- team_member_id (string, optional): Filter wages returned to only
- those that are associated with the specified team member.
- limit (int, optional): Maximum number of Team Member Wages to
- return per page. Can range between 1 and 200. The default is
- the maximum at 200.
- cursor (string, optional): Pointer to the next page of Employee
- Wage results to fetch.
+ team_member_id (string, optional): Filter the returned wages to
+ only those that are associated with the specified team
+ member.
+ limit (int, optional): The maximum number of `TeamMemberWage`
+ results to return per page. The number can range between 1 and
+ 200. The default is 200.
+ cursor (string, optional): A pointer to the next page of
+ `EmployeeWage` results to fetch.
Returns:
ApiResponse: An object with the response value as well as other
@@ -746,10 +747,10 @@ def get_team_member_wage(self,
id):
"""Does a GET request to /v2/labor/team-member-wages/{id}.
- Returns a single `TeamMemberWage` specified by id.
+ Returns a single `TeamMemberWage` specified by `id `.
Args:
- id (string): UUID for the `TeamMemberWage` being retrieved.
+ id (string): The UUID for the `TeamMemberWage` being retrieved.
Returns:
ApiResponse: An object with the response value as well as other
@@ -798,10 +799,10 @@ def list_workweek_configs(self,
Returns a list of `WorkweekConfig` instances for a business.
Args:
- limit (int, optional): Maximum number of Workweek Configs to
- return per page.
- cursor (string, optional): Pointer to the next page of Workweek
- Config results to fetch.
+ limit (int, optional): The maximum number of `WorkweekConfigs`
+ results to return per page.
+ cursor (string, optional): A pointer to the next page of
+ `WorkweekConfig` results to fetch.
Returns:
ApiResponse: An object with the response value as well as other
@@ -855,7 +856,8 @@ def update_workweek_config(self,
Updates a `WorkweekConfig`.
Args:
- id (string): UUID for the `WorkweekConfig` object being updated.
+ id (string): The UUID for the `WorkweekConfig` object being
+ updated.
body (UpdateWorkweekConfigRequest): An object containing the
fields to POST for the request. See the corresponding object
definition for field details.
diff --git a/square/api/o_auth_api.py b/square/api/o_auth_api.py
index 0ecbeb28..8037983a 100644
--- a/square/api/o_auth_api.py
+++ b/square/api/o_auth_api.py
@@ -46,8 +46,8 @@ def renew_token(self,
dashboard](https://developer.squareup.com/apps).
Args:
- client_id (string): Your application ID, available from the
- [developer dashboard](https://developer.squareup.com/apps).
+ client_id (string): Your application ID, available from the OAuth
+ page for your application on the Developer Dashboard.
body (RenewTokenRequest): An object containing the fields to POST
for the request. See the corresponding object definition for
field details.
@@ -113,8 +113,7 @@ def revoke_token(self,
Authorization: Client APPLICATION_SECRET
```
Replace `APPLICATION_SECRET` with the application secret on the OAuth
- page in the [developer
- dashboard](https://developer.squareup.com/apps).
+ page for your application on the Developer Dashboard.
Args:
body (RevokeTokenRequest): An object containing the fields to POST
@@ -163,17 +162,28 @@ def obtain_token(self,
body):
"""Does a POST request to /oauth2/token.
- Returns an OAuth access token.
- The endpoint supports distinct methods of obtaining OAuth access
- tokens.
- Applications specify a method by adding the `grant_type` parameter
- in the request and also provide relevant information.
- __Note:__ Regardless of the method application specified,
- the endpoint always returns two items; an OAuth access token and
- a refresh token in the response.
- __OAuth tokens should only live on secure servers. Application
- clients
- should never interact directly with OAuth tokens__.
+ Returns an OAuth access token and a refresh token unless the
+ `short_lived` parameter is set to `true`, in which case the endpoint
+ returns only an access token.
+ The `grant_type` parameter specifies the type of OAuth request. If
+ `grant_type` is `authorization_code`, you must include the
+ authorization
+ code you received when a seller granted you authorization. If
+ `grant_type`
+ is `refresh_token`, you must provide a valid refresh token. If you are
+ using
+ an old version of the Square APIs (prior to March 13, 2019),
+ `grant_type`
+ can be `migration_token` and you must provide a valid migration
+ token.
+ You can use the `scopes` parameter to limit the set of permissions
+ granted
+ to the access token and refresh token. You can use the `short_lived`
+ parameter
+ to create an access token that expires in 24 hours.
+ __Note:__ OAuth tokens should be encrypted and stored on a secure
+ server.
+ Application clients should never interact directly with OAuth tokens.
Args:
body (ObtainTokenRequest): An object containing the fields to POST
diff --git a/square/api/orders_api.py b/square/api/orders_api.py
index a971ac61..656a19fc 100644
--- a/square/api/orders_api.py
+++ b/square/api/orders_api.py
@@ -167,6 +167,57 @@ def calculate_order(self,
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
+ def clone_order(self,
+ body):
+ """Does a POST request to /v2/orders/clone.
+
+ Creates a new order, in the `DRAFT` state, by duplicating an existing
+ order. The newly created order has
+ only the core fields (such as line items, taxes, and discounts) copied
+ from the original order.
+
+ Args:
+ body (CloneOrderRequest): An object containing the fields to POST
+ for the request. See the corresponding object definition for
+ field details.
+
+ Returns:
+ ApiResponse: An object with the response value as well as other
+ useful information such as status codes and headers. Success
+
+ Raises:
+ APIException: When an error occurs while fetching the data from
+ the remote API. This exception includes the HTTP Response
+ code, an error message, and the HTTP body that was received in
+ the request.
+
+ """
+
+ # Prepare query URL
+ _url_path = '/v2/orders/clone'
+ _query_builder = self.config.get_base_uri()
+ _query_builder += _url_path
+ _query_url = APIHelper.clean_url(_query_builder)
+
+ # Prepare headers
+ _headers = {
+ 'accept': 'application/json',
+ 'content-type': 'application/json; charset=utf-8'
+ }
+
+ # Prepare and execute request
+ _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
+ 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 search_orders(self,
body):
"""Does a POST request to /v2/orders/search.
diff --git a/square/api/v1_employees_api.py b/square/api/v1_employees_api.py
deleted file mode 100644
index b5229bf8..00000000
--- a/square/api/v1_employees_api.py
+++ /dev/null
@@ -1,492 +0,0 @@
-# -*- coding: utf-8 -*-
-
-from square.api_helper import APIHelper
-from square.http.api_response import ApiResponse
-from square.api.base_api import BaseApi
-from square.http.auth.o_auth_2 import OAuth2
-
-
-class V1EmployeesApi(BaseApi):
-
- """A Controller to access Endpoints in the square API."""
-
- def __init__(self, config, call_back=None):
- super(V1EmployeesApi, self).__init__(config, call_back)
-
- def list_employees(self,
- order=None,
- begin_updated_at=None,
- end_updated_at=None,
- begin_created_at=None,
- end_created_at=None,
- status=None,
- external_id=None,
- limit=None,
- batch_token=None):
- """Does a GET request to /v1/me/employees.
-
- Provides summary information for all of a business's employees.
-
- Args:
- order (SortOrder, optional): The order in which employees are
- listed in the response, based on their created_at field.
- Default value: ASC
- begin_updated_at (string, optional): If filtering results by their
- updated_at field, the beginning of the requested reporting
- period, in ISO 8601 format
- end_updated_at (string, optional): If filtering results by there
- updated_at field, the end of the requested reporting period,
- in ISO 8601 format.
- begin_created_at (string, optional): If filtering results by their
- created_at field, the beginning of the requested reporting
- period, in ISO 8601 format.
- end_created_at (string, optional): If filtering results by their
- created_at field, the end of the requested reporting period,
- in ISO 8601 format.
- status (V1ListEmployeesRequestStatus, optional): If provided, the
- endpoint returns only employee entities with the specified
- status (ACTIVE or INACTIVE).
- external_id (string, optional): If provided, the endpoint returns
- only employee entities with the specified external_id.
- limit (int, optional): The maximum integer number of employee
- entities to return in a single response. Default 100, maximum
- 200.
- batch_token (string, optional): A pagination cursor to retrieve
- the next set of results for your original query to the
- endpoint.
-
- 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 = '/v1/me/employees'
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_parameters = {
- 'order': order,
- 'begin_updated_at': begin_updated_at,
- 'end_updated_at': end_updated_at,
- 'begin_created_at': begin_created_at,
- 'end_created_at': end_created_at,
- 'status': status,
- 'external_id': external_id,
- 'limit': limit,
- 'batch_token': batch_token
- }
- _query_builder = APIHelper.append_url_with_query_parameters(
- _query_builder,
- _query_parameters
- )
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.get(_query_url, headers=_headers)
- 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 create_employee(self,
- body):
- """Does a POST request to /v1/me/employees.
-
- Use the CreateEmployee endpoint to add an employee to a Square
- account. Employees created with the Connect API have an initial
- status
- of `INACTIVE`. Inactive employees cannot sign in to Square Point of
- Sale
- until they are activated from the Square Dashboard. Employee status
- cannot be changed with the Connect API.
- Employee entities cannot be deleted. To disable employee profiles,
- set the employee's status to INACTIVE
-
- Args:
- body (V1Employee): An object containing the fields to POST for the
- request. See the corresponding object definition for field
- details.
-
- Returns:
- ApiResponse: An object with the response value as well as other
- useful information such as status codes and headers. Success
-
- Raises:
- APIException: When an error occurs while fetching the data from
- the remote API. This exception includes the HTTP Response
- code, an error message, and the HTTP body that was received in
- the request.
-
- """
-
- # Prepare query URL
- _url_path = '/v1/me/employees'
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json',
- 'content-type': 'application/json; charset=utf-8'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
- 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 retrieve_employee(self,
- employee_id):
- """Does a GET request to /v1/me/employees/{employee_id}.
-
- Provides the details for a single employee.
-
- Args:
- employee_id (string): The employee's ID.
-
- 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 = '/v1/me/employees/{employee_id}'
- _url_path = APIHelper.append_url_with_template_parameters(_url_path, {
- 'employee_id': {'value': employee_id, 'encode': True}
- })
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.get(_query_url, headers=_headers)
- 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 update_employee(self,
- employee_id,
- body):
- """Does a PUT request to /v1/me/employees/{employee_id}.
-
- UpdateEmployee
-
- Args:
- employee_id (string): The ID of the role to modify.
- body (V1Employee): An object containing the fields to POST for the
- request. See the corresponding object definition for field
- details.
-
- Returns:
- ApiResponse: An object with the response value as well as other
- useful information such as status codes and headers. Success
-
- Raises:
- APIException: When an error occurs while fetching the data from
- the remote API. This exception includes the HTTP Response
- code, an error message, and the HTTP body that was received in
- the request.
-
- """
-
- # Prepare query URL
- _url_path = '/v1/me/employees/{employee_id}'
- _url_path = APIHelper.append_url_with_template_parameters(_url_path, {
- 'employee_id': {'value': employee_id, 'encode': True}
- })
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json',
- 'content-type': 'application/json; charset=utf-8'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.put(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
- 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 list_employee_roles(self,
- order=None,
- limit=None,
- batch_token=None):
- """Does a GET request to /v1/me/roles.
-
- Provides summary information for all of a business's employee roles.
-
- Args:
- order (SortOrder, optional): The order in which employees are
- listed in the response, based on their created_at
- field.Default value: ASC
- limit (int, optional): The maximum integer number of employee
- entities to return in a single response. Default 100, maximum
- 200.
- batch_token (string, optional): A pagination cursor to retrieve
- the next set of results for your original query to the
- endpoint.
-
- 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 = '/v1/me/roles'
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_parameters = {
- 'order': order,
- 'limit': limit,
- 'batch_token': batch_token
- }
- _query_builder = APIHelper.append_url_with_query_parameters(
- _query_builder,
- _query_parameters
- )
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.get(_query_url, headers=_headers)
- 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 create_employee_role(self,
- body):
- """Does a POST request to /v1/me/roles.
-
- Creates an employee role you can then assign to employees.
- Square accounts can include any number of roles that can be assigned
- to
- employees. These roles define the actions and permissions granted to
- an
- employee with that role. For example, an employee with a "Shift
- Manager"
- role might be able to issue refunds in Square Point of Sale, whereas
- an
- employee with a "Clerk" role might not.
- Roles are assigned with the
- [V1UpdateEmployee]($e/V1Employees/UpdateEmployeeRole)
- endpoint. An employee can have only one role at a time.
- If an employee has no role, they have none of the permissions
- associated
- with roles. All employees can accept payments with Square Point of
- Sale.
-
- Args:
- body (V1EmployeeRole): An EmployeeRole object with a name and
- permissions, and an optional owner flag.
-
- 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 = '/v1/me/roles'
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json',
- 'content-type': 'application/json; charset=utf-8'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
- 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 retrieve_employee_role(self,
- role_id):
- """Does a GET request to /v1/me/roles/{role_id}.
-
- Provides the details for a single employee role.
-
- Args:
- role_id (string): The role's ID.
-
- 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 = '/v1/me/roles/{role_id}'
- _url_path = APIHelper.append_url_with_template_parameters(_url_path, {
- 'role_id': {'value': role_id, 'encode': True}
- })
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.get(_query_url, headers=_headers)
- 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 update_employee_role(self,
- role_id,
- body):
- """Does a PUT request to /v1/me/roles/{role_id}.
-
- Modifies the details of an employee role.
-
- Args:
- role_id (string): The ID of the role to modify.
- body (V1EmployeeRole): An object containing the fields to POST for
- the request. See the corresponding object definition for
- field details.
-
- Returns:
- ApiResponse: An object with the response value as well as other
- useful information such as status codes and headers. Success
-
- Raises:
- APIException: When an error occurs while fetching the data from
- the remote API. This exception includes the HTTP Response
- code, an error message, and the HTTP body that was received in
- the request.
-
- """
-
- # Prepare query URL
- _url_path = '/v1/me/roles/{role_id}'
- _url_path = APIHelper.append_url_with_template_parameters(_url_path, {
- 'role_id': {'value': role_id, 'encode': True}
- })
- _query_builder = self.config.get_base_uri()
- _query_builder += _url_path
- _query_url = APIHelper.clean_url(_query_builder)
-
- # Prepare headers
- _headers = {
- 'accept': 'application/json',
- 'content-type': 'application/json; charset=utf-8'
- }
-
- # Prepare and execute request
- _request = self.config.http_client.put(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
- 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
diff --git a/square/client.py b/square/client.py
index 8459b23e..4f685e3a 100644
--- a/square/client.py
+++ b/square/client.py
@@ -4,7 +4,6 @@
from square.configuration import Configuration
from square.api.mobile_authorization_api import MobileAuthorizationApi
from square.api.o_auth_api import OAuthApi
-from square.api.v1_employees_api import V1EmployeesApi
from square.api.v1_transactions_api import V1TransactionsApi
from square.api.apple_pay_api import ApplePayApi
from square.api.bank_accounts_api import BankAccountsApi
@@ -42,11 +41,11 @@ class Client(object):
@staticmethod
def sdk_version():
- return '14.0.0.20210915'
+ return '14.1.0.20210915'
@staticmethod
def square_version():
- return '2021-07-21'
+ return '2021-09-15'
@lazy_property
def mobile_authorization(self):
@@ -56,10 +55,6 @@ def mobile_authorization(self):
def o_auth(self):
return OAuthApi(self.config)
- @lazy_property
- def v1_employees(self):
- return V1EmployeesApi(self.config)
-
@lazy_property
def v1_transactions(self):
return V1TransactionsApi(self.config)
@@ -188,7 +183,7 @@ def __init__(self, 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-07-21', access_token='TODO: Replace',
+ square_version='2021-09-15', access_token='TODO: Replace',
additional_headers={}, config=None):
if config is None:
self.config = Configuration(timeout=timeout,
diff --git a/square/configuration.py b/square/configuration.py
index 9f15b7a8..e95f4153 100644
--- a/square/configuration.py
+++ b/square/configuration.py
@@ -57,7 +57,7 @@ def __init__(
self, 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-07-21',
+ custom_url='https://connect.squareup.com', square_version='2021-09-15',
access_token='TODO: Replace', additional_headers={}
):
# The value to use for connection timeout