From e1f76eb6e3cdf6dbefe5a8b46bb4182a7329da77 Mon Sep 17 00:00:00 2001 From: autobot Date: Wed, 21 Feb 2024 22:27:46 +0000 Subject: [PATCH] Generated PR for Release: 35.0.0.20240222 --- doc/api/checkout.md | 2 +- doc/api/customers.md | 230 ++++++++- doc/api/invoices.md | 5 +- doc/api/locations.md | 2 +- doc/api/v1-transactions.md | 328 ------------- doc/auth/oauth-2-bearer-token.md | 32 ++ doc/client.md | 19 +- doc/models/activity-type.md | 54 ++- doc/models/bulk-create-customer-data.md | 38 ++ doc/models/bulk-create-customers-request.md | 61 +++ doc/models/bulk-create-customers-response.md | 150 ++++++ doc/models/bulk-delete-customers-request.md | 28 ++ doc/models/bulk-delete-customers-response.md | 94 ++++ doc/models/bulk-retrieve-customers-request.md | 28 ++ .../bulk-retrieve-customers-response.md | 142 ++++++ doc/models/bulk-update-customer-data.md | 39 ++ doc/models/bulk-update-customers-request.md | 43 ++ doc/models/bulk-update-customers-response.md | 135 ++++++ doc/models/catalog-item-modifier-list-info.md | 7 +- .../catalog-modifier-list-modifier-type.md | 16 + doc/models/catalog-modifier-list.md | 24 +- doc/models/catalog-object.md | 2 +- doc/models/create-customer-response.md | 3 +- doc/models/list-payment-links-request.md | 2 +- doc/models/list-payment-links-response.md | 2 +- doc/models/order-line-item-tax.md | 2 +- .../payment-balance-activity-fee-detail.md | 2 +- doc/models/payment-refund.md | 2 +- doc/models/payout-entry.md | 2 +- .../retrieve-merchant-settings-response.md | 4 - doc/models/search-orders-response.md | 2 +- doc/models/update-customer-request.md | 2 +- doc/models/update-customer-response.md | 3 +- .../update-merchant-settings-response.md | 4 - doc/models/v1-create-refund-request-type.md | 14 - doc/models/v1-create-refund-request.md | 34 -- doc/models/v1-list-payments-request.md | 30 -- doc/models/v1-list-payments-response.md | 42 -- doc/models/v1-list-refunds-request.md | 29 -- doc/models/v1-list-refunds-response.md | 70 --- .../v1-list-settlements-request-status.md | 14 - doc/models/v1-list-settlements-request.md | 30 -- doc/models/v1-list-settlements-response.md | 52 -- doc/models/v1-payment-discount.md | 30 -- doc/models/v1-payment-item-detail.md | 29 -- ...v1-payment-itemization-itemization-type.md | 18 - doc/models/v1-payment-itemization.md | 60 --- doc/models/v1-payment-modifier.md | 30 -- doc/models/v1-payment-surcharge-type.md | 15 - doc/models/v1-payment-surcharge.md | 40 -- doc/models/v1-payment-tax-inclusion-type.md | 14 - doc/models/v1-payment-tax.md | 42 -- doc/models/v1-payment.md | 75 --- doc/models/v1-refund-type.md | 14 - doc/models/v1-refund.md | 53 --- doc/models/v1-settlement-entry-type.md | 33 -- doc/models/v1-settlement-entry.md | 35 -- doc/models/v1-settlement-status.md | 14 - doc/models/v1-settlement.md | 35 -- pyproject.toml | 2 +- square/api/apple_pay_api.py | 2 - square/api/bank_accounts_api.py | 2 - square/api/base_api.py | 10 +- square/api/booking_custom_attributes_api.py | 2 - square/api/bookings_api.py | 2 - square/api/cards_api.py | 2 - square/api/cash_drawers_api.py | 2 - square/api/catalog_api.py | 2 - square/api/checkout_api.py | 6 +- square/api/customer_custom_attributes_api.py | 2 - square/api/customer_groups_api.py | 2 - square/api/customer_segments_api.py | 2 - square/api/customers_api.py | 210 +++++++- square/api/devices_api.py | 2 - square/api/disputes_api.py | 2 - square/api/employees_api.py | 2 - square/api/gift_card_activities_api.py | 2 - square/api/gift_cards_api.py | 2 - square/api/inventory_api.py | 2 - square/api/invoices_api.py | 8 +- square/api/labor_api.py | 2 - square/api/location_custom_attributes_api.py | 2 - square/api/locations_api.py | 5 +- square/api/loyalty_api.py | 2 - square/api/merchant_custom_attributes_api.py | 2 - square/api/merchants_api.py | 2 - square/api/mobile_authorization_api.py | 2 - square/api/order_custom_attributes_api.py | 2 - square/api/orders_api.py | 2 - square/api/payments_api.py | 2 - square/api/payouts_api.py | 2 - square/api/refunds_api.py | 2 - square/api/sites_api.py | 2 - square/api/snippets_api.py | 2 - square/api/subscriptions_api.py | 2 - square/api/team_api.py | 2 - square/api/terminal_api.py | 2 - square/api/transactions_api.py | 2 - square/api/v1_transactions_api.py | 450 ------------------ square/api/vendors_api.py | 2 - square/api/webhook_subscriptions_api.py | 2 - square/client.py | 55 +-- square/configuration.py | 69 ++- square/http/auth/o_auth_2.py | 21 +- tests/api/api_test_base.py | 4 +- tests/api/test_locations_api.py | 4 +- 106 files changed, 1417 insertions(+), 1858 deletions(-) create mode 100644 doc/auth/oauth-2-bearer-token.md create mode 100644 doc/models/bulk-create-customer-data.md create mode 100644 doc/models/bulk-create-customers-request.md create mode 100644 doc/models/bulk-create-customers-response.md create mode 100644 doc/models/bulk-delete-customers-request.md create mode 100644 doc/models/bulk-delete-customers-response.md create mode 100644 doc/models/bulk-retrieve-customers-request.md create mode 100644 doc/models/bulk-retrieve-customers-response.md create mode 100644 doc/models/bulk-update-customer-data.md create mode 100644 doc/models/bulk-update-customers-request.md create mode 100644 doc/models/bulk-update-customers-response.md create mode 100644 doc/models/catalog-modifier-list-modifier-type.md delete mode 100644 doc/models/v1-create-refund-request-type.md delete mode 100644 doc/models/v1-create-refund-request.md delete mode 100644 doc/models/v1-list-payments-request.md delete mode 100644 doc/models/v1-list-payments-response.md delete mode 100644 doc/models/v1-list-refunds-request.md delete mode 100644 doc/models/v1-list-refunds-response.md delete mode 100644 doc/models/v1-list-settlements-request-status.md delete mode 100644 doc/models/v1-list-settlements-request.md delete mode 100644 doc/models/v1-list-settlements-response.md delete mode 100644 doc/models/v1-payment-discount.md delete mode 100644 doc/models/v1-payment-item-detail.md delete mode 100644 doc/models/v1-payment-itemization-itemization-type.md delete mode 100644 doc/models/v1-payment-itemization.md delete mode 100644 doc/models/v1-payment-modifier.md delete mode 100644 doc/models/v1-payment-surcharge-type.md delete mode 100644 doc/models/v1-payment-surcharge.md delete mode 100644 doc/models/v1-payment-tax-inclusion-type.md delete mode 100644 doc/models/v1-payment-tax.md delete mode 100644 doc/models/v1-payment.md delete mode 100644 doc/models/v1-refund-type.md delete mode 100644 doc/models/v1-refund.md delete mode 100644 doc/models/v1-settlement-entry-type.md delete mode 100644 doc/models/v1-settlement-entry.md delete mode 100644 doc/models/v1-settlement-status.md delete mode 100644 doc/models/v1-settlement.md diff --git a/doc/api/checkout.md b/doc/api/checkout.md index 4bc796c0..1fa84c96 100644 --- a/doc/api/checkout.md +++ b/doc/api/checkout.md @@ -311,7 +311,7 @@ def list_payment_links(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `cursor` | `str` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If a cursor is not provided, the endpoint returns the first page of the results.
For more information, see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). | +| `cursor` | `str` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If a cursor is not provided, the endpoint returns the first page of the results.
For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `limit` | `int` | Query, Optional | A limit on the number of results to return per page. The limit is advisory and
the implementation might return more or less results. If the supplied limit is negative, zero, or
greater than the maximum limit of 1000, it is ignored.

Default value: `100` | ## Response Type diff --git a/doc/api/customers.md b/doc/api/customers.md index 84a5a6f1..6686a0cc 100644 --- a/doc/api/customers.md +++ b/doc/api/customers.md @@ -12,6 +12,10 @@ customers_api = client.customers * [List Customers](../../doc/api/customers.md#list-customers) * [Create Customer](../../doc/api/customers.md#create-customer) +* [Bulk Create Customers](../../doc/api/customers.md#bulk-create-customers) +* [Bulk Delete Customers](../../doc/api/customers.md#bulk-delete-customers) +* [Bulk Retrieve Customers](../../doc/api/customers.md#bulk-retrieve-customers) +* [Bulk Update Customers](../../doc/api/customers.md#bulk-update-customers) * [Search Customers](../../doc/api/customers.md#search-customers) * [Delete Customer](../../doc/api/customers.md#delete-customer) * [Retrieve Customer](../../doc/api/customers.md#retrieve-customer) @@ -128,6 +132,221 @@ elif result.is_error(): ``` +# Bulk Create Customers + +Creates multiple [customer profiles](../../doc/models/customer.md) for a business. + +This endpoint takes a map of individual create requests and returns a map of responses. + +You must provide at least one of the following values in each create request: + +- `given_name` +- `family_name` +- `company_name` +- `email_address` +- `phone_number` + +```python +def bulk_create_customers(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Bulk Create Customers Request`](../../doc/models/bulk-create-customers-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Create Customers Response`](../../doc/models/bulk-create-customers-response.md). + +## Example Usage + +```python +body = { + 'customers': { + '8bb76c4f-e35d-4c5b-90de-1194cd9179f0': { + 'given_name': 'Amelia', + 'family_name': 'Earhart', + 'email_address': 'Amelia.Earhart@example.com', + 'address': { + 'address_line_1': '500 Electric Ave', + 'address_line_2': 'Suite 600', + 'locality': 'New York', + 'administrative_district_level_1': 'NY', + 'postal_code': '10003', + 'country': 'US' + }, + 'phone_number': '+1-212-555-4240', + 'reference_id': 'YOUR_REFERENCE_ID', + 'note': 'a customer' + }, + 'd1689f23-b25d-4932-b2f0-aed00f5e2029': { + 'given_name': 'Marie', + 'family_name': 'Curie', + 'email_address': 'Marie.Curie@example.com', + 'address': { + 'address_line_1': '500 Electric Ave', + 'address_line_2': 'Suite 601', + 'locality': 'New York', + 'administrative_district_level_1': 'NY', + 'postal_code': '10003', + 'country': 'US' + }, + 'phone_number': '+1-212-444-4240', + 'reference_id': 'YOUR_REFERENCE_ID', + 'note': 'another customer' + } + } +} + +result = customers_api.bulk_create_customers(body) +print(result) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Bulk Delete Customers + +Deletes multiple customer profiles. + +The endpoint takes a list of customer IDs and returns a map of responses. + +```python +def bulk_delete_customers(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Bulk Delete Customers Request`](../../doc/models/bulk-delete-customers-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Delete Customers Response`](../../doc/models/bulk-delete-customers-response.md). + +## Example Usage + +```python +body = { + 'customer_ids': [ + '8DDA5NZVBZFGAX0V3HPF81HHE0', + 'N18CPRVXR5214XPBBA6BZQWF3C', + '2GYD7WNXF7BJZW1PMGNXZ3Y8M8' + ] +} + +result = customers_api.bulk_delete_customers(body) +print(result) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Bulk Retrieve Customers + +Retrieves multiple customer profiles. + +This endpoint takes a list of customer IDs and returns a map of responses. + +```python +def bulk_retrieve_customers(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Bulk Retrieve Customers Request`](../../doc/models/bulk-retrieve-customers-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Retrieve Customers Response`](../../doc/models/bulk-retrieve-customers-response.md). + +## Example Usage + +```python +body = { + 'customer_ids': [ + '8DDA5NZVBZFGAX0V3HPF81HHE0', + 'N18CPRVXR5214XPBBA6BZQWF3C', + '2GYD7WNXF7BJZW1PMGNXZ3Y8M8' + ] +} + +result = customers_api.bulk_retrieve_customers(body) +print(result) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Bulk Update Customers + +Updates multiple customer profiles. + +This endpoint takes a map of individual update requests and returns a map of responses. + +You cannot use this endpoint to change cards on file. To make changes, use the [Cards API](../../doc/api/cards.md) or [Gift Cards API](../../doc/api/gift-cards.md). + +```python +def bulk_update_customers(self, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`Bulk Update Customers Request`](../../doc/models/bulk-update-customers-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`Bulk Update Customers Response`](../../doc/models/bulk-update-customers-response.md). + +## Example Usage + +```python +body = { + 'customers': { + '8DDA5NZVBZFGAX0V3HPF81HHE0': { + 'email_address': 'New.Amelia.Earhart@example.com', + 'phone_number': 'phone_number2', + 'note': 'updated customer note', + 'version': 2 + }, + 'N18CPRVXR5214XPBBA6BZQWF3C': { + 'given_name': 'Marie', + 'family_name': 'Curie', + 'version': 0 + } + } +} + +result = customers_api.bulk_update_customers(body) +print(result) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + # Search Customers Searches the customer profiles associated with a Square account using one or more supported query filters. @@ -202,9 +421,6 @@ elif result.is_error(): Deletes a customer profile from a business. This operation also unlinks any associated cards on file. -As a best practice, include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. -If included, the value must be set to the current version of the customer profile. - To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile. ```python @@ -276,11 +492,7 @@ elif result.is_error(): # Update Customer Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request. -To add or update a field, specify the new value. To remove a field, specify `null` -(recommended) or specify an empty string (string fields only). - -As a best practice, include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. -If included, the value must be set to the current version of the customer profile. +To add or update a field, specify the new value. To remove a field, specify `null`. To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile. @@ -310,7 +522,7 @@ customer_id = 'customer_id8' body = { 'email_address': 'New.Amelia.Earhart@example.com', - 'phone_number': '', + 'phone_number': 'phone_number2', 'note': 'updated customer note', 'version': 2 } diff --git a/doc/api/invoices.md b/doc/api/invoices.md index 28a6e80f..28f65d62 100644 --- a/doc/api/invoices.md +++ b/doc/api/invoices.md @@ -484,9 +484,12 @@ nothing. Square also makes the invoice available on a Square-hosted invoice page The invoice `status` also changes from `DRAFT` to a status based on the invoice configuration. For example, the status changes to `UNPAID` if -Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on file for a portion of the +Square emails the invoice or `PARTIALLY_PAID` if Square charges a card on file for a portion of the invoice amount. +In addition to the required `ORDERS_WRITE` and `INVOICES_WRITE` permissions, `CUSTOMERS_READ` +and `PAYMENTS_WRITE` are required when publishing invoices configured for card-on-file payments. + ```python def publish_invoice(self, invoice_id, diff --git a/doc/api/locations.md b/doc/api/locations.md index 2db8ce2c..2b7a1e04 100644 --- a/doc/api/locations.md +++ b/doc/api/locations.md @@ -19,7 +19,7 @@ locations_api = client.locations # List Locations Provides details about all of the seller's [locations](https://developer.squareup.com/docs/locations-api), -including those with an inactive status. +including those with an inactive status. Locations are listed alphabetically by `name`. ```python def list_locations(self) diff --git a/doc/api/v1-transactions.md b/doc/api/v1-transactions.md index 2eeebed7..f3a62798 100644 --- a/doc/api/v1-transactions.md +++ b/doc/api/v1-transactions.md @@ -13,12 +13,6 @@ v1_transactions_api = client.v1_transactions * [V1 List Orders](../../doc/api/v1-transactions.md#v1-list-orders) * [V1 Retrieve Order](../../doc/api/v1-transactions.md#v1-retrieve-order) * [V1 Update Order](../../doc/api/v1-transactions.md#v1-update-order) -* [V1 List Payments](../../doc/api/v1-transactions.md#v1-list-payments) -* [V1 Retrieve Payment](../../doc/api/v1-transactions.md#v1-retrieve-payment) -* [V1 List Refunds](../../doc/api/v1-transactions.md#v1-list-refunds) -* [V1 Create Refund](../../doc/api/v1-transactions.md#v1-create-refund) -* [V1 List Settlements](../../doc/api/v1-transactions.md#v1-list-settlements) -* [V1 Retrieve Settlement](../../doc/api/v1-transactions.md#v1-retrieve-settlement) # V1 List Orders @@ -155,325 +149,3 @@ elif result.is_error(): print(result.errors) ``` - -# V1 List Payments - -**This endpoint is deprecated.** - -Provides summary information for all payments taken for a given -Square account during a date range. Date ranges cannot exceed 1 year in -length. See Date ranges for details of inclusive and exclusive dates. - -*Note**: Details for payments processed with Square Point of Sale while -in offline mode may not be transmitted to Square for up to 72 hours. -Offline payments have a `created_at` value that reflects the time the -payment was originally processed, not the time it was subsequently -transmitted to Square. Consequently, the ListPayments endpoint might -list an offline payment chronologically between online payments that -were seen in a previous request. - -```python -def v1_list_payments(self, - location_id, - order=None, - begin_time=None, - end_time=None, - limit=None, - batch_token=None, - include_partial=False) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `str` | Template, Required | The ID of the location to list payments for. If you specify me, this endpoint returns payments aggregated from all of the business's locations. | -| `order` | [`str (Sort Order)`](../../doc/models/sort-order.md) | Query, Optional | The order in which payments are listed in the response. | -| `begin_time` | `str` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `str` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `int` | Query, Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `batch_token` | `str` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | -| `include_partial` | `bool` | Query, Optional | Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. | - -## Response Type - -This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`List V1 Payment`](../../doc/models/v1-payment.md). - -## Example Usage - -```python -location_id = 'location_id4' - -include_partial = False - -result = v1_transactions_api.v1_list_payments( - location_id, - include_partial=include_partial -) -print(result) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - -# V1 Retrieve Payment - -**This endpoint is deprecated.** - -Provides comprehensive information for a single payment. - -```python -def v1_retrieve_payment(self, - location_id, - payment_id) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `str` | Template, Required | The ID of the payment's associated location. | -| `payment_id` | `str` | Template, Required | The Square-issued payment ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint. | - -## Response Type - -This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`V1 Payment`](../../doc/models/v1-payment.md). - -## Example Usage - -```python -location_id = 'location_id4' - -payment_id = 'payment_id0' - -result = v1_transactions_api.v1_retrieve_payment( - location_id, - payment_id -) -print(result) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - -# V1 List Refunds - -**This endpoint is deprecated.** - -Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. - -```python -def v1_list_refunds(self, - location_id, - order=None, - begin_time=None, - end_time=None, - limit=None, - batch_token=None) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `str` | Template, Required | The ID of the location to list refunds for. | -| `order` | [`str (Sort Order)`](../../doc/models/sort-order.md) | Query, Optional | The order in which payments are listed in the response. | -| `begin_time` | `str` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `str` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `int` | Query, Optional | The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. | -| `batch_token` | `str` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -## Response Type - -This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`List V1 Refund`](../../doc/models/v1-refund.md). - -## Example Usage - -```python -location_id = 'location_id4' - -result = v1_transactions_api.v1_list_refunds(location_id) -print(result) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - -# V1 Create Refund - -**This endpoint is deprecated.** - -Issues a refund for a previously processed payment. You must issue -a refund within 60 days of the associated payment. - -You cannot issue a partial refund for a split tender payment. You must -instead issue a full or partial refund for a particular tender, by -providing the applicable tender id to the V1CreateRefund endpoint. -Issuing a full refund for a split tender payment refunds all tenders -associated with the payment. - -Issuing a refund for a card payment is not reversible. For development -purposes, you can create fake cash payments in Square Point of Sale and -refund them. - -```python -def v1_create_refund(self, - location_id, - body) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `str` | Template, Required | The ID of the original payment's associated location. | -| `body` | [`V1 Create Refund Request`](../../doc/models/v1-create-refund-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | - -## Response Type - -This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`V1 Refund`](../../doc/models/v1-refund.md). - -## Example Usage - -```python -location_id = 'location_id4' - -body = { - 'payment_id': 'payment_id6', - 'type': 'FULL', - 'reason': 'reason8' -} - -result = v1_transactions_api.v1_create_refund( - location_id, - body -) -print(result) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - -# V1 List Settlements - -**This endpoint is deprecated.** - -Provides summary information for all deposits and withdrawals -initiated by Square to a linked bank account during a date range. Date -ranges cannot exceed one year in length. - -*Note**: the ListSettlements endpoint does not provide entry -information. - -```python -def v1_list_settlements(self, - location_id, - order=None, - begin_time=None, - end_time=None, - limit=None, - status=None, - batch_token=None) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `str` | Template, Required | The ID of the location to list settlements for. If you specify me, this endpoint returns settlements aggregated from all of the business's locations. | -| `order` | [`str (Sort Order)`](../../doc/models/sort-order.md) | Query, Optional | The order in which settlements are listed in the response. | -| `begin_time` | `str` | Query, Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `str` | Query, Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `int` | Query, Optional | The maximum number of settlements to return in a single response. This value cannot exceed 200. | -| `status` | [`str (V1 List Settlements Request Status)`](../../doc/models/v1-list-settlements-request-status.md) | Query, Optional | Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED). | -| `batch_token` | `str` | Query, Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | - -## Response Type - -This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`List V1 Settlement`](../../doc/models/v1-settlement.md). - -## Example Usage - -```python -location_id = 'location_id4' - -result = v1_transactions_api.v1_list_settlements(location_id) -print(result) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - - -# V1 Retrieve Settlement - -**This endpoint is deprecated.** - -Provides comprehensive information for a single settlement. - -The returned `Settlement` objects include an `entries` field that lists -the transactions that contribute to the settlement total. Most -settlement entries correspond to a payment payout, but settlement -entries are also generated for less common events, like refunds, manual -adjustments, or chargeback holds. - -Square initiates its regular deposits as indicated in the -[Deposit Options with Square](https://squareup.com/help/us/en/article/3807) -help article. Details for a regular deposit are usually not available -from Connect API endpoints before 10 p.m. PST the same day. - -Square does not know when an initiated settlement **completes**, only -whether it has failed. A completed settlement is typically reflected in -a bank account within 3 business days, but in exceptional cases it may -take longer. - -```python -def v1_retrieve_settlement(self, - location_id, - settlement_id) -``` - -## Parameters - -| Parameter | Type | Tags | Description | -| --- | --- | --- | --- | -| `location_id` | `str` | Template, Required | The ID of the settlements's associated location. | -| `settlement_id` | `str` | Template, Required | The settlement's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint. | - -## Response Type - -This method returns a `ApiResponse` instance. The `body` property of this instance returns the response data which is of type [`V1 Settlement`](../../doc/models/v1-settlement.md). - -## Example Usage - -```python -location_id = 'location_id4' - -settlement_id = 'settlement_id0' - -result = v1_transactions_api.v1_retrieve_settlement( - location_id, - settlement_id -) -print(result) - -if result.is_success(): - print(result.body) -elif result.is_error(): - print(result.errors) -``` - diff --git a/doc/auth/oauth-2-bearer-token.md b/doc/auth/oauth-2-bearer-token.md new file mode 100644 index 00000000..3cd2cfbe --- /dev/null +++ b/doc/auth/oauth-2-bearer-token.md @@ -0,0 +1,32 @@ + +# OAuth 2 Bearer token + + + +Documentation for accessing and setting credentials for global. + +## Auth Credentials + +| Name | Type | Description | Getter | +| --- | --- | --- | --- | +| AccessToken | `str` | The OAuth 2.0 Access Token to use for API requests. | `access_token` | + + + +**Note:** Auth credentials can be set using `BearerAuthCredentials` object, passed in as named parameter `bearer_auth_credentials` in the client initialization. + +## Usage Example + +### Client Initialization + +You must provide credentials in the client as shown in the following code snippet. + +```python +client = Client( + bearer_auth_credentials=BearerAuthCredentials( + access_token='AccessToken' + ) +) +``` + + diff --git a/doc/client.md b/doc/client.md index 11605faf..aa7320fc 100644 --- a/doc/client.md +++ b/doc/client.md @@ -5,7 +5,7 @@ The following parameters are configurable for the API Client: | Parameter | Type | Description | | --- | --- | --- | -| `square_version` | `str` | Square Connect API versions
*Default*: `'2024-01-18'` | +| `square_version` | `str` | Square Connect API versions
*Default*: `'2024-02-22'` | | `custom_url` | `str` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
*Default*: `'https://connect.squareup.com'` | | `environment` | `string` | The API environment.
**Default: `production`** | | `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests | @@ -18,15 +18,16 @@ The following parameters are configurable for the API Client: | `retry_methods` | `Array of string` | The http methods on which retry is to be done.
**Default: ['GET', 'PUT']** | | `additional_headers` | `dict` | Additional headers to add to each API request | | `user_agent_detail` | `string` | User agent detail, to be appended with user-agent header. | -| `access_token` | `str` | The OAuth 2.0 Access Token to use for API requests. | +| `bearer_auth_credentials` | [`BearerAuthCredentials`](auth/oauth-2-bearer-token.md) | The credential object for OAuth 2 Bearer token | The API client can be initialized as follows: ```python -from square.client import Client client = Client( - square_version='2024-01-18', - access_token='AccessToken' + square_version='2024-02-22', + bearer_auth_credentials=BearerAuthCredentials( + access_token='AccessToken' + ) ) ``` @@ -46,10 +47,14 @@ API calls return an `ApiResponse` object that includes the following fields: ## Make Calls with the API Client ```python +from square.http.auth.o_auth_2 import BearerAuthCredentials from square.client import Client + client = Client( - square_version='2024-01-18', - access_token='AccessToken' + square_version='2024-02-22', + bearer_auth_credentials=BearerAuthCredentials( + access_token='AccessToken' + ) ) locations_api = client.locations diff --git a/doc/models/activity-type.md b/doc/models/activity-type.md index a7fe5ce7..c54172a4 100644 --- a/doc/models/activity-type.md +++ b/doc/models/activity-type.md @@ -12,40 +12,56 @@ | `ADJUSTMENT` | A manual adjustment applied to the seller's account by Square. | | `APP_FEE_REFUND` | A refund for an application fee on a payment. | | `APP_FEE_REVENUE` | Revenue generated from an application fee on a payment. | -| `AUTOMATIC_SAVINGS` | An automatic transfer from the payment processing balance to the Square Savings account.
These are, generally, proportional to the seller's sales. | -| `AUTOMATIC_SAVINGS_REVERSED` | An automatic transfer from the Square Savings account back to the processing balance.
These are, generally, proportional to the seller's refunds. | +| `AUTOMATIC_SAVINGS` | An automatic transfer from the payment processing balance to the Square Savings account. These are generally proportional to the seller's sales. | +| `AUTOMATIC_SAVINGS_REVERSED` | An automatic transfer from the Square Savings account back to the processing balance. These are generally proportional to the seller's refunds. | | `CHARGE` | A credit card payment capture. | | `DEPOSIT_FEE` | Any fees involved with deposits such as instant deposits. | | `DISPUTE` | The balance change due to a dispute event. | | `ESCHEATMENT` | An escheatment entry for remittance. | -| `FEE` | The Square processing fee. | +| `FEE` | The cost plus adjustment fee. | | `FREE_PROCESSING` | Square offers free payments processing for a variety of business scenarios, including seller
referrals or when Square wants to apologize (for example, for a bug, customer service, or repricing complication).
This entry represents a credit to the seller for the purposes of free processing. | | `HOLD_ADJUSTMENT` | An adjustment made by Square related to holding a payment. | -| `INITIAL_BALANCE_CHANGE` | An external change to a seller's balance. Initial, in the sense that it
causes the creation of the other activity types, such as hold and refund. | +| `INITIAL_BALANCE_CHANGE` | An external change to a seller's balance (initial, in the sense that it causes the creation of the other activity types, such as a hold and refund). | | `MONEY_TRANSFER` | The balance change from a money transfer. | | `MONEY_TRANSFER_REVERSAL` | The reversal of a money transfer. | -| `OPEN_DISPUTE` | The balance change for a chargeback that has been filed. | -| `OTHER` | Any other type that does not belong in the rest of the types. | -| `OTHER_ADJUSTMENT` | Any other type of adjustment that does not fall under existing types. | -| `PAID_SERVICE_FEE` | A fee paid to a third-party merchant. | -| `PAID_SERVICE_FEE_REFUND` | A fee paid to a third-party merchant. | +| `OPEN_DISPUTE` | The balance change for a chargeback that's been filed. | +| `OTHER` | Any other type that doesn't belong in the rest of the types. | +| `OTHER_ADJUSTMENT` | Any other type of adjustment that doesn't fall under existing types. | +| `PAID_SERVICE_FEE` | A fee paid to a third-party seller. | +| `PAID_SERVICE_FEE_REFUND` | A fee refunded to a third-party seller. | | `REDEMPTION_CODE` | Repayment for a redemption code. | | `REFUND` | A refund for an existing card payment. | | `RELEASE_ADJUSTMENT` | An adjustment made by Square related to releasing a payment. | -| `RESERVE_HOLD` | Fees paid for funding risk reserve. | -| `RESERVE_RELEASE` | Fees released from risk reserve. | +| `RESERVE_HOLD` | Fees paid for a funding risk reserve. | +| `RESERVE_RELEASE` | Fees released from a risk reserve. | | `RETURNED_PAYOUT` | An entry created when Square receives a response for the ACH file that Square sent indicating that the
settlement of the original entry failed. | -| `SQUARE_CAPITAL_PAYMENT` | A capital merchant cash advance (MCA) assessment. These are, generally,
proportional to the merchant's sales but can be issued for other reasons related to the MCA. | -| `SQUARE_CAPITAL_REVERSED_PAYMENT` | A capital merchant cash advance (MCA) assessment refund. These are, generally,
proportional to the merchant's refunds but can be issued for other reasons related to the MCA. | +| `SQUARE_CAPITAL_PAYMENT` | A capital merchant cash advance (MCA) assessment. These are generally proportional to the merchant's sales but can be issued for other reasons related to the MCA. | +| `SQUARE_CAPITAL_REVERSED_PAYMENT` | A capital merchant cash advance (MCA) assessment refund. These are generally proportional to the merchant's refunds but can be issued for other reasons related to the MCA. | | `SUBSCRIPTION_FEE` | A fee charged for subscription to a Square product. | -| `SUBSCRIPTION_FEE_PAID_REFUND` | A Square subscription fee that has been refunded. | +| `SUBSCRIPTION_FEE_PAID_REFUND` | A Square subscription fee that's been refunded. | | `SUBSCRIPTION_FEE_REFUND` | The refund of a previously charged Square product subscription fee. | | `TAX_ON_FEE` | The tax paid on fee amounts. | | `THIRD_PARTY_FEE` | Fees collected by a third-party platform. | | `THIRD_PARTY_FEE_REFUND` | Refunded fees from a third-party platform. | -| `PAYOUT` | Balance change due to money transfer. | -| `AUTOMATIC_BITCOIN_CONVERSIONS` | Indicates the withholding of a portion of each payment by Square that has been
automatically converted into bitcoin using Cash App. The seller manages their bitcoin in
their Cash App account. | -| `AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED` | Indicates a return of the payment withholding that had been scheduled to be converted
into bitcoin using Cash App to the Square payments balance. | -| `CREDIT_CARD_REPAYMENT` | The repayment made toward the outstanding balance on the seller's Square credit card. | -| `CREDIT_CARD_REPAYMENT_REVERSED` | The reversal of the repayment made toward the outstanding balance on the seller's
Square credit card. | +| `PAYOUT` | The balance change due to money transfer. | +| `AUTOMATIC_BITCOIN_CONVERSIONS` | Indicates that the portion of each payment withheld by Square was automatically converted into bitcoin using Cash App. The seller manages their bitcoin in their Cash App account. | +| `AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED` | Indicates that a withheld payment, which was scheduled to be converted into bitcoin using Cash App, was deposited back to the Square payments balance. | +| `CREDIT_CARD_REPAYMENT` | Indicates that a repayment toward the outstanding balance on the seller's Square credit card was made. | +| `CREDIT_CARD_REPAYMENT_REVERSED` | Indicates that a repayment toward the outstanding balance on the seller's Square credit card was reversed. | +| `LOCAL_OFFERS_CASHBACK` | Cashback amount given by a Square Local Offers seller to their customer for a purchase. | +| `LOCAL_OFFERS_FEE` | A commission fee paid by a Square Local Offers seller to Square for a purchase discovered through Square Local Offers. | +| `PERCENTAGE_PROCESSING_ENROLLMENT` | When activating Percentage Processing, a credit is applied to the seller’s account to offset any negative balance caused by a dispute. | +| `PERCENTAGE_PROCESSING_DEACTIVATION` | Deducting the outstanding Percentage Processing balance from the seller’s account. It's the final installment in repaying the dispute-induced negative balance through percentage processing. | +| `PERCENTAGE_PROCESSING_REPAYMENT` | Withheld funds from a payment to cover a negative balance. It's an installment to repay the amount from a dispute that had been offset during Percentage Processing enrollment. | +| `PERCENTAGE_PROCESSING_REPAYMENT_REVERSED` | The reversal of a percentage processing repayment that happens for example when a refund is issued for a payment. | +| `PROCESSING_FEE` | The processing fee for a payment. If sellers opt for Gross Settlement, i.e., direct bank withdrawal instead of deducting fees from daily sales, the processing fee is recorded separately as a new payout entry, not part of the CHARGE payout entry. | +| `PROCESSING_FEE_REFUND` | The processing fee for a payment refund issued by sellers enrolled in Gross Settlement. The refunded processing fee is recorded separately as a new payout entry, not part of the REFUND payout entry. | +| `UNDO_PROCESSING_FEE_REFUND` | When undoing a processing fee refund in a Gross Settlement payment, this payout entry type is used. | +| `GIFT_CARD_LOAD_FEE` | Fee collected during the sale or reload of a gift card. This fee, which is a portion of the amount loaded on the gift card, is deducted from the merchant's payment balance. | +| `GIFT_CARD_LOAD_FEE_REFUND` | Refund for fee charged during the sale or reload of a gift card. | +| `UNDO_GIFT_CARD_LOAD_FEE_REFUND` | The undo of a refund for a fee charged during the sale or reload of a gift card. | +| `BALANCE_FOLDERS_TRANSFER` | A transfer of funds to a banking folder. In the United States, the folder name is 'Checking Folder'; in Canada, it's 'Balance Folder.' | +| `BALANCE_FOLDERS_TRANSFER_REVERSED` | A reversal of transfer of funds from a banking folder. In the United States, the folder name is 'Checking Folder'; in Canada, it's 'Balance Folder.' | +| `GIFT_CARD_POOL_TRANSFER` | A transfer of gift card funds to a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor's account. | +| `GIFT_CARD_POOL_TRANSFER_REVERSED` | A reversal of transfer of gift card funds from a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor's account. | diff --git a/doc/models/bulk-create-customer-data.md b/doc/models/bulk-create-customer-data.md new file mode 100644 index 00000000..6d3493e4 --- /dev/null +++ b/doc/models/bulk-create-customer-data.md @@ -0,0 +1,38 @@ + +# Bulk Create Customer Data + +Defines the customer data provided in individual create requests for a +[BulkCreateCustomers](../../doc/api/customers.md#bulk-create-customers) operation. + +## Structure + +`Bulk Create Customer Data` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `given_name` | `str` | Optional | The given name (that is, the first name) associated with the customer profile.
**Constraints**: *Maximum Length*: `300` | +| `family_name` | `str` | Optional | The family name (that is, the last name) associated with the customer profile.
**Constraints**: *Maximum Length*: `300` | +| `company_name` | `str` | Optional | A business name associated with the customer profile.
**Constraints**: *Maximum Length*: `500` | +| `nickname` | `str` | Optional | A nickname for the customer profile.
**Constraints**: *Maximum Length*: `100` | +| `email_address` | `str` | Optional | The email address associated with the customer profile.
**Constraints**: *Maximum Length*: `254` | +| `address` | [`Address`](../../doc/models/address.md) | Optional | Represents a postal address in a country.
For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | +| `phone_number` | `str` | Optional | The phone number associated with the customer profile. The phone number must be valid
and can contain 9–16 digits, with an optional `+` prefix and country code. For more information,
see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number). | +| `reference_id` | `str` | Optional | An optional second ID used to associate the customer profile with an
entity in another system.
**Constraints**: *Maximum Length*: `100` | +| `note` | `str` | Optional | A custom note associated with the customer profile. | +| `birthday` | `str` | Optional | The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format.
For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21.
Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or
`0000` if a birth year is not specified. | +| `tax_ids` | [`Customer Tax Ids`](../../doc/models/customer-tax-ids.md) | Optional | Represents the tax ID associated with a [customer profile](../../doc/models/customer.md). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom.
For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). | + +## Example (as JSON) + +```json +{ + "given_name": "given_name4", + "family_name": "family_name4", + "company_name": "company_name8", + "nickname": "nickname8", + "email_address": "email_address0" +} +``` + diff --git a/doc/models/bulk-create-customers-request.md b/doc/models/bulk-create-customers-request.md new file mode 100644 index 00000000..ab4d20b4 --- /dev/null +++ b/doc/models/bulk-create-customers-request.md @@ -0,0 +1,61 @@ + +# Bulk Create Customers Request + +Defines the body parameters that can be included in requests to the +[BulkCreateCustomers](../../doc/api/customers.md#bulk-create-customers) endpoint. + +## Structure + +`Bulk Create Customers Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `customers` | [`Dict Str Bulk Create Customer Data`](../../doc/models/bulk-create-customer-data.md) | Required | A map of 1 to 100 individual create requests, represented by `idempotency key: { customer data }`
key-value pairs.

Each key is an [idempotency key](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
that uniquely identifies the create request. Each value contains the customer data used to create the
customer profile. | + +## Example (as JSON) + +```json +{ + "customers": { + "8bb76c4f-e35d-4c5b-90de-1194cd9179f0": { + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "administrative_district_level_1": "NY", + "country": "US", + "locality": "New York", + "postal_code": "10003" + }, + "email_address": "Amelia.Earhart@example.com", + "family_name": "Earhart", + "given_name": "Amelia", + "note": "a customer", + "phone_number": "+1-212-555-4240", + "reference_id": "YOUR_REFERENCE_ID", + "company_name": "company_name8", + "nickname": "nickname8" + }, + "d1689f23-b25d-4932-b2f0-aed00f5e2029": { + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 601", + "administrative_district_level_1": "NY", + "country": "US", + "locality": "New York", + "postal_code": "10003" + }, + "email_address": "Marie.Curie@example.com", + "family_name": "Curie", + "given_name": "Marie", + "note": "another customer", + "phone_number": "+1-212-444-4240", + "reference_id": "YOUR_REFERENCE_ID", + "company_name": "company_name8", + "nickname": "nickname8" + } + } +} +``` + diff --git a/doc/models/bulk-create-customers-response.md b/doc/models/bulk-create-customers-response.md new file mode 100644 index 00000000..03938b20 --- /dev/null +++ b/doc/models/bulk-create-customers-response.md @@ -0,0 +1,150 @@ + +# Bulk Create Customers Response + +Defines the fields included in the response body from the +[BulkCreateCustomers](../../doc/api/customers.md#bulk-create-customers) endpoint. + +## Structure + +`Bulk Create Customers Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `responses` | [`Dict Str Create Customer Response`](../../doc/models/create-customer-response.md) | Optional | A map of responses that correspond to individual create requests, represented by
key-value pairs.

Each key is the idempotency key that was provided for a create request and each value
is the corresponding response.
If the request succeeds, the value is the new customer profile.
If the request fails, the value contains any errors that occurred during the request. | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | Any top-level errors that prevented the bulk operation from running. | + +## Example (as JSON) + +```json +{ + "responses": { + "8bb76c4f-e35d-4c5b-90de-1194cd9179f4": { + "customer": { + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 600", + "administrative_district_level_1": "NY", + "country": "US", + "locality": "New York", + "postal_code": "10003" + }, + "created_at": "2024-03-23T20:21:54.859Z", + "creation_source": "THIRD_PARTY", + "email_address": "Amelia.Earhart@example.com", + "family_name": "Earhart", + "given_name": "Amelia", + "id": "8DDA5NZVBZFGAX0V3HPF81HHE0", + "note": "a customer", + "phone_number": "+1-212-555-4240", + "preferences": { + "email_unsubscribed": false + }, + "reference_id": "YOUR_REFERENCE_ID", + "updated_at": "2024-03-23T20:21:54.859Z", + "version": 0, + "cards": [ + { + "id": "id8", + "card_brand": "DISCOVER", + "last_4": "last_40", + "exp_month": 152, + "exp_year": 144 + } + ] + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + }, + "d1689f23-b25d-4932-b2f0-aed00f5e2029": { + "customer": { + "address": { + "address_line_1": "500 Electric Ave", + "address_line_2": "Suite 601", + "administrative_district_level_1": "NY", + "country": "US", + "locality": "New York", + "postal_code": "10003" + }, + "created_at": "2024-03-23T20:21:54.859Z", + "creation_source": "THIRD_PARTY", + "email_address": "Marie.Curie@example.com", + "family_name": "Curie", + "given_name": "Marie", + "id": "N18CPRVXR5214XPBBA6BZQWF3C", + "note": "another customer", + "phone_number": "+1-212-444-4240", + "preferences": { + "email_unsubscribed": false + }, + "reference_id": "YOUR_REFERENCE_ID", + "updated_at": "2024-03-23T20:21:54.859Z", + "version": 0, + "cards": [ + { + "id": "id8", + "card_brand": "DISCOVER", + "last_4": "last_40", + "exp_month": 152, + "exp_year": 144 + } + ] + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + } + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/bulk-delete-customers-request.md b/doc/models/bulk-delete-customers-request.md new file mode 100644 index 00000000..9444684f --- /dev/null +++ b/doc/models/bulk-delete-customers-request.md @@ -0,0 +1,28 @@ + +# Bulk Delete Customers Request + +Defines the body parameters that can be included in requests to the +[BulkDeleteCustomers](../../doc/api/customers.md#bulk-delete-customers) endpoint. + +## Structure + +`Bulk Delete Customers Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_ids` | `List[str]` | Required | The IDs of the [customer profiles](entity:Customer) to delete. | + +## Example (as JSON) + +```json +{ + "customer_ids": [ + "8DDA5NZVBZFGAX0V3HPF81HHE0", + "N18CPRVXR5214XPBBA6BZQWF3C", + "2GYD7WNXF7BJZW1PMGNXZ3Y8M8" + ] +} +``` + diff --git a/doc/models/bulk-delete-customers-response.md b/doc/models/bulk-delete-customers-response.md new file mode 100644 index 00000000..30b87780 --- /dev/null +++ b/doc/models/bulk-delete-customers-response.md @@ -0,0 +1,94 @@ + +# Bulk Delete Customers Response + +Defines the fields included in the response body from the +[BulkDeleteCustomers](../../doc/api/customers.md#bulk-delete-customers) endpoint. + +## Structure + +`Bulk Delete Customers Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `responses` | [`Dict Str Delete Customer Response`](../../doc/models/delete-customer-response.md) | Optional | A map of responses that correspond to individual delete requests, represented by
key-value pairs.

Each key is the customer ID that was specified for a delete request and each value
is the corresponding response.
If the request succeeds, the value is an empty object (`{ }`).
If the request fails, the value contains any errors that occurred during the request. | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | Any top-level errors that prevented the bulk operation from running. | + +## Example (as JSON) + +```json +{ + "responses": { + "2GYD7WNXF7BJZW1PMGNXZ3Y8M8": { + "errors": [ + { + "category": "INVALID_REQUEST_ERROR", + "code": "NOT_FOUND", + "detail": "Customer with ID `2GYD7WNXF7BJZW1PMGNXZ3Y8M8` not found.", + "field": "field4" + } + ] + }, + "8DDA5NZVBZFGAX0V3HPF81HHE0": { + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + }, + "N18CPRVXR5214XPBBA6BZQWF3C": { + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + } + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/bulk-retrieve-customers-request.md b/doc/models/bulk-retrieve-customers-request.md new file mode 100644 index 00000000..f0413cd8 --- /dev/null +++ b/doc/models/bulk-retrieve-customers-request.md @@ -0,0 +1,28 @@ + +# Bulk Retrieve Customers Request + +Defines the body parameters that can be included in requests to the +[BulkRetrieveCustomers](../../doc/api/customers.md#bulk-retrieve-customers) endpoint. + +## Structure + +`Bulk Retrieve Customers Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `customer_ids` | `List[str]` | Required | The IDs of the [customer profiles](entity:Customer) to retrieve. | + +## Example (as JSON) + +```json +{ + "customer_ids": [ + "8DDA5NZVBZFGAX0V3HPF81HHE0", + "N18CPRVXR5214XPBBA6BZQWF3C", + "2GYD7WNXF7BJZW1PMGNXZ3Y8M8" + ] +} +``` + diff --git a/doc/models/bulk-retrieve-customers-response.md b/doc/models/bulk-retrieve-customers-response.md new file mode 100644 index 00000000..f342dc14 --- /dev/null +++ b/doc/models/bulk-retrieve-customers-response.md @@ -0,0 +1,142 @@ + +# Bulk Retrieve Customers Response + +Defines the fields included in the response body from the +[BulkRetrieveCustomers](../../doc/api/customers.md#bulk-retrieve-customers) endpoint. + +## Structure + +`Bulk Retrieve Customers Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `responses` | [`Dict Str Retrieve Customer Response`](../../doc/models/retrieve-customer-response.md) | Optional | A map of responses that correspond to individual retrieve requests, represented by
key-value pairs.

Each key is the customer ID that was specified for a retrieve request and each value
is the corresponding response.
If the request succeeds, the value is the requested customer profile.
If the request fails, the value contains any errors that occurred during the request. | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | Any top-level errors that prevented the bulk operation from running. | + +## Example (as JSON) + +```json +{ + "responses": { + "2GYD7WNXF7BJZW1PMGNXZ3Y8M8": { + "errors": [ + { + "category": "INVALID_REQUEST_ERROR", + "code": "NOT_FOUND", + "detail": "Customer with ID `2GYD7WNXF7BJZW1PMGNXZ3Y8M8` not found.", + "field": "field4" + } + ], + "customer": { + "id": "id0", + "created_at": "created_at2", + "updated_at": "updated_at4", + "cards": [ + { + "id": "id8", + "card_brand": "DISCOVER", + "last_4": "last_40", + "exp_month": 152, + "exp_year": 144 + } + ], + "given_name": "given_name2" + } + }, + "8DDA5NZVBZFGAX0V3HPF81HHE0": { + "customer": { + "birthday": "1897-07-24", + "created_at": "2024-01-19T00:27:54.59Z", + "creation_source": "THIRD_PARTY", + "email_address": "New.Amelia.Earhart@example.com", + "family_name": "Earhart", + "given_name": "Amelia", + "id": "8DDA5NZVBZFGAX0V3HPF81HHE0", + "note": "updated customer note", + "preferences": { + "email_unsubscribed": false + }, + "updated_at": "2024-01-19T00:38:06Z", + "version": 3 + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + }, + "N18CPRVXR5214XPBBA6BZQWF3C": { + "customer": { + "created_at": "2024-01-19T00:27:54.59Z", + "creation_source": "THIRD_PARTY", + "family_name": "Curie", + "given_name": "Marie", + "id": "N18CPRVXR5214XPBBA6BZQWF3C", + "preferences": { + "email_unsubscribed": false + }, + "updated_at": "2024-01-19T00:38:06Z", + "version": 1 + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + } + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/bulk-update-customer-data.md b/doc/models/bulk-update-customer-data.md new file mode 100644 index 00000000..175fa033 --- /dev/null +++ b/doc/models/bulk-update-customer-data.md @@ -0,0 +1,39 @@ + +# Bulk Update Customer Data + +Defines the customer data provided in individual update requests for a +[BulkUpdateCustomers](../../doc/api/customers.md#bulk-update-customers) operation. + +## Structure + +`Bulk Update Customer Data` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `given_name` | `str` | Optional | The given name (that is, the first name) associated with the customer profile.
**Constraints**: *Maximum Length*: `300` | +| `family_name` | `str` | Optional | The family name (that is, the last name) associated with the customer profile.
**Constraints**: *Maximum Length*: `300` | +| `company_name` | `str` | Optional | A business name associated with the customer profile.
**Constraints**: *Maximum Length*: `500` | +| `nickname` | `str` | Optional | A nickname for the customer profile.
**Constraints**: *Maximum Length*: `100` | +| `email_address` | `str` | Optional | The email address associated with the customer profile.
**Constraints**: *Maximum Length*: `254` | +| `address` | [`Address`](../../doc/models/address.md) | Optional | Represents a postal address in a country.
For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | +| `phone_number` | `str` | Optional | The phone number associated with the customer profile. The phone number must be valid
and can contain 9–16 digits, with an optional `+` prefix and country code. For more information,
see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number). | +| `reference_id` | `str` | Optional | An optional second ID used to associate the customer profile with an
entity in another system.
**Constraints**: *Maximum Length*: `100` | +| `note` | `str` | Optional | An custom note associates with the customer profile. | +| `birthday` | `str` | Optional | The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format.
For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21.
Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or
`0000` if a birth year is not specified. | +| `tax_ids` | [`Customer Tax Ids`](../../doc/models/customer-tax-ids.md) | Optional | Represents the tax ID associated with a [customer profile](../../doc/models/customer.md). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom.
For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). | +| `version` | `long\|int` | Optional | The current version of the customer profile.

As a best practice, you should include this field to enable
[optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)
control. | + +## Example (as JSON) + +```json +{ + "given_name": "given_name4", + "family_name": "family_name4", + "company_name": "company_name8", + "nickname": "nickname8", + "email_address": "email_address0" +} +``` + diff --git a/doc/models/bulk-update-customers-request.md b/doc/models/bulk-update-customers-request.md new file mode 100644 index 00000000..12dd5511 --- /dev/null +++ b/doc/models/bulk-update-customers-request.md @@ -0,0 +1,43 @@ + +# Bulk Update Customers Request + +Defines the body parameters that can be included in requests to the +[BulkUpdateCustomers](../../doc/api/customers.md#bulk-update-customers) endpoint. + +## Structure + +`Bulk Update Customers Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `customers` | [`Dict Str Bulk Update Customer Data`](../../doc/models/bulk-update-customer-data.md) | Required | A map of 1 to 100 individual update requests, represented by `customer ID: { customer data }`
key-value pairs.

Each key is the ID of the [customer profile](entity:Customer) to update. To update a customer profile
that was created by merging existing profiles, provide the ID of the newly created profile.

Each value contains the updated customer data. Only new or changed fields are required. To add or
update a field, specify the new value. To remove a field, specify `null`. | + +## Example (as JSON) + +```json +{ + "customers": { + "8DDA5NZVBZFGAX0V3HPF81HHE0": { + "email_address": "New.Amelia.Earhart@example.com", + "note": "updated customer note", + "phone_number": null, + "version": 2, + "given_name": "given_name4", + "family_name": "family_name6", + "company_name": "company_name8", + "nickname": "nickname8" + }, + "N18CPRVXR5214XPBBA6BZQWF3C": { + "family_name": "Curie", + "given_name": "Marie", + "version": 0, + "company_name": "company_name8", + "nickname": "nickname8", + "email_address": "email_address0" + } + } +} +``` + diff --git a/doc/models/bulk-update-customers-response.md b/doc/models/bulk-update-customers-response.md new file mode 100644 index 00000000..f43940ca --- /dev/null +++ b/doc/models/bulk-update-customers-response.md @@ -0,0 +1,135 @@ + +# Bulk Update Customers Response + +Defines the fields included in the response body from the +[BulkUpdateCustomers](../../doc/api/customers.md#bulk-update-customers) endpoint. + +## Structure + +`Bulk Update Customers Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `responses` | [`Dict Str Update Customer Response`](../../doc/models/update-customer-response.md) | Optional | A map of responses that correspond to individual update requests, represented by
key-value pairs.

Each key is the customer ID that was specified for an update request and each value
is the corresponding response.
If the request succeeds, the value is the updated customer profile.
If the request fails, the value contains any errors that occurred during the request. | +| `errors` | [`List Error`](../../doc/models/error.md) | Optional | Any top-level errors that prevented the bulk operation from running. | + +## Example (as JSON) + +```json +{ + "responses": { + "8DDA5NZVBZFGAX0V3HPF81HHE0": { + "customer": { + "birthday": "1897-07-24", + "created_at": "2024-01-19T00:27:54.59Z", + "creation_source": "THIRD_PARTY", + "email_address": "New.Amelia.Earhart@example.com", + "family_name": "Earhart", + "given_name": "Amelia", + "id": "8DDA5NZVBZFGAX0V3HPF81HHE0", + "note": "updated customer note", + "preferences": { + "email_unsubscribed": false + }, + "updated_at": "2024-01-19T00:38:06Z", + "version": 3, + "cards": [ + { + "id": "id8", + "card_brand": "DISCOVER", + "last_4": "last_40", + "exp_month": 152, + "exp_year": 144 + } + ] + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + }, + "N18CPRVXR5214XPBBA6BZQWF3C": { + "customer": { + "created_at": "2024-01-19T00:27:54.59Z", + "creation_source": "THIRD_PARTY", + "family_name": "Curie", + "given_name": "Marie", + "id": "N18CPRVXR5214XPBBA6BZQWF3C", + "preferences": { + "email_unsubscribed": false + }, + "updated_at": "2024-01-19T00:38:06Z", + "version": 1, + "cards": [ + { + "id": "id8", + "card_brand": "DISCOVER", + "last_4": "last_40", + "exp_month": 152, + "exp_year": 144 + } + ] + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] + } + }, + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/catalog-item-modifier-list-info.md b/doc/models/catalog-item-modifier-list-info.md index 79830aee..ce4f44ae 100644 --- a/doc/models/catalog-item-modifier-list-info.md +++ b/doc/models/catalog-item-modifier-list-info.md @@ -1,7 +1,8 @@ # Catalog Item Modifier List Info -Options to control the properties of a `CatalogModifierList` applied to a `CatalogItem` instance. +References a text-based modifier or a list of non text-based modifiers applied to a `CatalogItem` instance +and specifies supported behaviors of the application. ## Structure @@ -16,6 +17,7 @@ Options to control the properties of a `CatalogModifierList` applied to a `Catal | `min_selected_modifiers` | `int` | Optional | If 0 or larger, the smallest number of `CatalogModifier`s that must be selected from this `CatalogModifierList`. | | `max_selected_modifiers` | `int` | Optional | If 0 or larger, the largest number of `CatalogModifier`s that can be selected from this `CatalogModifierList`. | | `enabled` | `bool` | Optional | If `true`, enable this `CatalogModifierList`. The default value is `true`. | +| `ordinal` | `int` | Optional | The position of this `CatalogItemModifierListInfo` object within the `modifier_list_info` list applied
to a `CatalogItem` instance. | ## Example (as JSON) @@ -34,7 +36,8 @@ Options to control the properties of a `CatalogModifierList` applied to a `Catal ], "min_selected_modifiers": 170, "max_selected_modifiers": 66, - "enabled": false + "enabled": false, + "ordinal": 204 } ``` diff --git a/doc/models/catalog-modifier-list-modifier-type.md b/doc/models/catalog-modifier-list-modifier-type.md new file mode 100644 index 00000000..ab4f6bb1 --- /dev/null +++ b/doc/models/catalog-modifier-list-modifier-type.md @@ -0,0 +1,16 @@ + +# Catalog Modifier List Modifier Type + +Defines the type of `CatalogModifierList`. + +## Enumeration + +`Catalog Modifier List Modifier Type` + +## Fields + +| Name | Description | +| --- | --- | +| `LIST` | The `CatalogModifierList` instance is a non-empty list of non text-based modifiers. | +| `TEXT` | The `CatalogModifierList` instance is a single text-based modifier. | + diff --git a/doc/models/catalog-modifier-list.md b/doc/models/catalog-modifier-list.md index 974bac65..add7dcd3 100644 --- a/doc/models/catalog-modifier-list.md +++ b/doc/models/catalog-modifier-list.md @@ -1,12 +1,18 @@ # Catalog Modifier List -A list of modifiers applicable to items at the time of sale. +For a text-based modifier, this encapsulates the modifier's text when its `modifier_type` is `TEXT`. +For example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied +text string to be selected for the T-shirt at the time of sale. +For non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items +at the time of sale. Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type. For example, a "Condiments" modifier list applicable to a "Hot Dog" item may contain "Ketchup", "Mustard", and "Relish" modifiers. -Use the `selection_type` field to specify whether or not multiple selections from -the modifier list are allowed. + +A non text-based modifier can be applied to the modified item once or multiple times, if the `selection_type` field +is set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a text-based modifier can be applied to the item +only once and the `selection_type` field is always set to `SINGLE`. ## Structure @@ -16,11 +22,15 @@ the modifier list are allowed. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `name` | `str` | Optional | The name for the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
**Constraints**: *Maximum Length*: `255` | -| `ordinal` | `int` | Optional | Determines where this modifier list appears in a list of `CatalogModifierList` values. | +| `name` | `str` | Optional | The name of the `CatalogModifierList` instance. This is a searchable attribute for use in applicable query filters, and its value length is of
Unicode code points.
**Constraints**: *Maximum Length*: `255` | +| `ordinal` | `int` | Optional | The position of this `CatalogModifierList` within a list of `CatalogModifierList` instances. | | `selection_type` | [`str (Catalog Modifier List Selection Type)`](../../doc/models/catalog-modifier-list-selection-type.md) | Optional | Indicates whether a CatalogModifierList supports multiple selections. | -| `modifiers` | [`List Catalog Object`](../../doc/models/catalog-object.md) | Optional | The options included in the `CatalogModifierList`.
You must include at least one `CatalogModifier`.
Each CatalogObject must have type `MODIFIER` and contain
`CatalogModifier` data. | -| `image_ids` | `List[str]` | Optional | The IDs of images associated with this `CatalogModifierList` instance.
Currently these images are not displayed by Square, but are free to be displayed in 3rd party applications. | +| `modifiers` | [`List Catalog Object`](../../doc/models/catalog-object.md) | Optional | A non-empty list of `CatalogModifier` objects to be included in the `CatalogModifierList`,
for non text-based modifiers when the `modifier_type` attribute is `LIST`. Each element of this list
is a `CatalogObject` instance of the `MODIFIER` type, containing the following attributes:

```
{
"id": "{{catalog_modifier_id}}",
"type": "MODIFIER",
"modifier_data": {{a CatalogModifier instance>}}
}
``` | +| `image_ids` | `List[str]` | Optional | The IDs of images associated with this `CatalogModifierList` instance.
Currently these images are not displayed on Square products, but may be displayed in 3rd-party applications. | +| `modifier_type` | [`str (Catalog Modifier List Modifier Type)`](../../doc/models/catalog-modifier-list-modifier-type.md) | Optional | Defines the type of `CatalogModifierList`. | +| `max_length` | `int` | Optional | The maximum length, in Unicode points, of the text string of the text-based modifier as represented by
this `CatalogModifierList` object with the `modifier_type` set to `TEXT`. | +| `text_required` | `bool` | Optional | Whether the text string must be a non-empty string (`true`) or not (`false`) for a text-based modifier
as represented by this `CatalogModifierList` object with the `modifier_type` set to `TEXT`. | +| `internal_name` | `str` | Optional | A note for internal use by the business.

For example, for a text-based modifier applied to a T-shirt item, if the buyer-supplied text of "Hello, Kitty!"
is to be printed on the T-shirt, this `internal_name` attribute can be "Use italic face" as
an instruction for the business to follow.

For non text-based modifiers, this `internal_name` attribute can be
used to include SKUs, internal codes, or supplemental descriptions for internal use.
**Constraints**: *Maximum Length*: `512` | ## Example (as JSON) diff --git a/doc/models/catalog-object.md b/doc/models/catalog-object.md index 5ffc3541..9aab7d3e 100644 --- a/doc/models/catalog-object.md +++ b/doc/models/catalog-object.md @@ -35,7 +35,7 @@ For a more detailed discussion of the Catalog data model, please see the | `item_variation_data` | [`Catalog Item Variation`](../../doc/models/catalog-item-variation.md) | Optional | An item variation, representing a product for sale, in the Catalog object model. Each [item](../../doc/models/catalog-item.md) must have at least one
item variation and can have at most 250 item variations.

An item variation can be sellable, stockable, or both if it has a unit of measure for its count for the sold number of the variation, the stocked
number of the variation, or both. For example, when a variation representing wine is stocked and sold by the bottle, the variation is both
stockable and sellable. But when a variation of the wine is sold by the glass, the sold units cannot be used as a measure of the stocked units. This by-the-glass
variation is sellable, but not stockable. To accurately keep track of the wine's inventory count at any time, the sellable count must be
converted to stockable count. Typically, the seller defines this unit conversion. For example, 1 bottle equals 5 glasses. The Square API exposes
the `stockable_conversion` property on the variation to specify the conversion. Thus, when two glasses of the wine are sold, the sellable count
decreases by 2, and the stockable count automatically decreases by 0.4 bottle according to the conversion. | | `tax_data` | [`Catalog Tax`](../../doc/models/catalog-tax.md) | Optional | A tax applicable to an item. | | `discount_data` | [`Catalog Discount`](../../doc/models/catalog-discount.md) | Optional | A discount applicable to items. | -| `modifier_list_data` | [`Catalog Modifier List`](../../doc/models/catalog-modifier-list.md) | Optional | A list of modifiers applicable to items at the time of sale.

For example, a "Condiments" modifier list applicable to a "Hot Dog" item
may contain "Ketchup", "Mustard", and "Relish" modifiers.
Use the `selection_type` field to specify whether or not multiple selections from
the modifier list are allowed. | +| `modifier_list_data` | [`Catalog Modifier List`](../../doc/models/catalog-modifier-list.md) | Optional | For a text-based modifier, this encapsulates the modifier's text when its `modifier_type` is `TEXT`.
For example, to sell T-shirts with custom prints, a text-based modifier can be used to capture the buyer-supplied
text string to be selected for the T-shirt at the time of sale.

For non text-based modifiers, this encapsulates a non-empty list of modifiers applicable to items
at the time of sale. Each element of the modifier list is a `CatalogObject` instance of the `MODIFIER` type.
For example, a "Condiments" modifier list applicable to a "Hot Dog" item
may contain "Ketchup", "Mustard", and "Relish" modifiers.

A non text-based modifier can be applied to the modified item once or multiple times, if the `selection_type` field
is set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a text-based modifier can be applied to the item
only once and the `selection_type` field is always set to `SINGLE`. | | `modifier_data` | [`Catalog Modifier`](../../doc/models/catalog-modifier.md) | Optional | A modifier applicable to items at the time of sale. An example of a modifier is a Cheese add-on to a Burger item. | | `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. | diff --git a/doc/models/create-customer-response.md b/doc/models/create-customer-response.md index 1bce6ff9..2da0a4b7 100644 --- a/doc/models/create-customer-response.md +++ b/doc/models/create-customer-response.md @@ -2,7 +2,8 @@ # Create Customer Response Defines the fields that are included in the response body of -a request to the `CreateCustomer` endpoint. +a request to the [CreateCustomer](../../doc/api/customers.md#create-customer) or +[BulkCreateCustomers](../../doc/api/customers.md#bulk-create-customers) endpoint. Either `errors` or `customer` is present in a given response (never both). diff --git a/doc/models/list-payment-links-request.md b/doc/models/list-payment-links-request.md index 8531796c..ce636a0d 100644 --- a/doc/models/list-payment-links-request.md +++ b/doc/models/list-payment-links-request.md @@ -9,7 +9,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `cursor` | `str` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If a cursor is not provided, the endpoint returns the first page of the results.
For more information, see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). | +| `cursor` | `str` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If a cursor is not provided, the endpoint returns the first page of the results.
For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `limit` | `int` | Optional | A limit on the number of results to return per page. The limit is advisory and
the implementation might return more or less results. If the supplied limit is negative, zero, or
greater than the maximum limit of 1000, it is ignored.

Default value: `100` | ## Example (as JSON) diff --git a/doc/models/list-payment-links-response.md b/doc/models/list-payment-links-response.md index d640a300..81c43701 100644 --- a/doc/models/list-payment-links-response.md +++ b/doc/models/list-payment-links-response.md @@ -11,7 +11,7 @@ | --- | --- | --- | --- | | `errors` | [`List Error`](../../doc/models/error.md) | Optional | Errors that occurred during the request. | | `payment_links` | [`List Payment Link`](../../doc/models/payment-link.md) | Optional | The list of payment links. | -| `cursor` | `str` | Optional | When a response is truncated, it includes a cursor that you can use in a subsequent request
to retrieve the next set of gift cards. If a cursor is not present, this is the final response.
For more information, see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). | +| `cursor` | `str` | Optional | When a response is truncated, it includes a cursor that you can use in a subsequent request
to retrieve the next set of gift cards. If a cursor is not present, this is the final response.
For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | ## Example (as JSON) diff --git a/doc/models/order-line-item-tax.md b/doc/models/order-line-item-tax.md index c1773cbd..629bb974 100644 --- a/doc/models/order-line-item-tax.md +++ b/doc/models/order-line-item-tax.md @@ -20,7 +20,7 @@ contributes to the order subtotal. | `catalog_version` | `long\|int` | Optional | The version of the catalog object that this tax references. | | `name` | `str` | Optional | The tax's name.
**Constraints**: *Maximum Length*: `255` | | `type` | [`str (Order Line Item Tax Type)`](../../doc/models/order-line-item-tax-type.md) | Optional | Indicates how the tax is applied to the associated line item or order. | -| `percentage` | `str` | Optional | The percentage of the tax, as a string representation of a decimal
number. For example, a value of `"7.25"` corresponds to a percentage of
7.25%.
**Constraints**: *Maximum Length*: `10` | +| `percentage` | `str` | Optional | The percentage of the tax, as a string representation of a decimal
number. For example, a value of `"7.25"` corresponds to a percentage of
7.25%.

Either `percentage` or `amount_money` should be set, but not both.
**Constraints**: *Maximum Length*: `10` | | `metadata` | `Dict[str, str]` | Optional | Application-defined data attached to this tax. 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). | | `applied_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. | | `scope` | [`str (Order Line Item Tax Scope)`](../../doc/models/order-line-item-tax-scope.md) | Optional | Indicates whether this is a line-item or order-level tax. | diff --git a/doc/models/payment-balance-activity-fee-detail.md b/doc/models/payment-balance-activity-fee-detail.md index f972595d..603315ec 100644 --- a/doc/models/payment-balance-activity-fee-detail.md +++ b/doc/models/payment-balance-activity-fee-detail.md @@ -9,7 +9,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `payment_id` | `str` | Optional | The ID of the payment associated with this activity. | +| `payment_id` | `str` | Optional | The ID of the payment associated with this activity
This will only be populated when a principal LedgerEntryToken is also populated.
If the fee is independent (there is no principal LedgerEntryToken) then this will likely not
be populated. | ## Example (as JSON) diff --git a/doc/models/payment-refund.md b/doc/models/payment-refund.md index fd134900..a41bacca 100644 --- a/doc/models/payment-refund.md +++ b/doc/models/payment-refund.md @@ -16,7 +16,7 @@ the original payment and the amount of money refunded. | `status` | `str` | Optional | The refund's status:

- `PENDING` - Awaiting approval.
- `COMPLETED` - Successfully completed.
- `REJECTED` - The refund was rejected.
- `FAILED` - An error occurred.
**Constraints**: *Maximum Length*: `50` | | `location_id` | `str` | Optional | The location ID associated with the payment this refund is attached to.
**Constraints**: *Maximum Length*: `50` | | `unlinked` | `bool` | Optional | Flag indicating whether or not the refund is linked to an existing payment in Square. | -| `destination_type` | `str` | Optional | The destination type for this refund.

Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `CASH`, and
`EXTERNAL`.
**Constraints**: *Maximum Length*: `50` | +| `destination_type` | `str` | Optional | The destination type for this refund.

Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `CASH`,
`EXTERNAL`, and `SQUARE_ACCOUNT`.
**Constraints**: *Maximum Length*: `50` | | `destination_details` | [`Destination Details`](../../doc/models/destination-details.md) | Optional | Details about a refund's destination. | | `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. | | `app_fee_money` | [`Money`](../../doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | diff --git a/doc/models/payout-entry.md b/doc/models/payout-entry.md index 52cf5eaa..20bbd7ad 100644 --- a/doc/models/payout-entry.md +++ b/doc/models/payout-entry.md @@ -49,7 +49,7 @@ The total amount of the payout will equal the sum of the payout entries for a ba "id": "id8", "payout_id": "payout_id4", "effective_at": "effective_at8", - "type": "DEPOSIT_FEE", + "type": "SQUARE_CAPITAL_REVERSED_PAYMENT", "gross_amount_money": { "amount": 186, "currency": "BWP" diff --git a/doc/models/retrieve-merchant-settings-response.md b/doc/models/retrieve-merchant-settings-response.md index 1825c70b..c7070ca1 100644 --- a/doc/models/retrieve-merchant-settings-response.md +++ b/doc/models/retrieve-merchant-settings-response.md @@ -20,7 +20,6 @@ "merchant_id": "MERCHANT_ID", "payment_methods": { "afterpay_clearpay": { - "available": true, "enabled": true, "item_eligibility_range": { "max": { @@ -44,15 +43,12 @@ } }, "apple_pay": { - "available": true, "enabled": true }, "cash_app_pay": { - "available": true, "enabled": true }, "google_pay": { - "available": true, "enabled": true }, "cash_app": { diff --git a/doc/models/search-orders-response.md b/doc/models/search-orders-response.md index eb6f896f..60877606 100644 --- a/doc/models/search-orders-response.md +++ b/doc/models/search-orders-response.md @@ -14,7 +14,7 @@ Either the `order_entries` or `orders` field is set, depending on whether | --- | --- | --- | --- | | `order_entries` | [`List Order Entry`](../../doc/models/order-entry.md) | Optional | A list of [OrderEntries](entity:OrderEntry) that fit the query
conditions. The list is populated only if `return_entries` is set to `true` in the request. | | `orders` | [`List Order`](../../doc/models/order.md) | Optional | A list of
[Order](entity:Order) objects that match the query conditions. The list is populated only if
`return_entries` is set to `false` in the request. | -| `cursor` | `str` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.
For more information, see [Pagination](https://developer.squareup.com/docs/basics/build-basics/common-api-patterns/pagination). | +| `cursor` | `str` | Optional | The pagination cursor to be used in a subsequent request. If unset,
this is the final response.
For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `errors` | [`List Error`](../../doc/models/error.md) | Optional | [Errors](entity:Error) encountered during the search. | ## Example (as JSON) diff --git a/doc/models/update-customer-request.md b/doc/models/update-customer-request.md index d7d9ac33..3eec2843 100644 --- a/doc/models/update-customer-request.md +++ b/doc/models/update-customer-request.md @@ -31,7 +31,7 @@ Defines the body parameters that can be included in a request to the { "email_address": "New.Amelia.Earhart@example.com", "note": "updated customer note", - "phone_number": "", + "phone_number": null, "version": 2, "given_name": "given_name0", "family_name": "family_name8", diff --git a/doc/models/update-customer-response.md b/doc/models/update-customer-response.md index a8414603..6894d182 100644 --- a/doc/models/update-customer-response.md +++ b/doc/models/update-customer-response.md @@ -2,7 +2,8 @@ # Update Customer Response Defines the fields that are included in the response body of -a request to the `UpdateCustomer` endpoint. +a request to the [UpdateCustomer](../../doc/api/customers.md#update-customer) or +[BulkUpdateCustomers](../../doc/api/customers.md#bulk-update-customers) endpoint. Either `errors` or `customer` is present in a given response (never both). diff --git a/doc/models/update-merchant-settings-response.md b/doc/models/update-merchant-settings-response.md index b8419e3a..132c2a2f 100644 --- a/doc/models/update-merchant-settings-response.md +++ b/doc/models/update-merchant-settings-response.md @@ -20,7 +20,6 @@ "merchant_id": "MERCHANT_ID", "payment_methods": { "afterpay_clearpay": { - "available": true, "enabled": true, "item_eligibility_range": { "max": { @@ -44,15 +43,12 @@ } }, "apple_pay": { - "available": true, "enabled": false }, "cash_app_pay": { - "available": true, "enabled": true }, "google_pay": { - "available": true, "enabled": true }, "cash_app": { diff --git a/doc/models/v1-create-refund-request-type.md b/doc/models/v1-create-refund-request-type.md deleted file mode 100644 index d2a0db0d..00000000 --- a/doc/models/v1-create-refund-request-type.md +++ /dev/null @@ -1,14 +0,0 @@ - -# V1 Create Refund Request Type - -## Enumeration - -`V1 Create Refund Request Type` - -## Fields - -| Name | -| --- | -| `FULL` | -| `PARTIAL` | - diff --git a/doc/models/v1-create-refund-request.md b/doc/models/v1-create-refund-request.md deleted file mode 100644 index 5a714f11..00000000 --- a/doc/models/v1-create-refund-request.md +++ /dev/null @@ -1,34 +0,0 @@ - -# V1 Create Refund Request - -V1CreateRefundRequest - -## Structure - -`V1 Create Refund Request` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `payment_id` | `str` | Required | The ID of the payment to refund. If you are creating a `PARTIAL`
refund for a split tender payment, instead provide the id of the
particular tender you want to refund. | -| `type` | [`str (V1 Create Refund Request Type)`](../../doc/models/v1-create-refund-request-type.md) | Required | - | -| `reason` | `str` | Required | The reason for the refund. | -| `refunded_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `request_idempotence_key` | `str` | Optional | An optional key to ensure idempotence if you issue the same PARTIAL refund request more than once. | - -## Example (as JSON) - -```json -{ - "payment_id": "payment_id2", - "type": "FULL", - "reason": "reason2", - "refunded_money": { - "amount": 214, - "currency_code": "SRD" - }, - "request_idempotence_key": "request_idempotence_key6" -} -``` - diff --git a/doc/models/v1-list-payments-request.md b/doc/models/v1-list-payments-request.md deleted file mode 100644 index 8e0c286c..00000000 --- a/doc/models/v1-list-payments-request.md +++ /dev/null @@ -1,30 +0,0 @@ - -# V1 List Payments Request - -## Structure - -`V1 List Payments 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_time` | `str` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `str` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `int` | Optional | The maximum number of payments to return in a single response. This value cannot exceed 200. | -| `batch_token` | `str` | Optional | A pagination cursor to retrieve the next set of results for your
original query to the endpoint. | -| `include_partial` | `bool` | Optional | Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. | - -## Example (as JSON) - -```json -{ - "order": "DESC", - "begin_time": "begin_time8", - "end_time": "end_time2", - "limit": 104, - "batch_token": "batch_token8" -} -``` - diff --git a/doc/models/v1-list-payments-response.md b/doc/models/v1-list-payments-response.md deleted file mode 100644 index c540838a..00000000 --- a/doc/models/v1-list-payments-response.md +++ /dev/null @@ -1,42 +0,0 @@ - -# V1 List Payments Response - -## Structure - -`V1 List Payments Response` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`List V1 Payment`](../../doc/models/v1-payment.md) | Optional | - | - -## Example (as JSON) - -```json -{ - "items": [ - { - "id": "id8", - "merchant_id": "merchant_id8", - "created_at": "created_at6", - "creator_id": "creator_id8", - "device": { - "id": "id6", - "name": "name6" - } - }, - { - "id": "id8", - "merchant_id": "merchant_id8", - "created_at": "created_at6", - "creator_id": "creator_id8", - "device": { - "id": "id6", - "name": "name6" - } - } - ] -} -``` - diff --git a/doc/models/v1-list-refunds-request.md b/doc/models/v1-list-refunds-request.md deleted file mode 100644 index 571b6926..00000000 --- a/doc/models/v1-list-refunds-request.md +++ /dev/null @@ -1,29 +0,0 @@ - -# V1 List Refunds Request - -## Structure - -`V1 List Refunds 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_time` | `str` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `str` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `int` | Optional | The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. | -| `batch_token` | `str` | 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_time": "begin_time0", - "end_time": "end_time4", - "limit": 66, - "batch_token": "batch_token0" -} -``` - diff --git a/doc/models/v1-list-refunds-response.md b/doc/models/v1-list-refunds-response.md deleted file mode 100644 index a44d5b3e..00000000 --- a/doc/models/v1-list-refunds-response.md +++ /dev/null @@ -1,70 +0,0 @@ - -# V1 List Refunds Response - -## Structure - -`V1 List Refunds Response` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`List V1 Refund`](../../doc/models/v1-refund.md) | Optional | - | - -## Example (as JSON) - -```json -{ - "items": [ - { - "type": "FULL", - "reason": "reason6", - "refunded_money": { - "amount": 214, - "currency_code": "SRD" - }, - "refunded_processing_fee_money": { - "amount": 0, - "currency_code": "BGN" - }, - "refunded_tax_money": { - "amount": 148, - "currency_code": "SRD" - } - }, - { - "type": "FULL", - "reason": "reason6", - "refunded_money": { - "amount": 214, - "currency_code": "SRD" - }, - "refunded_processing_fee_money": { - "amount": 0, - "currency_code": "BGN" - }, - "refunded_tax_money": { - "amount": 148, - "currency_code": "SRD" - } - }, - { - "type": "FULL", - "reason": "reason6", - "refunded_money": { - "amount": 214, - "currency_code": "SRD" - }, - "refunded_processing_fee_money": { - "amount": 0, - "currency_code": "BGN" - }, - "refunded_tax_money": { - "amount": 148, - "currency_code": "SRD" - } - } - ] -} -``` - diff --git a/doc/models/v1-list-settlements-request-status.md b/doc/models/v1-list-settlements-request-status.md deleted file mode 100644 index f3045e5b..00000000 --- a/doc/models/v1-list-settlements-request-status.md +++ /dev/null @@ -1,14 +0,0 @@ - -# V1 List Settlements Request Status - -## Enumeration - -`V1 List Settlements Request Status` - -## Fields - -| Name | -| --- | -| `SENT` | -| `FAILED` | - diff --git a/doc/models/v1-list-settlements-request.md b/doc/models/v1-list-settlements-request.md deleted file mode 100644 index 660052a8..00000000 --- a/doc/models/v1-list-settlements-request.md +++ /dev/null @@ -1,30 +0,0 @@ - -# V1 List Settlements Request - -## Structure - -`V1 List Settlements 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_time` | `str` | Optional | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | -| `end_time` | `str` | Optional | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | -| `limit` | `int` | Optional | The maximum number of settlements to return in a single response. This value cannot exceed 200. | -| `status` | [`str (V1 List Settlements Request Status)`](../../doc/models/v1-list-settlements-request-status.md) | Optional | - | -| `batch_token` | `str` | 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_time": "begin_time8", - "end_time": "end_time2", - "limit": 226, - "status": "SENT" -} -``` - diff --git a/doc/models/v1-list-settlements-response.md b/doc/models/v1-list-settlements-response.md deleted file mode 100644 index c3c66c8b..00000000 --- a/doc/models/v1-list-settlements-response.md +++ /dev/null @@ -1,52 +0,0 @@ - -# V1 List Settlements Response - -## Structure - -`V1 List Settlements Response` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `items` | [`List V1 Settlement`](../../doc/models/v1-settlement.md) | Optional | - | - -## Example (as JSON) - -```json -{ - "items": [ - { - "id": "id8", - "status": "FAILED", - "total_money": { - "amount": 250, - "currency_code": "KZT" - }, - "initiated_at": "initiated_at0", - "bank_account_id": "bank_account_id8" - }, - { - "id": "id8", - "status": "FAILED", - "total_money": { - "amount": 250, - "currency_code": "KZT" - }, - "initiated_at": "initiated_at0", - "bank_account_id": "bank_account_id8" - }, - { - "id": "id8", - "status": "FAILED", - "total_money": { - "amount": 250, - "currency_code": "KZT" - }, - "initiated_at": "initiated_at0", - "bank_account_id": "bank_account_id8" - } - ] -} -``` - diff --git a/doc/models/v1-payment-discount.md b/doc/models/v1-payment-discount.md deleted file mode 100644 index 0cbd096a..00000000 --- a/doc/models/v1-payment-discount.md +++ /dev/null @@ -1,30 +0,0 @@ - -# V1 Payment Discount - -V1PaymentDiscount - -## Structure - -`V1 Payment Discount` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `str` | Optional | The discount's name. | -| `applied_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `discount_id` | `str` | Optional | The ID of the applied discount, if available. Discounts applied in older versions of Square Register might not have an ID. | - -## Example (as JSON) - -```json -{ - "name": "name4", - "applied_money": { - "amount": 196, - "currency_code": "IQD" - }, - "discount_id": "discount_id2" -} -``` - diff --git a/doc/models/v1-payment-item-detail.md b/doc/models/v1-payment-item-detail.md deleted file mode 100644 index 0bcda7a9..00000000 --- a/doc/models/v1-payment-item-detail.md +++ /dev/null @@ -1,29 +0,0 @@ - -# V1 Payment Item Detail - -V1PaymentItemDetail - -## Structure - -`V1 Payment Item Detail` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `category_name` | `str` | Optional | The name of the item's merchant-defined category, if any. | -| `sku` | `str` | Optional | The item's merchant-defined SKU, if any. | -| `item_id` | `str` | Optional | The unique ID of the item purchased, if any. | -| `item_variation_id` | `str` | Optional | The unique ID of the item variation purchased, if any. | - -## Example (as JSON) - -```json -{ - "category_name": "category_name4", - "sku": "sku0", - "item_id": "item_id4", - "item_variation_id": "item_variation_id8" -} -``` - diff --git a/doc/models/v1-payment-itemization-itemization-type.md b/doc/models/v1-payment-itemization-itemization-type.md deleted file mode 100644 index 940e0da9..00000000 --- a/doc/models/v1-payment-itemization-itemization-type.md +++ /dev/null @@ -1,18 +0,0 @@ - -# V1 Payment Itemization Itemization Type - -## Enumeration - -`V1 Payment Itemization Itemization Type` - -## Fields - -| Name | -| --- | -| `ITEM` | -| `CUSTOM_AMOUNT` | -| `GIFT_CARD_ACTIVATION` | -| `GIFT_CARD_RELOAD` | -| `GIFT_CARD_UNKNOWN` | -| `OTHER` | - diff --git a/doc/models/v1-payment-itemization.md b/doc/models/v1-payment-itemization.md deleted file mode 100644 index 658d5d7d..00000000 --- a/doc/models/v1-payment-itemization.md +++ /dev/null @@ -1,60 +0,0 @@ - -# V1 Payment Itemization - -Payment include an`itemizations` field that lists the items purchased, -along with associated fees, modifiers, and discounts. Each itemization has an -`itemization_type` field that indicates which of the following the itemization -represents: - - -*Note**: itemization information included in a `Payment` object reflects -details collected **at the time of the payment**. Details such as the name or -price of items might have changed since the payment was processed. - -## Structure - -`V1 Payment Itemization` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `str` | Optional | The item's name. | -| `quantity` | `float` | Optional | The quantity of the item purchased. This can be a decimal value. | -| `itemization_type` | [`str (V1 Payment Itemization Itemization Type)`](../../doc/models/v1-payment-itemization-itemization-type.md) | Optional | - | -| `item_detail` | [`V1 Payment Item Detail`](../../doc/models/v1-payment-item-detail.md) | Optional | V1PaymentItemDetail | -| `notes` | `str` | Optional | Notes entered by the merchant about the item at the time of payment, if any. | -| `item_variation_name` | `str` | Optional | The name of the item variation purchased, if any. | -| `total_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `single_quantity_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `gross_sales_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `discount_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `net_sales_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `taxes` | [`List V1 Payment Tax`](../../doc/models/v1-payment-tax.md) | Optional | All taxes applied to this itemization. | -| `discounts` | [`List V1 Payment Discount`](../../doc/models/v1-payment-discount.md) | Optional | All discounts applied to this itemization. | -| `modifiers` | [`List V1 Payment Modifier`](../../doc/models/v1-payment-modifier.md) | Optional | All modifier options applied to this itemization. | - -## Example (as JSON) - -```json -{ - "name": "name4", - "quantity": 253.5, - "itemization_type": "GIFT_CARD_UNKNOWN", - "item_detail": { - "category_name": "category_name0", - "sku": "sku6", - "item_id": "item_id2", - "item_variation_id": "item_variation_id2" - }, - "notes": "notes4" -} -``` - diff --git a/doc/models/v1-payment-modifier.md b/doc/models/v1-payment-modifier.md deleted file mode 100644 index 6a60bfc9..00000000 --- a/doc/models/v1-payment-modifier.md +++ /dev/null @@ -1,30 +0,0 @@ - -# V1 Payment Modifier - -V1PaymentModifier - -## Structure - -`V1 Payment Modifier` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `str` | Optional | The modifier option's name. | -| `applied_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `modifier_option_id` | `str` | Optional | The ID of the applied modifier option, if available. Modifier options applied in older versions of Square Register might not have an ID. | - -## Example (as JSON) - -```json -{ - "name": "name0", - "applied_money": { - "amount": 196, - "currency_code": "IQD" - }, - "modifier_option_id": "modifier_option_id6" -} -``` - diff --git a/doc/models/v1-payment-surcharge-type.md b/doc/models/v1-payment-surcharge-type.md deleted file mode 100644 index da3d97fd..00000000 --- a/doc/models/v1-payment-surcharge-type.md +++ /dev/null @@ -1,15 +0,0 @@ - -# V1 Payment Surcharge Type - -## Enumeration - -`V1 Payment Surcharge Type` - -## Fields - -| Name | -| --- | -| `UNKNOWN` | -| `AUTO_GRATUITY` | -| `CUSTOM` | - diff --git a/doc/models/v1-payment-surcharge.md b/doc/models/v1-payment-surcharge.md deleted file mode 100644 index d9184324..00000000 --- a/doc/models/v1-payment-surcharge.md +++ /dev/null @@ -1,40 +0,0 @@ - -# V1 Payment Surcharge - -V1PaymentSurcharge - -## Structure - -`V1 Payment Surcharge` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `name` | `str` | Optional | The name of the surcharge. | -| `applied_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `rate` | `str` | Optional | The amount of the surcharge as a percentage. The percentage is provided as a string representing the decimal equivalent of the percentage. For example, "0.7" corresponds to a 7% surcharge. Exactly one of rate or amount_money should be set. | -| `amount_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `type` | [`str (V1 Payment Surcharge Type)`](../../doc/models/v1-payment-surcharge-type.md) | Optional | - | -| `taxable` | `bool` | Optional | Indicates whether the surcharge is taxable. | -| `taxes` | [`List V1 Payment Tax`](../../doc/models/v1-payment-tax.md) | Optional | The list of taxes that should be applied to the surcharge. | -| `surcharge_id` | `str` | Optional | A Square-issued unique identifier associated with the surcharge. | - -## Example (as JSON) - -```json -{ - "name": "name6", - "applied_money": { - "amount": 196, - "currency_code": "IQD" - }, - "rate": "rate4", - "amount_money": { - "amount": 186, - "currency_code": "UZS" - }, - "type": "AUTO_GRATUITY" -} -``` - diff --git a/doc/models/v1-payment-tax-inclusion-type.md b/doc/models/v1-payment-tax-inclusion-type.md deleted file mode 100644 index 9c8c3c79..00000000 --- a/doc/models/v1-payment-tax-inclusion-type.md +++ /dev/null @@ -1,14 +0,0 @@ - -# V1 Payment Tax Inclusion Type - -## Enumeration - -`V1 Payment Tax Inclusion Type` - -## Fields - -| Name | -| --- | -| `ADDITIVE` | -| `INCLUSIVE` | - diff --git a/doc/models/v1-payment-tax.md b/doc/models/v1-payment-tax.md deleted file mode 100644 index 46f79454..00000000 --- a/doc/models/v1-payment-tax.md +++ /dev/null @@ -1,42 +0,0 @@ - -# V1 Payment Tax - -V1PaymentTax - -## Structure - -`V1 Payment Tax` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `errors` | [`List Error`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `name` | `str` | Optional | The merchant-defined name of the tax. | -| `applied_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `rate` | `str` | Optional | The rate of the tax, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%. | -| `inclusion_type` | [`str (V1 Payment Tax Inclusion Type)`](../../doc/models/v1-payment-tax-inclusion-type.md) | Optional | - | -| `fee_id` | `str` | Optional | The ID of the tax, if available. Taxes applied in older versions of Square Register might not have an ID. | - -## Example (as JSON) - -```json -{ - "errors": [ - { - "category": "MERCHANT_SUBSCRIPTION_ERROR", - "code": "MAP_KEY_LENGTH_TOO_LONG", - "detail": "detail6", - "field": "field4" - } - ], - "name": "name6", - "applied_money": { - "amount": 196, - "currency_code": "IQD" - }, - "rate": "rate4", - "inclusion_type": "ADDITIVE" -} -``` - diff --git a/doc/models/v1-payment.md b/doc/models/v1-payment.md deleted file mode 100644 index 9db21db9..00000000 --- a/doc/models/v1-payment.md +++ /dev/null @@ -1,75 +0,0 @@ - -# V1 Payment - -A payment represents a paid transaction between a Square merchant and a -customer. Payment details are usually available from Connect API endpoints -within a few minutes after the transaction completes. - -Each Payment object includes several fields that end in `_money`. These fields -describe the various amounts of money that contribute to the payment total: - - - - -## Structure - -`V1 Payment` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `str` | Optional | The payment's unique identifier. | -| `merchant_id` | `str` | Optional | The unique identifier of the merchant that took the payment. | -| `created_at` | `str` | Optional | The time when the payment was created, in ISO 8601 format. Reflects the time of the first payment if the object represents an incomplete partial payment, and the time of the last or complete payment otherwise. | -| `creator_id` | `str` | Optional | The unique identifier of the Square account that took the payment. | -| `device` | [`V1 Device`](../../doc/models/v1-device.md) | Optional | - | -| `payment_url` | `str` | Optional | The URL of the payment's detail page in the merchant dashboard. The merchant must be signed in to the merchant dashboard to view this page. | -| `receipt_url` | `str` | Optional | The URL of the receipt for the payment. Note that for split tender
payments, this URL corresponds to the receipt for the first tender
listed in the payment's tender field. Each Tender object has its own
receipt_url field you can use to get the other receipts associated with
a split tender payment. | -| `inclusive_tax_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `additive_tax_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `tax_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `tip_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `discount_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `total_collected_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `processing_fee_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `net_total_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `swedish_rounding_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `gross_sales_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `net_sales_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `inclusive_tax` | [`List V1 Payment Tax`](../../doc/models/v1-payment-tax.md) | Optional | All of the inclusive taxes associated with the payment. | -| `additive_tax` | [`List V1 Payment Tax`](../../doc/models/v1-payment-tax.md) | Optional | All of the additive taxes associated with the payment. | -| `tender` | [`List V1 Tender`](../../doc/models/v1-tender.md) | Optional | All of the tenders associated with the payment. | -| `refunds` | [`List V1 Refund`](../../doc/models/v1-refund.md) | Optional | All of the refunds applied to the payment. Note that the value of all refunds on a payment can exceed the value of all tenders if a merchant chooses to refund money to a tender after previously accepting returned goods as part of an exchange. | -| `itemizations` | [`List V1 Payment Itemization`](../../doc/models/v1-payment-itemization.md) | Optional | The items purchased in the payment. | -| `surcharge_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `surcharges` | [`List V1 Payment Surcharge`](../../doc/models/v1-payment-surcharge.md) | Optional | A list of all surcharges associated with the payment. | -| `is_partial` | `bool` | Optional | Indicates whether or not the payment is only partially paid for.
If true, this payment will have the tenders collected so far, but the
itemizations will be empty until the payment is completed. | - -## Example (as JSON) - -```json -{ - "id": "id2", - "merchant_id": "merchant_id8", - "created_at": "created_at0", - "creator_id": "creator_id2", - "device": { - "id": "id6", - "name": "name6" - } -} -``` - diff --git a/doc/models/v1-refund-type.md b/doc/models/v1-refund-type.md deleted file mode 100644 index 21e7a4cf..00000000 --- a/doc/models/v1-refund-type.md +++ /dev/null @@ -1,14 +0,0 @@ - -# V1 Refund Type - -## Enumeration - -`V1 Refund Type` - -## Fields - -| Name | -| --- | -| `FULL` | -| `PARTIAL` | - diff --git a/doc/models/v1-refund.md b/doc/models/v1-refund.md deleted file mode 100644 index 35edeec0..00000000 --- a/doc/models/v1-refund.md +++ /dev/null @@ -1,53 +0,0 @@ - -# V1 Refund - -V1Refund - -## Structure - -`V1 Refund` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `type` | [`str (V1 Refund Type)`](../../doc/models/v1-refund-type.md) | Optional | - | -| `reason` | `str` | Optional | The merchant-specified reason for the refund. | -| `refunded_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_processing_fee_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_tax_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_additive_tax_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_additive_tax` | [`List V1 Payment Tax`](../../doc/models/v1-payment-tax.md) | Optional | All of the additive taxes associated with the refund. | -| `refunded_inclusive_tax_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_inclusive_tax` | [`List V1 Payment Tax`](../../doc/models/v1-payment-tax.md) | Optional | All of the inclusive taxes associated with the refund. | -| `refunded_tip_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_discount_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_surcharge_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `refunded_surcharges` | [`List V1 Payment Surcharge`](../../doc/models/v1-payment-surcharge.md) | Optional | A list of all surcharges associated with the refund. | -| `created_at` | `str` | Optional | The time when the merchant initiated the refund for Square to process, in ISO 8601 format. | -| `processed_at` | `str` | Optional | The time when Square processed the refund on behalf of the merchant, in ISO 8601 format. | -| `payment_id` | `str` | Optional | A Square-issued ID associated with the refund. For single-tender refunds, payment_id is the ID of the original payment ID. For split-tender refunds, payment_id is the ID of the original tender. For exchange-based refunds (is_exchange == true), payment_id is the ID of the original payment ID even if the payment includes other tenders. | -| `merchant_id` | `str` | Optional | - | -| `is_exchange` | `bool` | Optional | Indicates whether or not the refund is associated with an exchange. If is_exchange is true, the refund reflects the value of goods returned in the exchange not the total money refunded. | - -## Example (as JSON) - -```json -{ - "type": "FULL", - "reason": "reason4", - "refunded_money": { - "amount": 214, - "currency_code": "SRD" - }, - "refunded_processing_fee_money": { - "amount": 0, - "currency_code": "BGN" - }, - "refunded_tax_money": { - "amount": 148, - "currency_code": "SRD" - } -} -``` - diff --git a/doc/models/v1-settlement-entry-type.md b/doc/models/v1-settlement-entry-type.md deleted file mode 100644 index 7fe9ce7f..00000000 --- a/doc/models/v1-settlement-entry-type.md +++ /dev/null @@ -1,33 +0,0 @@ - -# V1 Settlement Entry Type - -## Enumeration - -`V1 Settlement Entry Type` - -## Fields - -| Name | Description | -| --- | --- | -| `ADJUSTMENT` | A manual adjustment applied to the merchant's account by Square | -| `BALANCE_CHARGE` | A payment from an existing Square balance, such as a gift card | -| `CHARGE` | A credit card payment CAPTURE | -| `FREE_PROCESSING` | Square offers Free Payments Processing for a variety of business scenarios including seller referral or when we want to apologize for a bug, customer service, repricing complication, etc. This entry represents a credit to the merchant for the purposes of Free Processing. | -| `HOLD_ADJUSTMENT` | An adjustment made by Square related to holding/releasing a payment | -| `PAID_SERVICE_FEE` | a fee paid to a 3rd party merchant | -| `PAID_SERVICE_FEE_REFUND` | a refund for a 3rd party merchant fee | -| `REDEMPTION_CODE` | Repayment for a redemption code | -| `REFUND` | A refund for an existing card payment | -| `RETURNED_PAYOUT` | An entry created when we receive a response for the ACH file we sent indicating that the settlement of the original entry failed. | -| `SQUARE_CAPITAL_ADVANCE` | Initial deposit to a merchant for a Capital merchant cash advance (MCA). | -| `SQUARE_CAPITAL_PAYMENT` | Capital merchant cash advance (MCA) assessment. These are, generally, proportional to the merchant's sales but may be issued for other reasons related to the MCA. | -| `SQUARE_CAPITAL_REVERSED_PAYMENT` | Capital merchant cash advance (MCA) assessment refund. These are, generally, proportional to the merchant's refunds but may be issued for other reasons related to the MCA. | -| `SUBSCRIPTION_FEE` | Fee charged for subscription to a Square product | -| `SUBSCRIPTION_FEE_REFUND` | Refund of a previously charged Square product subscription fee. | -| `OTHER` | | -| `INCENTED_PAYMENT` | A payment in which Square covers part of the funds for a purchase | -| `RETURNED_ACH_ENTRY` | A settlement failed to be processed and the settlement amount has been returned to the account | -| `RETURNED_SQUARE_275` | Refund for cancelling a Square Plus subscription | -| `SQUARE_275` | Fee charged for a Square Plus subscription ($275) | -| `SQUARE_CARD` | Settlements to or withdrawals from the Square Card (an asset) | - diff --git a/doc/models/v1-settlement-entry.md b/doc/models/v1-settlement-entry.md deleted file mode 100644 index dd5f298d..00000000 --- a/doc/models/v1-settlement-entry.md +++ /dev/null @@ -1,35 +0,0 @@ - -# V1 Settlement Entry - -V1SettlementEntry - -## Structure - -`V1 Settlement Entry` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `payment_id` | `str` | Optional | The settlement's unique identifier. | -| `type` | [`str (V1 Settlement Entry Type)`](../../doc/models/v1-settlement-entry-type.md) | Optional | - | -| `amount_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `fee_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | - -## Example (as JSON) - -```json -{ - "payment_id": "payment_id0", - "type": "RETURNED_PAYOUT", - "amount_money": { - "amount": 186, - "currency_code": "UZS" - }, - "fee_money": { - "amount": 108, - "currency_code": "ILS" - } -} -``` - diff --git a/doc/models/v1-settlement-status.md b/doc/models/v1-settlement-status.md deleted file mode 100644 index d730bdb7..00000000 --- a/doc/models/v1-settlement-status.md +++ /dev/null @@ -1,14 +0,0 @@ - -# V1 Settlement Status - -## Enumeration - -`V1 Settlement Status` - -## Fields - -| Name | -| --- | -| `FAILED` | -| `SENT` | - diff --git a/doc/models/v1-settlement.md b/doc/models/v1-settlement.md deleted file mode 100644 index cda94b2e..00000000 --- a/doc/models/v1-settlement.md +++ /dev/null @@ -1,35 +0,0 @@ - -# V1 Settlement - -V1Settlement - -## Structure - -`V1 Settlement` - -## Fields - -| Name | Type | Tags | Description | -| --- | --- | --- | --- | -| `id` | `str` | Optional | The settlement's unique identifier. | -| `status` | [`str (V1 Settlement Status)`](../../doc/models/v1-settlement-status.md) | Optional | - | -| `total_money` | [`V1 Money`](../../doc/models/v1-money.md) | Optional | - | -| `initiated_at` | `str` | Optional | The time when the settlement was submitted for deposit or withdrawal, in ISO 8601 format. | -| `bank_account_id` | `str` | Optional | The Square-issued unique identifier for the bank account associated with the settlement. | -| `entries` | [`List V1 Settlement Entry`](../../doc/models/v1-settlement-entry.md) | Optional | The entries included in this settlement. | - -## Example (as JSON) - -```json -{ - "id": "id2", - "status": "FAILED", - "total_money": { - "amount": 250, - "currency_code": "KZT" - }, - "initiated_at": "initiated_at4", - "bank_account_id": "bank_account_id2" -} -``` - diff --git a/pyproject.toml b/pyproject.toml index fcda1978..f0aa03d9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ requires = ["setuptools>=61.0"] [project] name = "squareup" description = "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management." -version = "34.0.1.20240118" +version = "35.0.0.20240222" readme = "README.md" requires-python = ">=3.7" authors = [{name = "Square Developer Platform", email = "developers@squareup.com"}] diff --git a/square/api/apple_pay_api.py b/square/api/apple_pay_api.py index 25875960..c18d1a27 100644 --- a/square/api/apple_pay_api.py +++ b/square/api/apple_pay_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class ApplePayApi(BaseApi): diff --git a/square/api/bank_accounts_api.py b/square/api/bank_accounts_api.py index d72c63c4..ff2ec5d1 100644 --- a/square/api/bank_accounts_api.py +++ b/square/api/bank_accounts_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class BankAccountsApi(BaseApi): diff --git a/square/api/base_api.py b/square/api/base_api.py index e1271ae0..a971495f 100644 --- a/square/api/base_api.py +++ b/square/api/base_api.py @@ -17,13 +17,12 @@ class BaseApi(object): http_call_back (HttpCallBack): An object which holds call back methods to be called before and after the execution of an HttpRequest. new_api_call_builder (APICall): Returns the API Call builder instance. - auth_managers (dict): A dictionary which holds the instances of authentication managers. """ @staticmethod def user_agent(): - return 'Square-Python-SDK/34.0.1.20240118 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}' + return 'Square-Python-SDK/35.0.0.20240222 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}' @staticmethod def user_agent_parameters(): @@ -34,8 +33,7 @@ def user_agent_parameters(): } def __init__(self, config): - self._global_config = config - self._config = self._global_config.get_http_client_configuration() + self._config = config.get_http_client_configuration() self._http_call_back = self.config.http_callback self.api_call = ApiCall(config) @@ -50,7 +48,3 @@ def http_call_back(self): @property def new_api_call_builder(self): return self.api_call.new_builder - - @property - def auth_managers(self): - return self._global_config.get_auth_managers() diff --git a/square/api/booking_custom_attributes_api.py b/square/api/booking_custom_attributes_api.py index 2d32ba51..21b471bf 100644 --- a/square/api/booking_custom_attributes_api.py +++ b/square/api/booking_custom_attributes_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class BookingCustomAttributesApi(BaseApi): diff --git a/square/api/bookings_api.py b/square/api/bookings_api.py index 2318a691..00fb4091 100644 --- a/square/api/bookings_api.py +++ b/square/api/bookings_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class BookingsApi(BaseApi): diff --git a/square/api/cards_api.py b/square/api/cards_api.py index 2b27688f..979e1103 100644 --- a/square/api/cards_api.py +++ b/square/api/cards_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CardsApi(BaseApi): diff --git a/square/api/cash_drawers_api.py b/square/api/cash_drawers_api.py index 8446b05b..ec8b656d 100644 --- a/square/api/cash_drawers_api.py +++ b/square/api/cash_drawers_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CashDrawersApi(BaseApi): diff --git a/square/api/catalog_api.py b/square/api/catalog_api.py index 3e3040b9..9ec604b9 100644 --- a/square/api/catalog_api.py +++ b/square/api/catalog_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CatalogApi(BaseApi): diff --git a/square/api/checkout_api.py b/square/api/checkout_api.py index ab7d90bf..247b449f 100644 --- a/square/api/checkout_api.py +++ b/square/api/checkout_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CheckoutApi(BaseApi): @@ -262,8 +260,8 @@ def list_payment_links(self, next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see - [Pagination](https://developer.squareup.com/docs/basics/api101/ - pagination). + [Pagination](https://developer.squareup.com/docs/build-basics/c + ommon-api-patterns/pagination). limit (int, optional): A limit on the number of results to return per page. The limit is advisory and the implementation might return more or less results. If the supplied limit is diff --git a/square/api/customer_custom_attributes_api.py b/square/api/customer_custom_attributes_api.py index 954593d1..e141558f 100644 --- a/square/api/customer_custom_attributes_api.py +++ b/square/api/customer_custom_attributes_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CustomerCustomAttributesApi(BaseApi): diff --git a/square/api/customer_groups_api.py b/square/api/customer_groups_api.py index f29852dc..b68b89d3 100644 --- a/square/api/customer_groups_api.py +++ b/square/api/customer_groups_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CustomerGroupsApi(BaseApi): diff --git a/square/api/customer_segments_api.py b/square/api/customer_segments_api.py index 66920872..7acbb3e5 100644 --- a/square/api/customer_segments_api.py +++ b/square/api/customer_segments_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CustomerSegmentsApi(BaseApi): diff --git a/square/api/customers_api.py b/square/api/customers_api.py index e5d68d03..1ee5521f 100644 --- a/square/api/customers_api.py +++ b/square/api/customers_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class CustomersApi(BaseApi): @@ -153,6 +151,199 @@ def create_customer(self, .convertor(ApiResponse.create) ).execute() + def bulk_create_customers(self, + body): + """Does a POST request to /v2/customers/bulk-create. + + Creates multiple [customer profiles]($m/Customer) for a business. + This endpoint takes a map of individual create requests and returns a + map of responses. + You must provide at least one of the following values in each create + request: + - `given_name` + - `family_name` + - `company_name` + - `email_address` + - `phone_number` + + Args: + body (BulkCreateCustomersRequest): An object containing the fields + to POST for the request. See the corresponding object + definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/customers/bulk-create') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def bulk_delete_customers(self, + body): + """Does a POST request to /v2/customers/bulk-delete. + + Deletes multiple customer profiles. + The endpoint takes a list of customer IDs and returns a map of + responses. + + Args: + body (BulkDeleteCustomersRequest): An object containing the fields + to POST for the request. See the corresponding object + definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/customers/bulk-delete') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def bulk_retrieve_customers(self, + body): + """Does a POST request to /v2/customers/bulk-retrieve. + + Retrieves multiple customer profiles. + This endpoint takes a list of customer IDs and returns a map of + responses. + + Args: + body (BulkRetrieveCustomersRequest): An object containing the + fields to POST for the request. See the corresponding object + definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/customers/bulk-retrieve') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + + def bulk_update_customers(self, + body): + """Does a POST request to /v2/customers/bulk-update. + + Updates multiple customer profiles. + This endpoint takes a map of individual update requests and returns a + map of responses. + You cannot use this endpoint to change cards on file. To make changes, + use the [Cards API]($e/Cards) or [Gift Cards API]($e/GiftCards). + + Args: + body (BulkUpdateCustomersRequest): An object containing the fields + to POST for the request. See the corresponding object + definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + return super().new_api_call_builder.request( + RequestBuilder().server('default') + .path('/v2/customers/bulk-update') + .http_method(HttpMethodEnum.POST) + .header_param(Parameter() + .key('Content-Type') + .value('application/json')) + .body_param(Parameter() + .value(body)) + .header_param(Parameter() + .key('accept') + .value('application/json')) + .body_serializer(APIHelper.json_serialize) + .auth(Single('global')) + ).response( + ResponseHandler() + .deserializer(APIHelper.json_deserialize) + .is_api_response(True) + .convertor(ApiResponse.create) + ).execute() + def search_customers(self, body): """Does a POST request to /v2/customers/search. @@ -215,12 +406,6 @@ def delete_customer(self, Deletes a customer profile from a business. This operation also unlinks any associated cards on file. - As a best practice, include the `version` field in the request to - enable [optimistic - concurrency](https://developer.squareup.com/docs/build-basics/common-ap - i-patterns/optimistic-concurrency) control. - If included, the value must be set to the current version of the - customer profile. To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile. @@ -317,14 +502,7 @@ def update_customer(self, Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request. To add or update a field, specify the new value. To remove a field, - specify `null` - (recommended) or specify an empty string (string fields only). - As a best practice, include the `version` field in the request to - enable [optimistic - concurrency](https://developer.squareup.com/docs/build-basics/common-ap - i-patterns/optimistic-concurrency) control. - If included, the value must be set to the current version of the - customer profile. + specify `null`. To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile. You cannot use this endpoint to change cards on file. To make changes, diff --git a/square/api/devices_api.py b/square/api/devices_api.py index 74b39e7b..30e465ba 100644 --- a/square/api/devices_api.py +++ b/square/api/devices_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class DevicesApi(BaseApi): diff --git a/square/api/disputes_api.py b/square/api/disputes_api.py index 3672af39..5865d20a 100644 --- a/square/api/disputes_api.py +++ b/square/api/disputes_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class DisputesApi(BaseApi): diff --git a/square/api/employees_api.py b/square/api/employees_api.py index 41f2db80..da56b9ce 100644 --- a/square/api/employees_api.py +++ b/square/api/employees_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class EmployeesApi(BaseApi): diff --git a/square/api/gift_card_activities_api.py b/square/api/gift_card_activities_api.py index 0e8ea5d8..4fd16572 100644 --- a/square/api/gift_card_activities_api.py +++ b/square/api/gift_card_activities_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class GiftCardActivitiesApi(BaseApi): diff --git a/square/api/gift_cards_api.py b/square/api/gift_cards_api.py index a5a7e881..9dbb39be 100644 --- a/square/api/gift_cards_api.py +++ b/square/api/gift_cards_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class GiftCardsApi(BaseApi): diff --git a/square/api/inventory_api.py b/square/api/inventory_api.py index bc25ec98..dc585c1d 100644 --- a/square/api/inventory_api.py +++ b/square/api/inventory_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class InventoryApi(BaseApi): diff --git a/square/api/invoices_api.py b/square/api/invoices_api.py index 34f9cf64..7ed80150 100644 --- a/square/api/invoices_api.py +++ b/square/api/invoices_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class InvoicesApi(BaseApi): @@ -512,9 +510,13 @@ def publish_invoice(self, The invoice `status` also changes from `DRAFT` to a status based on the invoice configuration. For example, the status changes to `UNPAID` if - Square emails the invoice or `PARTIALLY_PAID` if Square charge a card + Square emails the invoice or `PARTIALLY_PAID` if Square charges a card on file for a portion of the invoice amount. + In addition to the required `ORDERS_WRITE` and `INVOICES_WRITE` + permissions, `CUSTOMERS_READ` + and `PAYMENTS_WRITE` are required when publishing invoices configured + for card-on-file payments. Args: invoice_id (str): The ID of the invoice to publish. diff --git a/square/api/labor_api.py b/square/api/labor_api.py index f16363b0..646fdbc8 100644 --- a/square/api/labor_api.py +++ b/square/api/labor_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class LaborApi(BaseApi): diff --git a/square/api/location_custom_attributes_api.py b/square/api/location_custom_attributes_api.py index e0646a58..3d190838 100644 --- a/square/api/location_custom_attributes_api.py +++ b/square/api/location_custom_attributes_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class LocationCustomAttributesApi(BaseApi): diff --git a/square/api/locations_api.py b/square/api/locations_api.py index d0069cc9..65109064 100644 --- a/square/api/locations_api.py +++ b/square/api/locations_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class LocationsApi(BaseApi): @@ -23,7 +21,8 @@ def list_locations(self): Provides details about all of the seller's [locations](https://developer.squareup.com/docs/locations-api), - including those with an inactive status. + including those with an inactive status. Locations are listed + alphabetically by `name`. Returns: ApiResponse: An object with the response value as well as other diff --git a/square/api/loyalty_api.py b/square/api/loyalty_api.py index 5ad6dc6c..27f43681 100644 --- a/square/api/loyalty_api.py +++ b/square/api/loyalty_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class LoyaltyApi(BaseApi): diff --git a/square/api/merchant_custom_attributes_api.py b/square/api/merchant_custom_attributes_api.py index 30b25cd8..efdf2d50 100644 --- a/square/api/merchant_custom_attributes_api.py +++ b/square/api/merchant_custom_attributes_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class MerchantCustomAttributesApi(BaseApi): diff --git a/square/api/merchants_api.py b/square/api/merchants_api.py index a17eb891..d1e95546 100644 --- a/square/api/merchants_api.py +++ b/square/api/merchants_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class MerchantsApi(BaseApi): diff --git a/square/api/mobile_authorization_api.py b/square/api/mobile_authorization_api.py index f50512c1..056f2ef9 100644 --- a/square/api/mobile_authorization_api.py +++ b/square/api/mobile_authorization_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class MobileAuthorizationApi(BaseApi): diff --git a/square/api/order_custom_attributes_api.py b/square/api/order_custom_attributes_api.py index 2c019c0e..db91f54b 100644 --- a/square/api/order_custom_attributes_api.py +++ b/square/api/order_custom_attributes_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class OrderCustomAttributesApi(BaseApi): diff --git a/square/api/orders_api.py b/square/api/orders_api.py index 2ba883d0..79562619 100644 --- a/square/api/orders_api.py +++ b/square/api/orders_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class OrdersApi(BaseApi): diff --git a/square/api/payments_api.py b/square/api/payments_api.py index f6281a98..78787f5f 100644 --- a/square/api/payments_api.py +++ b/square/api/payments_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class PaymentsApi(BaseApi): diff --git a/square/api/payouts_api.py b/square/api/payouts_api.py index cc1bb63d..ae21bcf3 100644 --- a/square/api/payouts_api.py +++ b/square/api/payouts_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class PayoutsApi(BaseApi): diff --git a/square/api/refunds_api.py b/square/api/refunds_api.py index 6bc73b62..cdb7b9c5 100644 --- a/square/api/refunds_api.py +++ b/square/api/refunds_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class RefundsApi(BaseApi): diff --git a/square/api/sites_api.py b/square/api/sites_api.py index 45ece37f..28528f93 100644 --- a/square/api/sites_api.py +++ b/square/api/sites_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class SitesApi(BaseApi): diff --git a/square/api/snippets_api.py b/square/api/snippets_api.py index 5249ceed..1c01c488 100644 --- a/square/api/snippets_api.py +++ b/square/api/snippets_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class SnippetsApi(BaseApi): diff --git a/square/api/subscriptions_api.py b/square/api/subscriptions_api.py index 76f08a80..8cd4d948 100644 --- a/square/api/subscriptions_api.py +++ b/square/api/subscriptions_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class SubscriptionsApi(BaseApi): diff --git a/square/api/team_api.py b/square/api/team_api.py index d232ba7c..95b885af 100644 --- a/square/api/team_api.py +++ b/square/api/team_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class TeamApi(BaseApi): diff --git a/square/api/terminal_api.py b/square/api/terminal_api.py index f325bbe9..87c7df16 100644 --- a/square/api/terminal_api.py +++ b/square/api/terminal_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class TerminalApi(BaseApi): diff --git a/square/api/transactions_api.py b/square/api/transactions_api.py index e3ddd259..f68b0038 100644 --- a/square/api/transactions_api.py +++ b/square/api/transactions_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class TransactionsApi(BaseApi): diff --git a/square/api/v1_transactions_api.py b/square/api/v1_transactions_api.py index e057a7fb..381810a8 100644 --- a/square/api/v1_transactions_api.py +++ b/square/api/v1_transactions_api.py @@ -9,8 +9,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class V1TransactionsApi(BaseApi): @@ -186,451 +184,3 @@ def v1_update_order(self, .is_api_response(True) .convertor(ApiResponse.create) ).execute() - - @deprecated() - def v1_list_payments(self, - location_id, - order=None, - begin_time=None, - end_time=None, - limit=None, - batch_token=None, - include_partial=False): - """Does a GET request to /v1/{location_id}/payments. - - Provides summary information for all payments taken for a given - Square account during a date range. Date ranges cannot exceed 1 year - in - length. See Date ranges for details of inclusive and exclusive dates. - *Note**: Details for payments processed with Square Point of Sale - while - in offline mode may not be transmitted to Square for up to 72 hours. - Offline payments have a `created_at` value that reflects the time the - payment was originally processed, not the time it was subsequently - transmitted to Square. Consequently, the ListPayments endpoint might - list an offline payment chronologically between online payments that - were seen in a previous request. - - Args: - location_id (str): The ID of the location to list payments for. If - you specify me, this endpoint returns payments aggregated from - all of the business's locations. - order (SortOrder, optional): The order in which payments are - listed in the response. - begin_time (str, optional): The beginning of the requested - reporting period, in ISO 8601 format. If this value is before - January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns - an error. Default value: The current time minus one year. - end_time (str, optional): The end of the requested reporting - period, in ISO 8601 format. If this value is more than one - year greater than begin_time, this endpoint returns an error. - Default value: The current time. - limit (int, optional): The maximum number of payments to return in - a single response. This value cannot exceed 200. - batch_token (str, optional): A pagination cursor to retrieve the - next set of results for your original query to the endpoint. - include_partial (bool, optional): Indicates whether or not to - include partial payments in the response. Partial payments - will have the tenders collected so far, but the itemizations - will be empty until the payment is completed. - - Returns: - ApiResponse: An object with the response value as well as other - useful information such as status codes and headers. Success - - Raises: - APIException: When an error occurs while fetching the data from - the remote API. This exception includes the HTTP Response - code, an error message, and the HTTP body that was received in - the request. - - """ - - return super().new_api_call_builder.request( - RequestBuilder().server('default') - .path('/v1/{location_id}/payments') - .http_method(HttpMethodEnum.GET) - .template_param(Parameter() - .key('location_id') - .value(location_id) - .should_encode(True)) - .query_param(Parameter() - .key('order') - .value(order)) - .query_param(Parameter() - .key('begin_time') - .value(begin_time)) - .query_param(Parameter() - .key('end_time') - .value(end_time)) - .query_param(Parameter() - .key('limit') - .value(limit)) - .query_param(Parameter() - .key('batch_token') - .value(batch_token)) - .query_param(Parameter() - .key('include_partial') - .value(include_partial)) - .header_param(Parameter() - .key('accept') - .value('application/json')) - .auth(Single('global')) - ).response( - ResponseHandler() - .deserializer(APIHelper.json_deserialize) - .is_api_response(True) - .convertor(ApiResponse.create) - ).execute() - - @deprecated() - def v1_retrieve_payment(self, - location_id, - payment_id): - """Does a GET request to /v1/{location_id}/payments/{payment_id}. - - Provides comprehensive information for a single payment. - - Args: - location_id (str): The ID of the payment's associated location. - payment_id (str): The Square-issued payment ID. payment_id comes - from Payment objects returned by the List Payments endpoint, - Settlement objects returned by the List Settlements endpoint, - or Refund objects returned by the List Refunds 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. - - """ - - return super().new_api_call_builder.request( - RequestBuilder().server('default') - .path('/v1/{location_id}/payments/{payment_id}') - .http_method(HttpMethodEnum.GET) - .template_param(Parameter() - .key('location_id') - .value(location_id) - .should_encode(True)) - .template_param(Parameter() - .key('payment_id') - .value(payment_id) - .should_encode(True)) - .header_param(Parameter() - .key('accept') - .value('application/json')) - .auth(Single('global')) - ).response( - ResponseHandler() - .deserializer(APIHelper.json_deserialize) - .is_api_response(True) - .convertor(ApiResponse.create) - ).execute() - - @deprecated() - def v1_list_refunds(self, - location_id, - order=None, - begin_time=None, - end_time=None, - limit=None, - batch_token=None): - """Does a GET request to /v1/{location_id}/refunds. - - Provides the details for all refunds initiated by a merchant or any of - the merchant's mobile staff during a date range. Date ranges cannot - exceed one year in length. - - Args: - location_id (str): The ID of the location to list refunds for. - order (SortOrder, optional): The order in which payments are - listed in the response. - begin_time (str, optional): The beginning of the requested - reporting period, in ISO 8601 format. If this value is before - January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns - an error. Default value: The current time minus one year. - end_time (str, optional): The end of the requested reporting - period, in ISO 8601 format. If this value is more than one - year greater than begin_time, this endpoint returns an error. - Default value: The current time. - limit (int, optional): The approximate number of refunds to return - in a single response. Default: 100. Max: 200. Response may - contain more results than the prescribed limit when refunds - are made simultaneously to multiple tenders in a payment or - when refunds are generated in an exchange to account for the - value of returned goods. - batch_token (str, 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. - - """ - - return super().new_api_call_builder.request( - RequestBuilder().server('default') - .path('/v1/{location_id}/refunds') - .http_method(HttpMethodEnum.GET) - .template_param(Parameter() - .key('location_id') - .value(location_id) - .should_encode(True)) - .query_param(Parameter() - .key('order') - .value(order)) - .query_param(Parameter() - .key('begin_time') - .value(begin_time)) - .query_param(Parameter() - .key('end_time') - .value(end_time)) - .query_param(Parameter() - .key('limit') - .value(limit)) - .query_param(Parameter() - .key('batch_token') - .value(batch_token)) - .header_param(Parameter() - .key('accept') - .value('application/json')) - .auth(Single('global')) - ).response( - ResponseHandler() - .deserializer(APIHelper.json_deserialize) - .is_api_response(True) - .convertor(ApiResponse.create) - ).execute() - - @deprecated() - def v1_create_refund(self, - location_id, - body): - """Does a POST request to /v1/{location_id}/refunds. - - Issues a refund for a previously processed payment. You must issue - a refund within 60 days of the associated payment. - You cannot issue a partial refund for a split tender payment. You - must - instead issue a full or partial refund for a particular tender, by - providing the applicable tender id to the V1CreateRefund endpoint. - Issuing a full refund for a split tender payment refunds all tenders - associated with the payment. - Issuing a refund for a card payment is not reversible. For - development - purposes, you can create fake cash payments in Square Point of Sale - and - refund them. - - Args: - location_id (str): The ID of the original payment's associated - location. - body (V1CreateRefundRequest): An object containing the fields to - POST for the request. See the corresponding object definition - for field details. - - Returns: - ApiResponse: An object with the response value as well as other - useful information such as status codes and headers. Success - - Raises: - APIException: When an error occurs while fetching the data from - the remote API. This exception includes the HTTP Response - code, an error message, and the HTTP body that was received in - the request. - - """ - - return super().new_api_call_builder.request( - RequestBuilder().server('default') - .path('/v1/{location_id}/refunds') - .http_method(HttpMethodEnum.POST) - .template_param(Parameter() - .key('location_id') - .value(location_id) - .should_encode(True)) - .header_param(Parameter() - .key('Content-Type') - .value('application/json')) - .body_param(Parameter() - .value(body)) - .header_param(Parameter() - .key('accept') - .value('application/json')) - .body_serializer(APIHelper.json_serialize) - .auth(Single('global')) - ).response( - ResponseHandler() - .deserializer(APIHelper.json_deserialize) - .is_api_response(True) - .convertor(ApiResponse.create) - ).execute() - - @deprecated() - def v1_list_settlements(self, - location_id, - order=None, - begin_time=None, - end_time=None, - limit=None, - status=None, - batch_token=None): - """Does a GET request to /v1/{location_id}/settlements. - - Provides summary information for all deposits and withdrawals - initiated by Square to a linked bank account during a date range. - Date - ranges cannot exceed one year in length. - *Note**: the ListSettlements endpoint does not provide entry - information. - - Args: - location_id (str): The ID of the location to list settlements for. - If you specify me, this endpoint returns settlements - aggregated from all of the business's locations. - order (SortOrder, optional): The order in which settlements are - listed in the response. - begin_time (str, optional): The beginning of the requested - reporting period, in ISO 8601 format. If this value is before - January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns - an error. Default value: The current time minus one year. - end_time (str, optional): The end of the requested reporting - period, in ISO 8601 format. If this value is more than one - year greater than begin_time, this endpoint returns an error. - Default value: The current time. - limit (int, optional): The maximum number of settlements to return - in a single response. This value cannot exceed 200. - status (V1ListSettlementsRequestStatus, optional): Provide this - parameter to retrieve only settlements with a particular - status (SENT or FAILED). - batch_token (str, 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. - - """ - - return super().new_api_call_builder.request( - RequestBuilder().server('default') - .path('/v1/{location_id}/settlements') - .http_method(HttpMethodEnum.GET) - .template_param(Parameter() - .key('location_id') - .value(location_id) - .should_encode(True)) - .query_param(Parameter() - .key('order') - .value(order)) - .query_param(Parameter() - .key('begin_time') - .value(begin_time)) - .query_param(Parameter() - .key('end_time') - .value(end_time)) - .query_param(Parameter() - .key('limit') - .value(limit)) - .query_param(Parameter() - .key('status') - .value(status)) - .query_param(Parameter() - .key('batch_token') - .value(batch_token)) - .header_param(Parameter() - .key('accept') - .value('application/json')) - .auth(Single('global')) - ).response( - ResponseHandler() - .deserializer(APIHelper.json_deserialize) - .is_api_response(True) - .convertor(ApiResponse.create) - ).execute() - - @deprecated() - def v1_retrieve_settlement(self, - location_id, - settlement_id): - """Does a GET request to /v1/{location_id}/settlements/{settlement_id}. - - Provides comprehensive information for a single settlement. - The returned `Settlement` objects include an `entries` field that - lists - the transactions that contribute to the settlement total. Most - settlement entries correspond to a payment payout, but settlement - entries are also generated for less common events, like refunds, - manual - adjustments, or chargeback holds. - Square initiates its regular deposits as indicated in the - [Deposit Options with - Square](https://squareup.com/help/us/en/article/3807) - help article. Details for a regular deposit are usually not available - from Connect API endpoints before 10 p.m. PST the same day. - Square does not know when an initiated settlement **completes**, only - whether it has failed. A completed settlement is typically reflected - in - a bank account within 3 business days, but in exceptional cases it - may - take longer. - - Args: - location_id (str): The ID of the settlements's associated - location. - settlement_id (str): The settlement's Square-issued ID. You obtain - this value from Settlement objects returned by the List - Settlements 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. - - """ - - return super().new_api_call_builder.request( - RequestBuilder().server('default') - .path('/v1/{location_id}/settlements/{settlement_id}') - .http_method(HttpMethodEnum.GET) - .template_param(Parameter() - .key('location_id') - .value(location_id) - .should_encode(True)) - .template_param(Parameter() - .key('settlement_id') - .value(settlement_id) - .should_encode(True)) - .header_param(Parameter() - .key('accept') - .value('application/json')) - .auth(Single('global')) - ).response( - ResponseHandler() - .deserializer(APIHelper.json_deserialize) - .is_api_response(True) - .convertor(ApiResponse.create) - ).execute() diff --git a/square/api/vendors_api.py b/square/api/vendors_api.py index 2adcbcc4..0b3e1d87 100644 --- a/square/api/vendors_api.py +++ b/square/api/vendors_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class VendorsApi(BaseApi): diff --git a/square/api/webhook_subscriptions_api.py b/square/api/webhook_subscriptions_api.py index 3863108c..a665c80a 100644 --- a/square/api/webhook_subscriptions_api.py +++ b/square/api/webhook_subscriptions_api.py @@ -8,8 +8,6 @@ from apimatic_core.types.parameter import Parameter from square.http.http_method_enum import HttpMethodEnum from apimatic_core.authentication.multiple.single_auth import Single -from apimatic_core.authentication.multiple.and_auth_group import And -from apimatic_core.authentication.multiple.or_auth_group import Or class WebhookSubscriptionsApi(BaseApi): diff --git a/square/client.py b/square/client.py index 1afdfb7e..8cfffde1 100644 --- a/square/client.py +++ b/square/client.py @@ -52,14 +52,13 @@ class Client(object): - @staticmethod def sdk_version(): - return '34.0.1.20240118' + return '35.0.0.20240222' @staticmethod def square_version(): - return '2024-01-18' + return '2024-02-22' def user_agent_detail(self): return self.config.user_agent_detail @@ -231,29 +230,23 @@ def webhook_subscriptions(self): def __init__(self, http_client_instance=None, override_http_client_configuration=False, http_call_back=None, 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', access_token='', - square_version='2024-01-18', additional_headers={}, - user_agent_detail='', config=None): - if config is None: - self.config = Configuration( - http_client_instance=http_client_instance, - override_http_client_configuration=override_http_client_configuration, - http_call_back=http_call_back, - timeout=timeout, - max_retries=max_retries, - backoff_factor=backoff_factor, - retry_statuses=retry_statuses, - retry_methods=retry_methods, - environment=environment, - custom_url=custom_url, - access_token=access_token, - square_version=square_version, - additional_headers=additional_headers, - user_agent_detail=user_agent_detail) - else: - self.config = config + retry_statuses=None, retry_methods=None, + environment='production', + custom_url='https://connect.squareup.com', access_token=None, + bearer_auth_credentials=None, square_version='2024-02-22', + additional_headers={}, user_agent_detail='', config=None): + self.config = config or Configuration( + http_client_instance=http_client_instance, + override_http_client_configuration=override_http_client_configuration, + http_call_back=http_call_back, timeout=timeout, + max_retries=max_retries, backoff_factor=backoff_factor, + retry_statuses=retry_statuses, retry_methods=retry_methods, + environment=environment, custom_url=custom_url, + access_token=access_token, + bearer_auth_credentials=bearer_auth_credentials, + square_version=square_version, + additional_headers=additional_headers, + user_agent_detail=user_agent_detail) additional_user_agent_parameters = { 'api-version': {'value': self.config.square_version, 'encode': False}, @@ -265,12 +258,8 @@ def __init__(self, http_client_instance=None, .additional_headers(self.config.additional_headers)\ .global_header('Square-Version', self.config.square_version) - self.initialize_auth_managers(self.global_configuration) - + self.auth_managers = {key: None for key in ['global']} + self.auth_managers['global'] = OAuth2( + self.config.bearer_auth_credentials) self.global_configuration = self.global_configuration.auth_managers(self.auth_managers) - def initialize_auth_managers(self, global_config): - http_client_config = global_config.get_http_client_configuration() - self.auth_managers = { key: None for key in ['global']} - self.auth_managers['global'] = OAuth2(http_client_config.access_token) - return self.auth_managers diff --git a/square/configuration.py b/square/configuration.py index e156f9d3..b64f8c9c 100644 --- a/square/configuration.py +++ b/square/configuration.py @@ -1,5 +1,6 @@ # -*- coding: utf-8 -*- +import warnings from copy import deepcopy from square.api_helper import APIHelper from apimatic_core.http.configurations.http_client_configuration import HttpClientConfiguration @@ -20,7 +21,7 @@ def custom_url(self): @property def access_token(self): - return self._access_token + return self._bearer_auth_credentials.access_token @property def square_version(self): @@ -34,33 +35,42 @@ def additional_headers(self): def user_agent_detail(self): return self._user_agent_detail - def __init__( - self, http_client_instance=None, - override_http_client_configuration=False, http_call_back=None, - 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', access_token='', - square_version='2024-01-18', additional_headers={}, - user_agent_detail='' - ): + @property + def bearer_auth_credentials(self): + return self._bearer_auth_credentials + + def __init__(self, http_client_instance=None, + override_http_client_configuration=False, http_call_back=None, + timeout=60, max_retries=0, backoff_factor=2, + retry_statuses=None, retry_methods=None, + environment='production', + custom_url='https://connect.squareup.com', access_token=None, + bearer_auth_credentials=None, square_version='2024-02-22', + additional_headers={}, user_agent_detail=''): + if retry_methods is None: + retry_methods = ['GET', 'PUT'] + + if retry_statuses is None: + retry_statuses = [408, 413, 429, 500, 502, 503, 504, 521, 522, 524] + super().__init__(http_client_instance, override_http_client_configuration, http_call_back, timeout, max_retries, backoff_factor, retry_statuses, retry_methods) + # Current API environment self._environment = environment # Sets the base URL requests are made to. Defaults to `https://connect.squareup.com` self._custom_url = custom_url - # The OAuth 2.0 Access Token to use for API requests. - self._access_token = access_token - # Square Connect API versions self._square_version = square_version # Additional headers to add to each API request self._additional_headers = deepcopy(additional_headers) + self._bearer_auth_credentials = self.create_auth_credentials_object( + access_token, bearer_auth_credentials) + # User agent detail, to be appended with user-agent header. self._user_agent_detail = Configuration.validate_user_agent(user_agent_detail) @@ -71,7 +81,8 @@ def clone_with(self, http_client_instance=None, override_http_client_configuration=None, http_call_back=None, timeout=None, max_retries=None, backoff_factor=None, retry_statuses=None, retry_methods=None, environment=None, - custom_url=None, access_token=None, square_version=None, + custom_url=None, access_token=None, + bearer_auth_credentials=None, square_version=None, additional_headers=None, user_agent_detail=None): http_client_instance = http_client_instance or self.http_client_instance override_http_client_configuration = override_http_client_configuration or self.override_http_client_configuration @@ -83,10 +94,13 @@ def clone_with(self, http_client_instance=None, retry_methods = retry_methods or self.retry_methods environment = environment or self.environment custom_url = custom_url or self.custom_url - access_token = access_token or self.access_token square_version = square_version or self.square_version additional_headers = additional_headers or self.additional_headers user_agent_detail = user_agent_detail or self.user_agent_detail + bearer_auth_credentials = self.create_auth_credentials_object( + access_token, + bearer_auth_credentials or self.bearer_auth_credentials, + stack_level=3) return Configuration( http_client_instance=http_client_instance, override_http_client_configuration=override_http_client_configuration, @@ -94,9 +108,9 @@ def clone_with(self, http_client_instance=None, max_retries=max_retries, backoff_factor=backoff_factor, retry_statuses=retry_statuses, retry_methods=retry_methods, environment=environment, custom_url=custom_url, - access_token=access_token, square_version=square_version, - additional_headers=additional_headers, - user_agent_detail=user_agent_detail + square_version=square_version, additional_headers=additional_headers, + user_agent_detail=user_agent_detail, + bearer_auth_credentials=bearer_auth_credentials ) def create_http_client(self): @@ -147,3 +161,20 @@ def validate_user_agent(user_agent): if len(user_agent) > 128: raise ValueError('The length of user-agent detail should not exceed 128 characters.') return user_agent + + @staticmethod + def create_auth_credentials_object(access_token, bearer_auth_credentials, + stack_level=4): + if access_token is None: + return bearer_auth_credentials + + warnings.warn(message=('The \'access_token\' params are deprecated. Use' + ' \'bearer_auth_credentials\' param instead.'), + category=DeprecationWarning, + stacklevel=stack_level) + + if bearer_auth_credentials is not None: + return bearer_auth_credentials.clone_with(access_token) + + from square.http.auth.o_auth_2 import BearerAuthCredentials + return BearerAuthCredentials(access_token) diff --git a/square/http/auth/o_auth_2.py b/square/http/auth/o_auth_2.py index 7cfb2cdd..a589815e 100644 --- a/square/http/auth/o_auth_2.py +++ b/square/http/auth/o_auth_2.py @@ -11,12 +11,27 @@ def error_message(self): in BearerAuth """ - return "BearerAuth: access_token is undefined." + return "BearerAuth: AccessToken is undefined." - def __init__(self, access_token): + def __init__(self, bearer_auth_credentials): auth_params = {} - self._access_token = access_token + self._access_token = bearer_auth_credentials.access_token \ + if bearer_auth_credentials is not None else None if self._access_token: auth_params["Authorization"] = "Bearer {}".format(self._access_token) super().__init__(auth_params=auth_params) + +class BearerAuthCredentials: + + @property + def access_token(self): + return self._access_token + + def __init__(self, access_token): + if access_token is None: + raise ValueError('access_token cannot be None') + self._access_token = access_token + + def clone_with(self, access_token=None): + return BearerAuthCredentials(access_token or self.access_token) diff --git a/tests/api/api_test_base.py b/tests/api/api_test_base.py index 983c28dd..664bd208 100644 --- a/tests/api/api_test_base.py +++ b/tests/api/api_test_base.py @@ -12,6 +12,9 @@ class ApiTestBase(unittest.TestCase): """All test classes inherit from this base class. It abstracts out common functionality and configuration variables set up.""" + client = None + config = None + @classmethod def setUpClass(cls): """Class method called once before running tests in a test class.""" @@ -19,7 +22,6 @@ def setUpClass(cls): cls.assert_precision = 0.01 cls.config = ApiTestBase.create_configuration() cls.client = Client(config=cls.config) - cls.auth_managers = cls.client.auth_managers @staticmethod def create_configuration(): diff --git a/tests/api/test_locations_api.py b/tests/api/test_locations_api.py index 7a69cb55..d5c606be 100644 --- a/tests/api/test_locations_api.py +++ b/tests/api/test_locations_api.py @@ -10,6 +10,8 @@ class LocationsApiTests(ApiTestBase): + controller = None + @classmethod def setUpClass(cls): super(LocationsApiTests, cls).setUpClass() @@ -17,7 +19,7 @@ def setUpClass(cls): cls.response_catcher = cls.controller.http_call_back # Provides details about all of the seller's [locations](https://developer.squareup.com/docs/locations-api), - #including those with an inactive status. + #including those with an inactive status. Locations are listed alphabetically by `name`. def test_list_locations(self): # Perform the API call through the SDK function