From a5be2c4df33b972a82cdb2322d1fe59865e59f9b Mon Sep 17 00:00:00 2001 From: autobot Date: Wed, 17 Nov 2021 00:56:18 +0000 Subject: [PATCH] Generated PR for Release: 16.0.0.20211117 --- CHANGELOG.md | 26 +++ doc/api/bookings.md | 49 ++++ doc/api/disputes.md | 2 +- doc/api/gift-card-activities.md | 14 +- doc/api/gift-cards.md | 20 +- doc/api/sites.md | 2 +- doc/api/subscriptions.md | 150 +++++++++++- doc/client.md | 8 +- doc/models/booking.md | 2 +- doc/models/cancel-subscription-response.md | 9 +- doc/models/card-square-product.md | 1 + doc/models/card.md | 1 + doc/models/change-timing.md | 16 ++ doc/models/create-card-response.md | 3 +- doc/models/create-subscription-request.md | 12 +- doc/models/create-subscription-response.md | 6 +- .../delete-subscription-action-response.md | 47 ++++ doc/models/device-code.md | 2 +- doc/models/disable-card-response.md | 3 +- .../dispute-evidence-created-webhook-data.md | 2 +- ...dispute-evidence-created-webhook-object.md | 2 +- doc/models/dispute-state.md | 22 +- doc/models/dispute.md | 2 +- doc/models/error-code.md | 4 + doc/models/error.md | 2 +- doc/models/gift-card-activity-block.md | 2 +- doc/models/gift-card-activity-type.md | 2 + doc/models/gift-card-activity-unblock.md | 2 +- doc/models/gift-card-activity.md | 2 +- doc/models/gift-card-type.md | 2 + doc/models/gift-card.md | 2 +- doc/models/invoice-sort.md | 2 +- .../link-customer-to-gift-card-request.md | 4 +- .../link-customer-to-gift-card-response.md | 4 +- doc/models/list-bookings-request.md | 30 +++ doc/models/list-bookings-response.md | 46 ++++ doc/models/list-cards-response.md | 3 +- doc/models/list-employees-response.md | 6 +- .../list-gift-card-activities-request.md | 14 +- .../list-gift-card-activities-response.md | 8 +- doc/models/list-gift-cards-request.md | 10 +- doc/models/list-gift-cards-response.md | 8 +- doc/models/list-loyalty-programs-response.md | 3 +- doc/models/list-sites-response.md | 18 +- .../list-subscription-events-request.md | 8 +- .../list-subscription-events-response.md | 11 +- ...st-team-member-booking-profiles-request.md | 2 +- doc/models/pause-subscription-request.md | 32 +++ doc/models/pause-subscription-response.md | 49 ++++ doc/models/payment.md | 2 +- doc/models/refund-payment-request.md | 2 +- doc/models/resume-subscription-request.md | 26 +++ doc/models/resume-subscription-response.md | 17 +- doc/models/retrieve-card-response.md | 3 +- doc/models/retrieve-employee-response.md | 6 +- .../retrieve-gift-card-from-nonce-request.md | 4 +- .../retrieve-gift-card-from-nonce-response.md | 4 +- .../retrieve-loyalty-program-response.md | 3 +- doc/models/retrieve-snippet-response.md | 4 +- doc/models/retrieve-subscription-request.md | 24 ++ doc/models/retrieve-subscription-response.md | 6 +- doc/models/search-catalog-items-response.md | 6 +- doc/models/search-loyalty-accounts-request.md | 2 +- doc/models/search-loyalty-rewards-request.md | 2 +- doc/models/search-subscriptions-filter.md | 7 +- doc/models/search-subscriptions-query.md | 4 +- doc/models/search-subscriptions-request.md | 12 +- doc/models/search-subscriptions-response.md | 8 +- doc/models/snippet-response.md | 6 +- doc/models/subscription-action-type.md | 18 ++ doc/models/subscription-action.md | 29 +++ doc/models/subscription-event-info-code.md | 9 +- doc/models/subscription-event-info.md | 4 +- ...scription-event-subscription-event-type.md | 13 +- doc/models/subscription-event.md | 10 +- doc/models/subscription-status.md | 5 +- doc/models/subscription.md | 18 +- doc/models/swap-plan-request.md | 24 ++ doc/models/swap-plan-response.md | 50 ++++ .../unlink-customer-from-gift-card-request.md | 4 +- ...unlink-customer-from-gift-card-response.md | 4 +- doc/models/update-subscription-request.md | 7 +- doc/models/update-subscription-response.md | 6 +- doc/models/upsert-snippet-response.md | 4 +- doc/models/v1-list-orders-response.md | 8 +- doc/models/v1-order.md | 6 +- doc/models/v1-payment-tax.md | 6 +- setup.py | 2 +- square/api/apple_pay_api.py | 2 +- square/api/base_api.py | 2 +- square/api/bookings_api.py | 86 ++++++- square/api/cards_api.py | 2 +- square/api/catalog_api.py | 16 +- square/api/checkout_api.py | 2 +- square/api/customer_groups_api.py | 4 +- square/api/customers_api.py | 8 +- square/api/devices_api.py | 2 +- square/api/disputes_api.py | 2 +- square/api/gift_card_activities_api.py | 51 ++-- square/api/gift_cards_api.py | 57 +++-- square/api/inventory_api.py | 12 +- square/api/invoices_api.py | 10 +- square/api/labor_api.py | 12 +- square/api/locations_api.py | 4 +- square/api/loyalty_api.py | 18 +- square/api/mobile_authorization_api.py | 2 +- square/api/o_auth_api.py | 6 +- square/api/orders_api.py | 14 +- square/api/payments_api.py | 8 +- square/api/refunds_api.py | 2 +- square/api/sites_api.py | 3 +- square/api/snippets_api.py | 2 +- square/api/subscriptions_api.py | 217 ++++++++++++++++-- square/api/team_api.py | 12 +- square/api/terminal_api.py | 8 +- square/api/v1_transactions_api.py | 4 +- square/client.py | 33 +-- square/configuration.py | 61 +++-- square/http/requests_client.py | 30 ++- 119 files changed, 1348 insertions(+), 396 deletions(-) create mode 100644 doc/models/change-timing.md create mode 100644 doc/models/delete-subscription-action-response.md create mode 100644 doc/models/list-bookings-request.md create mode 100644 doc/models/list-bookings-response.md create mode 100644 doc/models/pause-subscription-request.md create mode 100644 doc/models/pause-subscription-response.md create mode 100644 doc/models/resume-subscription-request.md create mode 100644 doc/models/retrieve-subscription-request.md create mode 100644 doc/models/subscription-action-type.md create mode 100644 doc/models/subscription-action.md create mode 100644 doc/models/swap-plan-request.md create mode 100644 doc/models/swap-plan-response.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 96c6d57b..676d8332 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,31 @@ # Change Log +## Version 16.0.0.20211117 (2021-11-17) +## API updates + +* **Cards API.** The [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/card) object and webhook response body for all webhooks are updated updated with fields. + * Added the [Card.merchant_id](https://developer.squareup.com/reference/square_2021-11-17/objects/Card#definition__property-merchant_id) field to identify the Square seller that stored the payment card on file. + * Added a [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/Card) object to the response bodies of all [Cards API webhooks](https://developer.squareup.com/docs/webhooks/v2webhook-events-tech-ref#cards-api). The `Card` is added as a child of the `data.object` field in all webhook responses. + +* **Bookings API.** The new [ListBookings](https://developer.squareup.com/reference/square_2021-11-17/bookings-api/list-bookings) endpoint supports browsing a collection of bookings of a seller. For more information, see [Use the Bookings API: list bookings.](https://developer.squareup.com/docs/bookings-api/use-the-api#list-bookings) + +* **Subscriptions API.** Introduced the new [actions framework](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) representing scheduled, future changes to subscriptions. + * The new [PauseSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/pause-subscription) endpoint supports temporarily pausing a subscription. Calling this endpoint schedules a new `PAUSE` action. + * The new [SwapPlan](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/swap-plan) endpoint supports changing the subscription plan associated with a single customer. Calling this endpoint schedules a new `SWAP_PLAN` action. + * The new [DeleteSubscriptionAction](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/delete-subscription-action) endpoint supports deleting a scheduled action. + * The [ResumeSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/resume-subscription) endpoint has been updated to support resuming a paused subscription. Calling this endpoint schedules a new `RESUME` action. + * The [CancelSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/cancel-subscription) endpoint now schedules a new `CANCEL` action. + * Added an optional `include` body parameter to the [SearchSubscriptions](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/search-subscriptions) endpoint. Include `actions` in the request to return all [actions](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) associated with the subscriptions. + +## Documentation Update + +* **Migration Guides.** + * [Migrate from the Connect V1 Refunds API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-refunds) The topic is updated to include information to migrate from the v1 ListRefunds endpoint to the appropriate Square API counterparts. + * [Migrate from the Connect V1 Payments API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-payments) The topic provides developers information to migrate from the Connect V1 Payments API to the appropriate Square API counterparts. + + Code that relies on these V1 API endpoints must be updated to avoid breaking when these APIs reach retirement. + + ## Version 15.0.0.20211020 (2021-10-20) ## API updates * **Transactions API.** Three previously deprecated endpoints (`ListRefunds`, `Charge`, and `CreateRefund`) in the [Transactions API](https://developer.squareup.com/reference/square_2021-10-20/transactions-api) are removed from Square API version 2021-10-20 and later. These endpoints will work if you are using Square API versions prior to 2021-10-20. However, these endpoints will eventually be retired from all Square versions. diff --git a/doc/api/bookings.md b/doc/api/bookings.md index d4ec9e2e..c539ddf8 100644 --- a/doc/api/bookings.md +++ b/doc/api/bookings.md @@ -10,6 +10,7 @@ bookings_api = client.bookings ## Methods +* [List Bookings](/doc/api/bookings.md#list-bookings) * [Create Booking](/doc/api/bookings.md#create-booking) * [Search Availability](/doc/api/bookings.md#search-availability) * [Retrieve Business Booking Profile](/doc/api/bookings.md#retrieve-business-booking-profile) @@ -20,6 +21,54 @@ bookings_api = client.bookings * [Cancel Booking](/doc/api/bookings.md#cancel-booking) +# List Bookings + +Retrieve a collection of bookings. + +```python +def list_bookings(self, + limit=None, + cursor=None, + team_member_id=None, + location_id=None, + start_at_min=None, + start_at_max=None) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `limit` | `int` | Query, Optional | The maximum number of results per page to return in a paged response. | +| `cursor` | `string` | Query, Optional | The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results. | +| `team_member_id` | `string` | Query, Optional | The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved. | +| `location_id` | `string` | Query, Optional | The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved. | +| `start_at_min` | `string` | Query, Optional | The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used. | +| `start_at_max` | `string` | Query, Optional | The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after `start_at_min` is used. | + +## Response Type + +[`List Bookings Response`](/doc/models/list-bookings-response.md) + +## Example Usage + +```python +limit = 172 +cursor = 'cursor6' +team_member_id = 'team_member_id0' +location_id = 'location_id4' +start_at_min = 'start_at_min8' +start_at_max = 'start_at_max8' + +result = bookings_api.list_bookings(limit, cursor, team_member_id, location_id, start_at_min, start_at_max) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + # Create Booking Creates a booking. diff --git a/doc/api/disputes.md b/doc/api/disputes.md index ce796d58..b204eeea 100644 --- a/doc/api/disputes.md +++ b/doc/api/disputes.md @@ -48,7 +48,7 @@ def list_disputes(self, ```python cursor = 'cursor6' -states = 'EVIDENCE_REQUIRED' +states = 'INQUIRY_EVIDENCE_REQUIRED' location_id = 'location_id4' result = disputes_api.list_disputes(cursor, states, location_id) diff --git a/doc/api/gift-card-activities.md b/doc/api/gift-card-activities.md index a85f0627..f426e1bd 100644 --- a/doc/api/gift-card-activities.md +++ b/doc/api/gift-card-activities.md @@ -37,13 +37,13 @@ def list_gift_card_activities(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `gift_card_id` | `string` | Query, Optional | If you provide a gift card ID, the endpoint returns activities that belong
to the specified gift card. Otherwise, the endpoint returns all gift card activities for
the seller. | -| `mtype` | `string` | Query, Optional | If you provide a type, the endpoint returns gift card activities of this type.
Otherwise, the endpoint returns all types of gift card activities. | -| `location_id` | `string` | Query, Optional | If you provide a location ID, the endpoint returns gift card activities for that location.
Otherwise, the endpoint returns gift card activities for all locations. | -| `begin_time` | `string` | Query, Optional | The timestamp for the beginning of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time minus one year. | -| `end_time` | `string` | Query, Optional | The timestamp for the end of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time. | -| `limit` | `int` | Query, Optional | If you provide a limit value, the endpoint returns the specified number
of results (or less) per page. A maximum value is 100. The default value is 50. | -| `cursor` | `string` | 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 you do not provide the cursor, the call returns the first page of the results. | +| `gift_card_id` | `string` | Query, Optional | If a gift card ID is provided, the endpoint returns activities related
to the specified gift card. Otherwise, the endpoint returns all gift card activities for
the seller. | +| `mtype` | `string` | Query, Optional | If a [type](/doc/models/gift-card-activity-type.md) is provided, the endpoint returns gift card activities of the specified type.
Otherwise, the endpoint returns all types of gift card activities. | +| `location_id` | `string` | Query, Optional | If a location ID is provided, the endpoint returns gift card activities for the specified location.
Otherwise, the endpoint returns gift card activities for all locations. | +| `begin_time` | `string` | Query, Optional | The timestamp for the beginning of the reporting period, in RFC 3339 format.
This start time is inclusive. The default value is the current time minus one year. | +| `end_time` | `string` | Query, Optional | The timestamp for the end of the reporting period, in RFC 3339 format.
This end time is inclusive. The default value is the current time. | +| `limit` | `int` | Query, Optional | If a limit is provided, the endpoint returns the specified number
of results (or fewer) per page. The maximum value is 100. The default value is 50.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | +| `cursor` | `string` | 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/working-with-apis/pagination). | | `sort_order` | `string` | Query, Optional | The order in which the endpoint returns the activities, based on `created_at`.

- `ASC` - Oldest to newest.
- `DESC` - Newest to oldest (default). | ## Response Type diff --git a/doc/api/gift-cards.md b/doc/api/gift-cards.md index 8844efa1..174a4340 100644 --- a/doc/api/gift-cards.md +++ b/doc/api/gift-cards.md @@ -37,11 +37,11 @@ def list_gift_cards(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `mtype` | `string` | Query, Optional | If a type is provided, gift cards of this type are returned
(see [GiftCardType](/doc/models/gift-card-type.md)).
If no type is provided, it returns gift cards of all types. | -| `state` | `string` | Query, Optional | If the state is provided, it returns the gift cards in the specified state
(see [GiftCardStatus](/doc/models/gift-card-status.md)).
Otherwise, it returns the gift cards of all states. | -| `limit` | `int` | Query, Optional | If a value is provided, it returns only that number of results per page.
The maximum number of results allowed per page is 50. The default value is 30. | -| `cursor` | `string` | 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, it returns the first page of the results.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | -| `customer_id` | `string` | Query, Optional | If a value is provided, returns only the gift cards linked to the specified customer | +| `mtype` | `string` | Query, Optional | If a [type](/doc/models/gift-card-type.md) is provided, the endpoint returns gift cards of the specified type.
Otherwise, the endpoint returns gift cards of all types. | +| `state` | `string` | Query, Optional | If a [state](/doc/models/gift-card-status.md) is provided, the endpoint returns the gift cards in the specified state.
Otherwise, the endpoint returns the gift cards of all states. | +| `limit` | `int` | Query, Optional | If a limit is provided, the endpoint returns only the specified number of results per page.
The maximum value is 50. The default value is 30.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | +| `cursor` | `string` | 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/working-with-apis/pagination). | +| `customer_id` | `string` | Query, Optional | If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer. | ## Response Type @@ -147,7 +147,7 @@ elif result.is_error(): # Retrieve Gift Card From Nonce -Retrieves a gift card using a nonce (a secure token) that represents the gift card. +Retrieves a gift card using a secure payment token that represents the gift card. ```python def retrieve_gift_card_from_nonce(self, @@ -181,7 +181,7 @@ elif result.is_error(): # Link Customer to Gift Card -Links a customer to a gift card +Links a customer to a gift card, which is also referred to as adding a card on file. ```python def link_customer_to_gift_card(self, @@ -193,7 +193,7 @@ def link_customer_to_gift_card(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `gift_card_id` | `string` | Template, Required | The ID of the gift card to link. | +| `gift_card_id` | `string` | Template, Required | The ID of the gift card to be linked. | | `body` | [`Link Customer to Gift Card Request`](/doc/models/link-customer-to-gift-card-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | ## Response Type @@ -218,7 +218,7 @@ elif result.is_error(): # Unlink Customer From Gift Card -Unlinks a customer from a gift card +Unlinks a customer from a gift card, which is also referred to as removing a card on file. ```python def unlink_customer_from_gift_card(self, @@ -230,7 +230,7 @@ def unlink_customer_from_gift_card(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `gift_card_id` | `string` | Template, Required | - | +| `gift_card_id` | `string` | Template, Required | The ID of the gift card to be unlinked. | | `body` | [`Unlink Customer From Gift Card Request`](/doc/models/unlink-customer-from-gift-card-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | ## Response Type diff --git a/doc/api/sites.md b/doc/api/sites.md index 312905b0..f114e008 100644 --- a/doc/api/sites.md +++ b/doc/api/sites.md @@ -11,7 +11,7 @@ sites_api = client.sites # List Sites -Lists the Square Online sites that belong to a seller. +Lists the Square Online sites that belong to a seller. Sites are listed in descending order by the `created_at` date. __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis). diff --git a/doc/api/subscriptions.md b/doc/api/subscriptions.md index 83f6adff..cb5daaab 100644 --- a/doc/api/subscriptions.md +++ b/doc/api/subscriptions.md @@ -14,14 +14,17 @@ subscriptions_api = client.subscriptions * [Search Subscriptions](/doc/api/subscriptions.md#search-subscriptions) * [Retrieve Subscription](/doc/api/subscriptions.md#retrieve-subscription) * [Update Subscription](/doc/api/subscriptions.md#update-subscription) +* [Delete Subscription Action](/doc/api/subscriptions.md#delete-subscription-action) * [Cancel Subscription](/doc/api/subscriptions.md#cancel-subscription) * [List Subscription Events](/doc/api/subscriptions.md#list-subscription-events) +* [Pause Subscription](/doc/api/subscriptions.md#pause-subscription) * [Resume Subscription](/doc/api/subscriptions.md#resume-subscription) +* [Swap Plan](/doc/api/subscriptions.md#swap-plan) # Create Subscription -Creates a subscription for a customer to a subscription plan. +Creates a subscription to a subscription plan by a customer. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square bills an invoice to the customer's email @@ -74,6 +77,7 @@ elif result.is_error(): # Search Subscriptions Searches for subscriptions. + Results are ordered chronologically by subscription creation date. If the request specifies more than one location ID, the endpoint orders the result @@ -116,6 +120,7 @@ body['query']['filter'] = {} body['query']['filter']['customer_ids'] = ['CHFGVKYY8RSV93M5KCYTG4PN0G'] body['query']['filter']['location_ids'] = ['S8GWD5R9QB376'] body['query']['filter']['source_names'] = ['My App'] +body['include'] = ['include4', 'include5', 'include6'] result = subscriptions_api.search_subscriptions(body) @@ -132,7 +137,8 @@ Retrieves a subscription. ```python def retrieve_subscription(self, - subscription_id) + subscription_id, + include=None) ``` ## Parameters @@ -140,6 +146,7 @@ def retrieve_subscription(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `subscription_id` | `string` | Template, Required | The ID of the subscription to retrieve. | +| `include` | `string` | Query, Optional | A query parameter to specify related information to be included in the response.

The supported query parameter values are:

- `actions`: to include scheduled actions on the targeted subscription. | ## Response Type @@ -149,8 +156,9 @@ def retrieve_subscription(self, ```python subscription_id = 'subscription_id0' +include = 'include2' -result = subscriptions_api.retrieve_subscription(subscription_id) +result = subscriptions_api.retrieve_subscription(subscription_id, include) if result.is_success(): print(result.body) @@ -174,7 +182,7 @@ def update_subscription(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `subscription_id` | `string` | Template, Required | The ID for the subscription to update. | +| `subscription_id` | `string` | Template, Required | The ID of the subscription to update. | | `body` | [`Update Subscription Request`](/doc/models/update-subscription-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | ## Response Type @@ -207,10 +215,47 @@ elif result.is_error(): ``` +# Delete Subscription Action + +Deletes a scheduled action for a subscription. + +```python +def delete_subscription_action(self, + subscription_id, + action_id) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `subscription_id` | `string` | Template, Required | The ID of the subscription the targeted action is to act upon. | +| `action_id` | `string` | Template, Required | The ID of the targeted action to be deleted. | + +## Response Type + +[`Delete Subscription Action Response`](/doc/models/delete-subscription-action-response.md) + +## Example Usage + +```python +subscription_id = 'subscription_id0' +action_id = 'action_id6' + +result = subscriptions_api.delete_subscription_action(subscription_id, action_id) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + # Cancel Subscription -Sets the `canceled_date` field to the end of the active billing period. -After this date, the status changes from ACTIVE to CANCELED. +Schedules a `CANCEL` action to cancel an active subscription +by setting the `canceled_date` field to the end of the active billing period +and changing the subscription status from ACTIVE to CANCELED after this date. ```python def cancel_subscription(self, @@ -258,8 +303,8 @@ def list_subscription_events(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `subscription_id` | `string` | Template, Required | The ID of the subscription to retrieve the events for. | -| `cursor` | `string` | Query, Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | -| `limit` | `int` | Query, Optional | The upper limit on the number of subscription events to return
in the response.

Default: `200` | +| `cursor` | `string` | Query, Optional | When the total number of resulting subscription events exceeds the limit of a paged response,
specify the cursor returned from a preceding response here to fetch the next set of results.
If the cursor is unset, the response contains the last page of the results.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | +| `limit` | `int` | Query, Optional | The upper limit on the number of subscription events to return
in a paged response. | ## Response Type @@ -281,13 +326,55 @@ elif result.is_error(): ``` +# Pause Subscription + +Schedules a `PAUSE` action to pause an active subscription. + +```python +def pause_subscription(self, + subscription_id, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `subscription_id` | `string` | Template, Required | The ID of the subscription to pause. | +| `body` | [`Pause Subscription Request`](/doc/models/pause-subscription-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +[`Pause Subscription Response`](/doc/models/pause-subscription-response.md) + +## Example Usage + +```python +subscription_id = 'subscription_id0' +body = {} +body['pause_effective_date'] = 'pause_effective_date6' +body['pause_cycle_duration'] = 94 +body['resume_effective_date'] = 'resume_effective_date4' +body['resume_change_timing'] = 'IMMEDIATE' +body['pause_reason'] = 'pause_reason2' + +result = subscriptions_api.pause_subscription(subscription_id, body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + # Resume Subscription -Resumes a deactivated subscription. +Schedules a `RESUME` action to resume a paused or a deactivated subscription. ```python def resume_subscription(self, - subscription_id) + subscription_id, + body) ``` ## Parameters @@ -295,6 +382,7 @@ def resume_subscription(self, | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `subscription_id` | `string` | Template, Required | The ID of the subscription to resume. | +| `body` | [`Resume Subscription Request`](/doc/models/resume-subscription-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | ## Response Type @@ -304,8 +392,48 @@ def resume_subscription(self, ```python subscription_id = 'subscription_id0' +body = {} +body['resume_effective_date'] = 'resume_effective_date4' +body['resume_change_timing'] = 'IMMEDIATE' + +result = subscriptions_api.resume_subscription(subscription_id, body) + +if result.is_success(): + print(result.body) +elif result.is_error(): + print(result.errors) +``` + + +# Swap Plan + +Schedules a `SWAP_PLAN` action to swap a subscription plan in an existing subscription. + +```python +def swap_plan(self, + subscription_id, + body) +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `subscription_id` | `string` | Template, Required | The ID of the subscription to swap the subscription plan for. | +| `body` | [`Swap Plan Request`](/doc/models/swap-plan-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +[`Swap Plan Response`](/doc/models/swap-plan-response.md) + +## Example Usage + +```python +subscription_id = 'subscription_id0' +body = {} +body['new_plan_id'] = 'new_plan_id2' -result = subscriptions_api.resume_subscription(subscription_id) +result = subscriptions_api.swap_plan(subscription_id, body) if result.is_success(): print(result.body) diff --git a/doc/client.md b/doc/client.md index 8ba641b0..1b38cbb1 100644 --- a/doc/client.md +++ b/doc/client.md @@ -5,10 +5,12 @@ The following parameters are configurable for the API Client: | Parameter | Type | Description | | --- | --- | --- | -| `square_version` | `string` | Square Connect API versions
*Default*: `'2021-10-20'` | +| `square_version` | `string` | Square Connect API versions
*Default*: `'2021-11-17'` | | `access_token` | `string` | The OAuth 2.0 Access Token to use for API requests. | | `custom_url` | `string` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
*Default*: `'https://connect.squareup.com'` | | `environment` | `string` | The API environment.
**Default: `production`** | +| `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests | +| `override_http_client_configuration` | `bool` | The value which determines to override properties of the passed Http Client from the sdk user | | `timeout` | `float` | The value to use for connection timeout.
**Default: 60** | | `max_retries` | `int` | The number of times to retry an endpoint call if it fails.
**Default: 0** | | `backoff_factor` | `float` | A backoff factor to apply between attempts after the second try.
**Default: 2** | @@ -22,7 +24,7 @@ The API client can be initialized as follows: from square.client import Client client = Client( - square_version='2021-10-20', + square_version='2021-11-17', access_token='AccessToken', environment='production', custom_url = 'https://connect.squareup.com',) @@ -47,7 +49,7 @@ API calls return an `ApiResponse` object that includes the following fields: from square.client import Client client = Client( - square_version='2021-10-20', + square_version='2021-11-17', access_token='AccessToken',) locations_api = client.locations diff --git a/doc/models/booking.md b/doc/models/booking.md index 893c550f..738aabdd 100644 --- a/doc/models/booking.md +++ b/doc/models/booking.md @@ -19,7 +19,7 @@ at a given location to a requesting customer in one or more appointment segments | `updated_at` | `string` | Optional | The timestamp specifying the most recent update time of this booking, in RFC 3339 format. | | `start_at` | `string` | Optional | The timestamp specifying the starting time of this booking, in RFC 3339 format. | | `location_id` | `string` | Optional | The ID of the [Location](/doc/models/location.md) object representing the location where the booked service is provided. | -| `customer_id` | `string` | Optional | The ID of the [Customer](/doc/models/customer.md) object representing the customer attending this booking | +| `customer_id` | `string` | Optional | The ID of the [Customer](/doc/models/customer.md) object representing the customer receiving the booked service. | | `customer_note` | `string` | Optional | The free-text field for the customer to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a relevant [CatalogObject](/doc/models/catalog-object.md) instance.
**Constraints**: *Maximum Length*: `4096` | | `seller_note` | `string` | Optional | The free-text field for the seller to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a specific [CatalogObject](/doc/models/catalog-object.md) instance.
This field should not be visible to customers.
**Constraints**: *Maximum Length*: `4096` | | `appointment_segments` | [`List of Appointment Segment`](/doc/models/appointment-segment.md) | Optional | A list of appointment segments for this booking. | diff --git a/doc/models/cancel-subscription-response.md b/doc/models/cancel-subscription-response.md index f5df7256..3bce0acd 100644 --- a/doc/models/cancel-subscription-response.md +++ b/doc/models/cancel-subscription-response.md @@ -1,8 +1,8 @@ # Cancel Subscription Response -Defines fields that are included in a -[CancelSubscription](/doc/api/subscriptions.md#cancel-subscription) response. +Defines output parameters in a response from the +[CancelSubscription](/doc/api/subscriptions.md#cancel-subscription) endpoint. ## Structure @@ -12,8 +12,9 @@ Defines fields that are included in a | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information about errors encountered during the request. | -| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a customer subscription to a subscription plan.
For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `actions` | [`List of Subscription Action`](/doc/models/subscription-action.md) | Optional | A list of a single `CANCEL` action scheduled for the subscription. | ## Example (as JSON) diff --git a/doc/models/card-square-product.md b/doc/models/card-square-product.md index 4022095d..d5de0cfc 100644 --- a/doc/models/card-square-product.md +++ b/doc/models/card-square-product.md @@ -19,4 +19,5 @@ | `GIFT_CARD` | | `VIRTUAL_TERMINAL` | | `READER_SDK` | +| `SQUARE_PROFILE` | diff --git a/doc/models/card.md b/doc/models/card.md index 4c50dd8f..bb5bdab7 100644 --- a/doc/models/card.md +++ b/doc/models/card.md @@ -21,6 +21,7 @@ details are determined by the payment token generated by Web Payments SDK. | `billing_address` | [`Address`](/doc/models/address.md) | Optional | Represents a postal address in a country. The address format is based
on an [open-source library from Google](https://github.com/google/libaddressinput). For more information,
see [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
`Address` object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.

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

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

When it comes to localization, the seller's language preferences
(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences))
are ignored for addresses. Even though Square products (such as Square Point of Sale
and the Seller Dashboard) mostly use a seller's language preference in
communication, when it comes to addresses, they will use English for a US address,
Japanese for an address in Japan, and so on. | | `fingerprint` | `string` | Optional | Intended as a Square-assigned identifier, based
on the card number, to identify the card across multiple locations within a
single application.
**Constraints**: *Maximum Length*: `255` | | `customer_id` | `string` | Optional | The ID of a customer created using the Customers API to be associated with the card. | +| `merchant_id` | `string` | Optional | The ID of the merchant associated with the card. | | `reference_id` | `string` | Optional | An optional user-defined reference ID that associates this card with
another entity in an external system. For example, a customer ID from an
external customer management system.
**Constraints**: *Maximum Length*: `128` | | `enabled` | `bool` | Optional | Indicates whether or not a card can be used for payments. | | `card_type` | [`str (Card Type)`](/doc/models/card-type.md) | Optional | Indicates a card's type, such as `CREDIT` or `DEBIT`. | diff --git a/doc/models/change-timing.md b/doc/models/change-timing.md new file mode 100644 index 00000000..1c55f966 --- /dev/null +++ b/doc/models/change-timing.md @@ -0,0 +1,16 @@ + +# Change Timing + +Supported timings when a pending change, as an action, takes place to a subscription. + +## Enumeration + +`Change Timing` + +## Fields + +| Name | Description | +| --- | --- | +| `IMMEDIATE` | The action occurs immediately. | +| `END_OF_BILLING_CYCLE` | The action occurs at the end of the billing cycle. | + diff --git a/doc/models/create-card-response.md b/doc/models/create-card-response.md index d5dab2ed..6f0df648 100644 --- a/doc/models/create-card-response.md +++ b/doc/models/create-card-response.md @@ -2,7 +2,7 @@ # Create Card Response Defines the fields that are included in the response body of -a request to the [CreateCard](#endpoint-cards-createcard) endpoint. +a request to the [CreateCard](/doc/api/cards.md#create-card) endpoint. Note: if there are errors processing the request, the card field will not be present. @@ -42,6 +42,7 @@ present. "fingerprint": "ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q", "id": "ccof:uIbfJXhXETSP197M3GB", "last_4": "1111", + "merchant_id": "6SSW7HV8K2ST5", "prepaid_type": "NOT_PREPAID", "reference_id": "user-id-1", "version": 1 diff --git a/doc/models/create-subscription-request.md b/doc/models/create-subscription-request.md index cd468e92..612f8306 100644 --- a/doc/models/create-subscription-request.md +++ b/doc/models/create-subscription-request.md @@ -1,8 +1,8 @@ # Create Subscription Request -Defines parameters in a -[CreateSubscription](/doc/api/subscriptions.md#create-subscription) endpoint request. +Defines input parameters in a request to the +[CreateSubscription](/doc/api/subscriptions.md#create-subscription) endpoint. ## Structure @@ -15,12 +15,12 @@ Defines parameters in a | `idempotency_key` | `string` | Optional | A unique string that identifies this `CreateSubscription` request.
If you do not provide a unique string (or provide an empty string as the value),
the endpoint treats each request as independent.

For more information, see [Idempotency keys](https://developer.squareup.com/docs/working-with-apis/idempotency). | | `location_id` | `string` | Required | The ID of the location the subscription is associated with.
**Constraints**: *Minimum Length*: `1` | | `plan_id` | `string` | Required | The ID of the subscription plan created using the Catalog API.
For more information, see
[Set Up and Manage a Subscription Plan](https://developer.squareup.com/docs/subscriptions-api/setup-plan) and
[Subscriptions Walkthrough](https://developer.squareup.com/docs/subscriptions-api/walkthrough).
**Constraints**: *Minimum Length*: `1` | -| `customer_id` | `string` | Required | The ID of the [customer](/doc/models/customer.md) profile.
**Constraints**: *Minimum Length*: `1` | -| `start_date` | `string` | Optional | The start date of the subscription, in YYYY-MM-DD format. For example,
2013-01-15. If the start date is left empty, the subscription begins
immediately. | -| `canceled_date` | `string` | Optional | The date when the subscription should be canceled, in
YYYY-MM-DD format (for example, 2025-02-29). This overrides the plan configuration
if it comes before the date the subscription would otherwise end. | +| `customer_id` | `string` | Required | The ID of the [customer](/doc/models/customer.md) subscribing to the subscription plan.
**Constraints**: *Minimum Length*: `1` | +| `start_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date to start the subscription.
If it is unspecified, the subscription starts immediately. | +| `canceled_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date when the newly created subscription is scheduled for cancellation.

This date overrides the cancellation date set in the plan configuration.
If the cancellation date is earlier than the end date of a subscription cycle, the subscription stops
at the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle.

When the subscription plan of the newly created subscription has a fixed number of cycles and the `canceled_date`
occurs before the subscription plan expires, the specified `canceled_date` sets the date when the subscription
stops through the end of the last cycle. | | `tax_percentage` | `string` | Optional | The tax to add when billing the subscription.
The percentage is expressed in decimal form, using a `'.'` as the decimal
separator and without a `'%'` sign. For example, a value of 7.5
corresponds to 7.5%.
**Constraints**: *Maximum Length*: `10` | | `price_override_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. | -| `card_id` | `string` | Optional | The ID of the [customer](/doc/models/customer.md) [card](/doc/models/card.md) to charge.
If not specified, Square sends an invoice via email. For an example to
create a customer and add a card on file, see [Subscriptions Walkthrough](https://developer.squareup.com/docs/subscriptions-api/walkthrough). | +| `card_id` | `string` | Optional | The ID of the [subscriber's](/doc/models/customer.md) [card](/doc/models/card.md) to charge.
If it is not specified, the subscriber receives an invoice via email. For an example to
create a customer profile for a subscriber and add a card on file, see [Subscriptions Walkthrough](https://developer.squareup.com/docs/subscriptions-api/walkthrough). | | `timezone` | `string` | Optional | The timezone that is used in date calculations for the subscription. If unset, defaults to
the location timezone. If a timezone is not configured for the location, defaults to "America/New_York".
Format: the IANA Timezone Database identifier for the location timezone. For
a list of time zones, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `source` | [`Subscription Source`](/doc/models/subscription-source.md) | Optional | The origination details of the subscription. | diff --git a/doc/models/create-subscription-response.md b/doc/models/create-subscription-response.md index 05050de5..cda56def 100644 --- a/doc/models/create-subscription-response.md +++ b/doc/models/create-subscription-response.md @@ -1,7 +1,7 @@ # Create Subscription Response -Defines the fields that are included in the response from the +Defines output parameters in a response from the [CreateSubscription](/doc/api/subscriptions.md#create-subscription) endpoint. ## Structure @@ -12,8 +12,8 @@ Defines the fields that are included in the response from the | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information about errors encountered during the request. | -| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a customer subscription to a subscription plan.
For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | ## Example (as JSON) diff --git a/doc/models/delete-subscription-action-response.md b/doc/models/delete-subscription-action-response.md new file mode 100644 index 00000000..441eedac --- /dev/null +++ b/doc/models/delete-subscription-action-response.md @@ -0,0 +1,47 @@ + +# Delete Subscription Action Response + +Defines output parameters in a response of the [DeleteSubscriptionAction](/doc/api/subscriptions.md#delete-subscription-action) +endpoint. + +## Structure + +`Delete Subscription Action Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | + +## Example (as JSON) + +```json +{ + "subscription": { + "charged_through_date": "2021-11-20", + "created_at": "2021-10-20T21:53:10Z", + "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", + "id": "8151fc89-da15-4eb9-a685-1a70883cebfc", + "invoice_ids": [ + "grebK0Q_l8H4fqoMMVvt-Q", + "rcX_i3sNmHTGKhI4W2mceA" + ], + "location_id": "S8GWD5R9QB376", + "paid_until_date": "2021-11-20", + "plan_id": "6JHXF3B2CW3YKHDV4XEM674H", + "price_override_money": { + "amount": 1000, + "currency": "USD" + }, + "source": { + "name": "My App" + }, + "start_date": "2021-10-20", + "status": "ACTIVE", + "timezone": "America/Los_Angeles" + } +} +``` + diff --git a/doc/models/device-code.md b/doc/models/device-code.md index 72b764d1..108aec85 100644 --- a/doc/models/device-code.md +++ b/doc/models/device-code.md @@ -13,7 +13,7 @@ | `name` | `string` | Optional | An optional user-defined name for the device code.
**Constraints**: *Maximum Length*: `128` | | `code` | `string` | Optional | The unique code that can be used to login. | | `device_id` | `string` | Optional | The unique id of the device that used this code. Populated when the device is paired up. | -| `product_type` | `string` | Required, Constant | **Default**: `'TERMINAL_API'`
*Default: `'TERMINAL_API'`* | +| `product_type` | `string` | Required, Constant | **Default**: `'TERMINAL_API'` | | `location_id` | `string` | Optional | The location assigned to this code.
**Constraints**: *Maximum Length*: `50` | | `status` | [`str (Device Code Status)`](/doc/models/device-code-status.md) | Optional | DeviceCode.Status enum. | | `pair_by` | `string` | Optional | When this DeviceCode will expire and no longer login. Timestamp in RFC 3339 format. | diff --git a/doc/models/disable-card-response.md b/doc/models/disable-card-response.md index fd2129e4..9c094c2d 100644 --- a/doc/models/disable-card-response.md +++ b/doc/models/disable-card-response.md @@ -2,7 +2,7 @@ # Disable Card Response Defines the fields that are included in the response body of -a request to the [DisableCard](#endpoint-cards-disablecard) endpoint. +a request to the [DisableCard](/doc/api/cards.md#disable-card) endpoint. Note: if there are errors processing the request, the card field will not be present. @@ -42,6 +42,7 @@ present. "fingerprint": "ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q", "id": "ccof:uIbfJXhXETSP197M3GB", "last_4": "1111", + "merchant_id": "6SSW7HV8K2ST5", "prepaid_type": "NOT_PREPAID", "reference_id": "user-id-1", "version": 2 diff --git a/doc/models/dispute-evidence-created-webhook-data.md b/doc/models/dispute-evidence-created-webhook-data.md index 0ccf2370..bfa75104 100644 --- a/doc/models/dispute-evidence-created-webhook-data.md +++ b/doc/models/dispute-evidence-created-webhook-data.md @@ -28,7 +28,7 @@ "currency": "NGN" }, "reason": "NOT_AS_DESCRIBED", - "state": "EVIDENCE_REQUIRED" + "state": "PROCESSING" } } } diff --git a/doc/models/dispute-evidence-created-webhook-object.md b/doc/models/dispute-evidence-created-webhook-object.md index e4ce7e7f..df41366e 100644 --- a/doc/models/dispute-evidence-created-webhook-object.md +++ b/doc/models/dispute-evidence-created-webhook-object.md @@ -23,7 +23,7 @@ "currency": "HRK" }, "reason": "DUPLICATE", - "state": "ACCEPTED" + "state": "PROCESSING" } } ``` diff --git a/doc/models/dispute-state.md b/doc/models/dispute-state.md index 6f3f0a3d..e306937f 100644 --- a/doc/models/dispute-state.md +++ b/doc/models/dispute-state.md @@ -9,16 +9,14 @@ The list of possible dispute states. ## Fields -| Name | -| --- | -| `UNKNOWN_STATE` | -| `INQUIRY_EVIDENCE_REQUIRED` | -| `INQUIRY_PROCESSING` | -| `INQUIRY_CLOSED` | -| `EVIDENCE_REQUIRED` | -| `PROCESSING` | -| `WON` | -| `LOST` | -| `ACCEPTED` | -| `WAITING_THIRD_PARTY` | +| Name | Description | +| --- | --- | +| `INQUIRY_EVIDENCE_REQUIRED` | The initial state of an inquiry with evidence required | +| `INQUIRY_PROCESSING` | Inquiry evidence has been submitted and the bank is processing the inquiry | +| `INQUIRY_CLOSED` | The inquiry is complete | +| `EVIDENCE_REQUIRED` | The initial state of a dispute with evidence required | +| `PROCESSING` | Dispute evidence has been submitted and the bank is processing the dispute | +| `WON` | The bank has completed processing the dispute and the seller has won | +| `LOST` | The bank has completed processing the dispute and the seller has lost | +| `ACCEPTED` | The seller has accepted the dispute | diff --git a/doc/models/dispute.md b/doc/models/dispute.md index 1592d107..99ec1a36 100644 --- a/doc/models/dispute.md +++ b/doc/models/dispute.md @@ -39,7 +39,7 @@ Represents a dispute a cardholder initiated with their bank. "currency": "NGN" }, "reason": "NOT_AS_DESCRIBED", - "state": "EVIDENCE_REQUIRED" + "state": "PROCESSING" } ``` diff --git a/doc/models/error-code.md b/doc/models/error-code.md index ba93d3d2..103389e0 100644 --- a/doc/models/error-code.md +++ b/doc/models/error-code.md @@ -62,6 +62,10 @@ Square API. | `TOO_MANY_MAP_ENTRIES` | Too many entries in the map field. | | `MAP_KEY_LENGTH_TOO_SHORT` | The length of one of the provided keys in the map is too short. | | `MAP_KEY_LENGTH_TOO_LONG` | The length of one of the provided keys in the map is too long. | +| `CUSTOMER_MISSING_NAME` | The provided customer does not have a recorded name. | +| `CUSTOMER_MISSING_EMAIL` | The provided customer does not have a recorded email. | +| `INVALID_PAUSE_LENGTH` | The subscription cannot be paused longer than the duration of the current phase. | +| `INVALID_DATE` | The subscription cannot be paused/resumed on the given date. | | `CARD_EXPIRED` | The card issuer declined the request because the card is expired. | | `INVALID_EXPIRATION` | The expiration date for the payment card is invalid. For example,
it indicates a date in the past. | | `INVALID_EXPIRATION_YEAR` | The expiration year for the payment card is invalid. For example,
it indicates a year in the past or contains invalid characters. | diff --git a/doc/models/error.md b/doc/models/error.md index 68520d03..eb20a630 100644 --- a/doc/models/error.md +++ b/doc/models/error.md @@ -23,7 +23,7 @@ See [Handling errors](https://developer.squareup.com/docs/build-basics/handling- ```json { "category": "RATE_LIMIT_ERROR", - "code": "ARRAY_EMPTY", + "code": "INVALID_EXPIRATION_DATE", "detail": "detail6", "field": "field6" } diff --git a/doc/models/gift-card-activity-block.md b/doc/models/gift-card-activity-block.md index c48c8241..e26dc14e 100644 --- a/doc/models/gift-card-activity-block.md +++ b/doc/models/gift-card-activity-block.md @@ -11,7 +11,7 @@ Describes a gift card activity of the BLOCK type. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_BLOCK'`
*Default: `'CHARGEBACK_BLOCK'`* | +| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_BLOCK'` | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-type.md b/doc/models/gift-card-activity-type.md index 7c151a08..b7741655 100644 --- a/doc/models/gift-card-activity-type.md +++ b/doc/models/gift-card-activity-type.md @@ -1,6 +1,8 @@ # Gift Card Activity Type +Indicates the gift card activity type. + ## Enumeration `Gift Card Activity Type` diff --git a/doc/models/gift-card-activity-unblock.md b/doc/models/gift-card-activity-unblock.md index e7fc1b4e..14633ba4 100644 --- a/doc/models/gift-card-activity-unblock.md +++ b/doc/models/gift-card-activity-unblock.md @@ -11,7 +11,7 @@ Present only when `GiftCardActivityType` is UNBLOCK. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_UNBLOCK'`
*Default: `'CHARGEBACK_UNBLOCK'`* | +| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_UNBLOCK'` | ## Example (as JSON) diff --git a/doc/models/gift-card-activity.md b/doc/models/gift-card-activity.md index 39d77a4c..90a2e5c4 100644 --- a/doc/models/gift-card-activity.md +++ b/doc/models/gift-card-activity.md @@ -12,7 +12,7 @@ Represents an action performed on a gift card that affects its state or balance. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `id` | `string` | Optional | The unique ID of the gift card activity. | -| `type` | [`str (Gift Card Activity Type)`](/doc/models/gift-card-activity-type.md) | Required | - | +| `type` | [`str (Gift Card Activity Type)`](/doc/models/gift-card-activity-type.md) | Required | Indicates the gift card activity type. | | `location_id` | `string` | Required | The ID of the location at which the activity occurred. | | `created_at` | `string` | Optional | The timestamp when the gift card activity was created, in RFC 3339 format. | | `gift_card_id` | `string` | Optional | The gift card ID. The ID is not required if a GAN is present. | diff --git a/doc/models/gift-card-type.md b/doc/models/gift-card-type.md index 45a384eb..7913227b 100644 --- a/doc/models/gift-card-type.md +++ b/doc/models/gift-card-type.md @@ -1,6 +1,8 @@ # Gift Card Type +Indicates the gift card type. + ## Enumeration `Gift Card Type` diff --git a/doc/models/gift-card.md b/doc/models/gift-card.md index df5090fd..0304a897 100644 --- a/doc/models/gift-card.md +++ b/doc/models/gift-card.md @@ -12,7 +12,7 @@ Represents a Square gift card. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `id` | `string` | Optional | The Square-assigned ID of the gift card. | -| `type` | [`str (Gift Card Type)`](/doc/models/gift-card-type.md) | Required | - | +| `type` | [`str (Gift Card Type)`](/doc/models/gift-card-type.md) | Required | Indicates the gift card type. | | `gan_source` | [`str (Gift Card GAN Source)`](/doc/models/gift-card-gan-source.md) | Optional | Indicates the source that generated the gift card
account number (GAN). | | `state` | [`str (Gift Card Status)`](/doc/models/gift-card-status.md) | Optional | Indicates the gift card state. | | `balance_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/invoice-sort.md b/doc/models/invoice-sort.md index bace148e..c83c4453 100644 --- a/doc/models/invoice-sort.md +++ b/doc/models/invoice-sort.md @@ -11,7 +11,7 @@ Identifies the sort field and sort order. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `field` | `string` | Required, Constant | The field to use for sorting.
**Default**: `'INVOICE_SORT_DATE'`
*Default: `'INVOICE_SORT_DATE'`* | +| `field` | `string` | Required, Constant | The field to use for sorting.
**Default**: `'INVOICE_SORT_DATE'` | | `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. | ## Example (as JSON) diff --git a/doc/models/link-customer-to-gift-card-request.md b/doc/models/link-customer-to-gift-card-request.md index 39fb091d..07abd227 100644 --- a/doc/models/link-customer-to-gift-card-request.md +++ b/doc/models/link-customer-to-gift-card-request.md @@ -1,7 +1,7 @@ # Link Customer to Gift Card Request -A request to link a customer to a gift card +A request to link a customer to a gift card. ## Structure @@ -11,7 +11,7 @@ A request to link a customer to a gift card | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `customer_id` | `string` | Required | The ID of the customer to be linked.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | +| `customer_id` | `string` | Required | The ID of the customer to link to the gift card.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | ## Example (as JSON) diff --git a/doc/models/link-customer-to-gift-card-response.md b/doc/models/link-customer-to-gift-card-response.md index df9058b0..3d17ec41 100644 --- a/doc/models/link-customer-to-gift-card-response.md +++ b/doc/models/link-customer-to-gift-card-response.md @@ -1,8 +1,8 @@ # Link Customer to Gift Card Response -A response that contains one `GiftCard` that was linked. The response might contain a set of `Error` -objects if the request resulted in errors. +A response that contains the linked `GiftCard` object. If the request resulted in errors, +the response contains a set of `Error` objects. ## Structure diff --git a/doc/models/list-bookings-request.md b/doc/models/list-bookings-request.md new file mode 100644 index 00000000..8e12a0a9 --- /dev/null +++ b/doc/models/list-bookings-request.md @@ -0,0 +1,30 @@ + +# List Bookings Request + +## Structure + +`List Bookings Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `limit` | `int` | Optional | The maximum number of results per page to return in a paged response.
**Constraints**: `>= 1`, `<= 10000` | +| `cursor` | `string` | Optional | The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results. | +| `team_member_id` | `string` | Optional | The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved. | +| `location_id` | `string` | Optional | The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved. | +| `start_at_min` | `string` | Optional | The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used. | +| `start_at_max` | `string` | Optional | The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after `start_at_min` is used. | + +## Example (as JSON) + +```json +{ + "limit": 172, + "cursor": "cursor6", + "team_member_id": "team_member_id0", + "location_id": "location_id4", + "start_at_min": "start_at_min8" +} +``` + diff --git a/doc/models/list-bookings-response.md b/doc/models/list-bookings-response.md new file mode 100644 index 00000000..47aaaf7d --- /dev/null +++ b/doc/models/list-bookings-response.md @@ -0,0 +1,46 @@ + +# List Bookings Response + +## Structure + +`List Bookings Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `bookings` | [`List of Booking`](/doc/models/booking.md) | Optional | The list of targeted bookings. | +| `cursor` | `string` | Optional | The pagination cursor to be used in the following request to get the next page of the results. Stop retrieving the next page of the results when the cursor is not set. | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | + +## Example (as JSON) + +```json +{ + "bookings": [ + { + "appointment_segments": [ + { + "duration_minutes": 60, + "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC", + "service_variation_version": 1599775456731, + "team_member_id": "TMXUrsBWWcHTt79t" + } + ], + "created_at": "2020-10-28T15:47:41Z", + "customer_id": "EX2QSVGTZN4K1E5QE1CBFNVQ8M", + "customer_note": "", + "id": "zkras0xv0xwswx", + "location_id": "LEQHH0YY8B42M", + "seller_note": "", + "start_at": "2020-11-26T13:00:00Z", + "status": "ACCEPTED", + "updated_at": "2020-10-28T15:49:25Z", + "version": 1 + } + ], + "cursor": "null", + "errors": [] +} +``` + diff --git a/doc/models/list-cards-response.md b/doc/models/list-cards-response.md index 20f4166f..19930ee8 100644 --- a/doc/models/list-cards-response.md +++ b/doc/models/list-cards-response.md @@ -2,7 +2,7 @@ # List Cards Response Defines the fields that are included in the response body of -a request to the [ListCards](#endpoint-cards-listcards) endpoint. +a request to the [ListCards](/doc/api/cards.md#list-cards) endpoint. Note: if there are errors processing the request, the card field will not be present. @@ -45,6 +45,7 @@ present. "fingerprint": "ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q", "id": "ccof:uIbfJXhXETSP197M3GB", "last_4": "1111", + "merchant_id": "6SSW7HV8K2ST5", "prepaid_type": "NOT_PREPAID", "reference_id": "user-id-1", "version": 1 diff --git a/doc/models/list-employees-response.md b/doc/models/list-employees-response.md index ddd9b6b3..d7052734 100644 --- a/doc/models/list-employees-response.md +++ b/doc/models/list-employees-response.md @@ -30,19 +30,19 @@ "errors": [ { "category": "AUTHENTICATION_ERROR", - "code": "UNPROCESSABLE_ENTITY", + "code": "MISSING_PIN", "detail": "detail1", "field": "field9" }, { "category": "INVALID_REQUEST_ERROR", - "code": "RATE_LIMITED", + "code": "MISSING_ACCOUNT_TYPE", "detail": "detail2", "field": "field0" }, { "category": "RATE_LIMIT_ERROR", - "code": "NOT_IMPLEMENTED", + "code": "INVALID_POSTAL_CODE", "detail": "detail3", "field": "field1" } diff --git a/doc/models/list-gift-card-activities-request.md b/doc/models/list-gift-card-activities-request.md index bf67ee25..6579827d 100644 --- a/doc/models/list-gift-card-activities-request.md +++ b/doc/models/list-gift-card-activities-request.md @@ -12,13 +12,13 @@ subset of activites. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `gift_card_id` | `string` | Optional | If you provide a gift card ID, the endpoint returns activities that belong
to the specified gift card. Otherwise, the endpoint returns all gift card activities for
the seller.
**Constraints**: *Maximum Length*: `50` | -| `type` | `string` | Optional | If you provide a type, the endpoint returns gift card activities of this type.
Otherwise, the endpoint returns all types of gift card activities. | -| `location_id` | `string` | Optional | If you provide a location ID, the endpoint returns gift card activities for that location.
Otherwise, the endpoint returns gift card activities for all locations. | -| `begin_time` | `string` | Optional | The timestamp for the beginning of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time minus one year. | -| `end_time` | `string` | Optional | The timestamp for the end of the reporting period, in RFC 3339 format.
Inclusive. Default: The current time. | -| `limit` | `int` | Optional | If you provide a limit value, the endpoint returns the specified number
of results (or less) per page. A maximum value is 100. The default value is 50.
**Constraints**: `>= 1`, `<= 100` | -| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If you do not provide the cursor, the call returns the first page of the results. | +| `gift_card_id` | `string` | Optional | If a gift card ID is provided, the endpoint returns activities related
to the specified gift card. Otherwise, the endpoint returns all gift card activities for
the seller.
**Constraints**: *Maximum Length*: `50` | +| `type` | `string` | Optional | If a [type](/doc/models/gift-card-activity-type.md) is provided, the endpoint returns gift card activities of the specified type.
Otherwise, the endpoint returns all types of gift card activities. | +| `location_id` | `string` | Optional | If a location ID is provided, the endpoint returns gift card activities for the specified location.
Otherwise, the endpoint returns gift card activities for all locations. | +| `begin_time` | `string` | Optional | The timestamp for the beginning of the reporting period, in RFC 3339 format.
This start time is inclusive. The default value is the current time minus one year. | +| `end_time` | `string` | Optional | The timestamp for the end of the reporting period, in RFC 3339 format.
This end time is inclusive. The default value is the current time. | +| `limit` | `int` | Optional | If a limit is provided, the endpoint returns the specified number
of results (or fewer) per page. The maximum value is 100. The default value is 50.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
**Constraints**: `>= 1`, `<= 100` | +| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for 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/working-with-apis/pagination). | | `sort_order` | `string` | Optional | The order in which the endpoint returns the activities, based on `created_at`.

- `ASC` - Oldest to newest.
- `DESC` - Newest to oldest (default). | ## Example (as JSON) diff --git a/doc/models/list-gift-card-activities-response.md b/doc/models/list-gift-card-activities-response.md index e493e76a..684dab88 100644 --- a/doc/models/list-gift-card-activities-response.md +++ b/doc/models/list-gift-card-activities-response.md @@ -1,8 +1,8 @@ # List Gift Card Activities Response -A response that contains one or more `GiftCardActivity`. The response might contain a set of `Error` objects -if the request resulted in errors. +A response that contains a list of `GiftCardActivity` objects. If the request resulted in errors, +the response contains a set of `Error` objects. ## Structure @@ -13,8 +13,8 @@ if the request resulted in errors. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `gift_card_activities` | [`List of Gift Card Activity`](/doc/models/gift-card-activity.md) | Optional | Gift card activities retrieved. | -| `cursor` | `string` | Optional | When a response is truncated, it includes a cursor that you can use in a
subsequent request to fetch the next set of activities. If empty, this is
the final response. | +| `gift_card_activities` | [`List of Gift Card Activity`](/doc/models/gift-card-activity.md) | Optional | The requested gift card activities or an empty object if none are found. | +| `cursor` | `string` | Optional | When a response is truncated, it includes a cursor that you can use in a
subsequent request to retrieve the next set of activities. If a cursor is not present, this is
the final response.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | ## Example (as JSON) diff --git a/doc/models/list-gift-cards-request.md b/doc/models/list-gift-cards-request.md index 2f5908fb..dde3d2fe 100644 --- a/doc/models/list-gift-cards-request.md +++ b/doc/models/list-gift-cards-request.md @@ -12,11 +12,11 @@ gift cards. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `type` | `string` | Optional | If a type is provided, gift cards of this type are returned
(see [GiftCardType](/doc/models/gift-card-type.md)).
If no type is provided, it returns gift cards of all types. | -| `state` | `string` | Optional | If the state is provided, it returns the gift cards in the specified state
(see [GiftCardStatus](/doc/models/gift-card-status.md)).
Otherwise, it returns the gift cards of all states. | -| `limit` | `int` | Optional | If a value is provided, it returns only that number of results per page.
The maximum number of results allowed per page is 50. The default value is 30.
**Constraints**: `>= 1`, `<= 50` | -| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If a cursor is not provided, it returns the first page of the results.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | -| `customer_id` | `string` | Optional | If a value is provided, returns only the gift cards linked to the specified customer
**Constraints**: *Maximum Length*: `191` | +| `type` | `string` | Optional | If a [type](/doc/models/gift-card-type.md) is provided, the endpoint returns gift cards of the specified type.
Otherwise, the endpoint returns gift cards of all types. | +| `state` | `string` | Optional | If a [state](/doc/models/gift-card-status.md) is provided, the endpoint returns the gift cards in the specified state.
Otherwise, the endpoint returns the gift cards of all states. | +| `limit` | `int` | Optional | If a limit is provided, the endpoint returns only the specified number of results per page.
The maximum value is 50. The default value is 30.
For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
**Constraints**: `>= 1`, `<= 50` | +| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for 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/working-with-apis/pagination). | +| `customer_id` | `string` | Optional | If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.
**Constraints**: *Maximum Length*: `191` | ## Example (as JSON) diff --git a/doc/models/list-gift-cards-response.md b/doc/models/list-gift-cards-response.md index 33f61914..35889f65 100644 --- a/doc/models/list-gift-cards-response.md +++ b/doc/models/list-gift-cards-response.md @@ -1,8 +1,8 @@ # List Gift Cards Response -A response that contains one or more `GiftCard`. The response might contain a set of `Error` -objects if the request resulted in errors. +A response that contains a list of `GiftCard` objects. If the request resulted in errors, +the response contains a set of `Error` objects. ## Structure @@ -13,8 +13,8 @@ objects if the request resulted in errors. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`List of Error`](/doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `gift_cards` | [`List of Gift Card`](/doc/models/gift-card.md) | Optional | Gift cards retrieved. | -| `cursor` | `string` | Optional | When a response is truncated, it includes a cursor that you can use in a
subsequent request to fetch the next set of gift cards. If empty, this is
the final response. | +| `gift_cards` | [`List of Gift Card`](/doc/models/gift-card.md) | Optional | The requested gift cards or an empty object if none are found. | +| `cursor` | `string` | 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/working-with-apis/pagination). | ## Example (as JSON) diff --git a/doc/models/list-loyalty-programs-response.md b/doc/models/list-loyalty-programs-response.md index eec41aa4..855762bb 100644 --- a/doc/models/list-loyalty-programs-response.md +++ b/doc/models/list-loyalty-programs-response.md @@ -33,7 +33,8 @@ A response that contains all loyalty programs. ], "points": 1, "spend_amount_money": { - "amount": 100 + "amount": 100, + "currency": "USD" } } ], diff --git a/doc/models/list-sites-response.md b/doc/models/list-sites-response.md index a433c794..2e200448 100644 --- a/doc/models/list-sites-response.md +++ b/doc/models/list-sites-response.md @@ -20,20 +20,20 @@ Represents a `ListSites` response. The response can include either `sites` or `e { "sites": [ { - "created_at": "2020-02-28T13:22:51Z", - "domain": "mysite1.square.site", + "created_at": "2020-10-28T13:22:51.000000Z", + "domain": "mysite2.square.site", "id": "site_278075276488921835", - "is_published": true, - "site_title": "My First Site", - "updated_at": "2021-01-13T09:58:32Z" + "is_published": false, + "site_title": "My Second Site", + "updated_at": "2020-10-28T13:22:51.000000Z" }, { - "created_at": "2020-06-18T17:45:13Z", - "domain": "mysite2.square.site", + "created_at": "2020-06-18T17:45:13.000000Z", + "domain": "mysite1.square.site", "id": "site_102725345836253849", "is_published": true, - "site_title": "My Second Site", - "updated_at": "2020-11-23T02:19:10Z" + "site_title": "My First Site", + "updated_at": "2020-11-23T02:19:10.000000Z" } ] } diff --git a/doc/models/list-subscription-events-request.md b/doc/models/list-subscription-events-request.md index 84c44e0d..531152c9 100644 --- a/doc/models/list-subscription-events-request.md +++ b/doc/models/list-subscription-events-request.md @@ -1,9 +1,9 @@ # List Subscription Events Request -Defines parameters in a +Defines input parameters in a request to the [ListSubscriptionEvents](/doc/api/subscriptions.md#list-subscription-events) -endpoint request. +endpoint. ## Structure @@ -13,8 +13,8 @@ endpoint request. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | -| `limit` | `int` | Optional | The upper limit on the number of subscription events to return
in the response.

Default: `200`
**Constraints**: `>= 1` | +| `cursor` | `string` | Optional | When the total number of resulting subscription events exceeds the limit of a paged response,
specify the cursor returned from a preceding response here to fetch the next set of results.
If the cursor is unset, the response contains the last page of the results.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | +| `limit` | `int` | Optional | The upper limit on the number of subscription events to return
in a paged response.
**Constraints**: `>= 1` | ## Example (as JSON) diff --git a/doc/models/list-subscription-events-response.md b/doc/models/list-subscription-events-response.md index ccff726c..bea89e15 100644 --- a/doc/models/list-subscription-events-response.md +++ b/doc/models/list-subscription-events-response.md @@ -1,9 +1,8 @@ # List Subscription Events Response -Defines the fields that are included in the response from the -[ListSubscriptionEvents](/doc/api/subscriptions.md#list-subscription-events) -endpoint. +Defines output parameters in a response from the +[ListSubscriptionEvents](/doc/api/subscriptions.md#list-subscription-events). ## Structure @@ -13,9 +12,9 @@ endpoint. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information about errors encountered during the request. | -| `subscription_events` | [`List of Subscription Event`](/doc/models/subscription-event.md) | Optional | The `SubscriptionEvents` retrieved. | -| `cursor` | `string` | Optional | When a response is truncated, it includes a cursor that you can
use in a subsequent request to fetch the next set of events.
If empty, this is the final response.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription_events` | [`List of Subscription Event`](/doc/models/subscription-event.md) | Optional | The retrieved subscription events. | +| `cursor` | `string` | Optional | When the total number of resulting subscription events exceeds the limit of a paged response,
the response includes a cursor for you to use in a subsequent request to fetch the next set of events.
If the cursor is unset, the response contains the last page of the results.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | ## Example (as JSON) diff --git a/doc/models/list-team-member-booking-profiles-request.md b/doc/models/list-team-member-booking-profiles-request.md index 79f2acdd..025f8ad6 100644 --- a/doc/models/list-team-member-booking-profiles-request.md +++ b/doc/models/list-team-member-booking-profiles-request.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `bookable_only` | `bool` | Optional | Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`). | -| `limit` | `int` | Optional | The maximum number of results to return. | +| `limit` | `int` | Optional | The maximum number of results to return.
**Constraints**: `>= 1`, `<= 100` | | `cursor` | `string` | Optional | The cursor for paginating through the results. | | `location_id` | `string` | Optional | Indicates whether to include only team members enabled at the given location in the returned result. | diff --git a/doc/models/pause-subscription-request.md b/doc/models/pause-subscription-request.md new file mode 100644 index 00000000..e6cb0606 --- /dev/null +++ b/doc/models/pause-subscription-request.md @@ -0,0 +1,32 @@ + +# Pause Subscription Request + +Defines input parameters in a request to the +[PauseSubscription](/doc/api/subscriptions.md#pause-subscription) endpoint. + +## Structure + +`Pause Subscription Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `pause_effective_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date when the scheduled `PAUSE` action takes place on the subscription.

When this date is unspecified or falls within the current billing cycle, the subscription is paused
on the starting date of the next billing cycle. | +| `pause_cycle_duration` | `long\|int` | Optional | The number of billing cycles the subscription will be paused before it is reactivated.

When this is set, a `RESUME` action is also scheduled to take place on the subscription at
the end of the specified pause cycle duration. In this case, neither `resume_effective_date`
nor `resume_change_timing` may be specified. | +| `resume_effective_date` | `string` | Optional | The date when the subscription is reactivated by a scheduled `RESUME` action.
This date must be at least one billing cycle ahead of `pause_effective_date`. | +| `resume_change_timing` | [`str (Change Timing)`](/doc/models/change-timing.md) | Optional | Supported timings when a pending change, as an action, takes place to a subscription. | +| `pause_reason` | `string` | Optional | The user-provided reason to pause the subscription.
**Constraints**: *Maximum Length*: `255` | + +## Example (as JSON) + +```json +{ + "pause_effective_date": "pause_effective_date0", + "pause_cycle_duration": 86, + "resume_effective_date": "resume_effective_date2", + "resume_change_timing": "IMMEDIATE", + "pause_reason": "pause_reason8" +} +``` + diff --git a/doc/models/pause-subscription-response.md b/doc/models/pause-subscription-response.md new file mode 100644 index 00000000..1e54ab90 --- /dev/null +++ b/doc/models/pause-subscription-response.md @@ -0,0 +1,49 @@ + +# Pause Subscription Response + +Defines output parameters in a response from the +[PauseSubscription](/doc/api/subscriptions.md#pause-subscription) endpoint. + +## Structure + +`Pause Subscription Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `actions` | [`List of Subscription Action`](/doc/models/subscription-action.md) | Optional | The list of a `PAUSE` action and a possible `RESUME` action created by the request. | + +## Example (as JSON) + +```json +{ + "actions": [ + { + "effective_date": "2021-11-17", + "id": "99b2439e-63f7-3ad5-95f7-ab2447a80673", + "type": "PAUSE" + } + ], + "subscription": { + "created_at": "2021-10-20T21:53:10Z", + "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", + "id": "9ba40961-995a-4a3d-8c53-048c40cafc13", + "location_id": "S8GWD5R9QB376", + "plan_id": "6JHXF3B2CW3YKHDV4XEM674H", + "price_override_money": { + "amount": 2000, + "currency": "USD" + }, + "source": { + "name": "My App" + }, + "status": "ACTIVE", + "timezone": "America/Los_Angeles", + "version": 1594311617331 + } +} +``` + diff --git a/doc/models/payment.md b/doc/models/payment.md index da07582c..bf9d7689 100644 --- a/doc/models/payment.md +++ b/doc/models/payment.md @@ -25,7 +25,7 @@ Represents a payment processed by the Square API. | `delay_duration` | `string` | Optional | The duration of time after the payment's creation when Square automatically applies the
`delay_action` to the payment. This automatic `delay_action` applies only to payments that
do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the `delay_duration`
time period.

This field is specified as a time duration, in RFC 3339 format.

Notes:
This feature is only supported for card payments.

Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | | `delay_action` | `string` | Optional | The action to be applied to the payment when the `delay_duration` has elapsed. This field
is read-only.

Current values include `CANCEL`. | | `delayed_until` | `string` | Optional | The read-only timestamp of when the `delay_action` is automatically applied,
in RFC 3339 format.

Note that this field is calculated by summing the payment's `delay_duration` and `created_at`
fields. The `created_at` field is generated by Square and might not exactly match the
time on your local machine. | -| `source_type` | `string` | Optional | The source type for this payment.

Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, or `EXTERNAL`.
**Constraints**: *Maximum Length*: `50` | +| `source_type` | `string` | Optional | The source type for this payment.

Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `CASH`, or
`EXTERNAL`.
**Constraints**: *Maximum Length*: `50` | | `card_details` | [`Card Payment Details`](/doc/models/card-payment-details.md) | Optional | Reflects the current status of a card payment. Contains only non-confidential information. | | `cash_details` | [`Cash Payment Details`](/doc/models/cash-payment-details.md) | Optional | Stores details about a cash payment. Contains only non-confidential information. For more information, see
[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments). | | `bank_account_details` | [`Bank Account Payment Details`](/doc/models/bank-account-payment-details.md) | Optional | Additional details about BANK_ACCOUNT type payments. | diff --git a/doc/models/refund-payment-request.md b/doc/models/refund-payment-request.md index 0287428c..1a05e90e 100644 --- a/doc/models/refund-payment-request.md +++ b/doc/models/refund-payment-request.md @@ -14,7 +14,7 @@ Describes a request to refund a payment using [RefundPayment](/doc/api/refunds.m | `idempotency_key` | `string` | Required | A unique string that identifies this `RefundPayment` request. The key can be any valid string
but must be unique for every `RefundPayment` request.

For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
**Constraints**: *Minimum Length*: `1` | | `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. | -| `payment_id` | `string` | Required | The unique ID of the payment being refunded.
**Constraints**: *Minimum Length*: `1` | +| `payment_id` | `string` | Optional | The unique ID of the payment being refunded. Must be provided and non-empty. | | `reason` | `string` | Optional | A description of the reason for the refund.
**Constraints**: *Maximum Length*: `192` | | `payment_version_token` | `string` | Optional | Used for optimistic concurrency. This opaque token identifies the current `Payment`
version that the caller expects. If the server has a different version of the Payment,
the update fails and a response with a VERSION_MISMATCH error is returned.
If the versions match, or the field is not provided, the refund proceeds as normal. | | `team_member_id` | `string` | Optional | An optional [TeamMember](/doc/models/team-member.md) ID to associate with this refund.
**Constraints**: *Maximum Length*: `192` | diff --git a/doc/models/resume-subscription-request.md b/doc/models/resume-subscription-request.md new file mode 100644 index 00000000..79d1700c --- /dev/null +++ b/doc/models/resume-subscription-request.md @@ -0,0 +1,26 @@ + +# Resume Subscription Request + +Defines input parameters in a request to the +[ResumeSubscription](/doc/api/subscriptions.md#resume-subscription) endpoint. + +## Structure + +`Resume Subscription Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `resume_effective_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date when the subscription reactivated. | +| `resume_change_timing` | [`str (Change Timing)`](/doc/models/change-timing.md) | Optional | Supported timings when a pending change, as an action, takes place to a subscription. | + +## Example (as JSON) + +```json +{ + "resume_effective_date": "resume_effective_date2", + "resume_change_timing": "IMMEDIATE" +} +``` + diff --git a/doc/models/resume-subscription-response.md b/doc/models/resume-subscription-response.md index bb85e354..74e691b6 100644 --- a/doc/models/resume-subscription-response.md +++ b/doc/models/resume-subscription-response.md @@ -1,9 +1,8 @@ # Resume Subscription Response -Defines parameters in a -[ResumeSubscription](/doc/api/subscriptions.md#resume-subscription) endpoint -response. +Defines output parameters in a response from the +[ResumeSubscription](/doc/api/subscriptions.md#resume-subscription) endpoint. ## Structure @@ -13,13 +12,21 @@ response. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information about errors encountered during the request. | -| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a customer subscription to a subscription plan.
For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `actions` | [`List of Subscription Action`](/doc/models/subscription-action.md) | Optional | A list of `RESUME` actions created by the request and scheduled for the subscription. | ## Example (as JSON) ```json { + "actions": [ + { + "effective_date": "2022-01-01", + "id": "18ff74f4-3da4-30c5-929f-7d6fca84f115", + "type": "RESUME" + } + ], "subscription": { "created_at": "2021-10-20T21:53:10Z", "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", diff --git a/doc/models/retrieve-card-response.md b/doc/models/retrieve-card-response.md index 147d07ab..7e54a207 100644 --- a/doc/models/retrieve-card-response.md +++ b/doc/models/retrieve-card-response.md @@ -2,7 +2,7 @@ # Retrieve Card Response Defines the fields that are included in the response body of -a request to the [RetrieveCard](#endpoint-cards-retrievecard) endpoint. +a request to the [RetrieveCard](/doc/api/cards.md#retrieve-card) endpoint. Note: if there are errors processing the request, the card field will not be present. @@ -42,6 +42,7 @@ present. "fingerprint": "ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q", "id": "ccof:uIbfJXhXETSP197M3GB", "last_4": "1111", + "merchant_id": "6SSW7HV8K2ST5", "prepaid_type": "NOT_PREPAID", "reference_id": "user-id-1", "version": 1 diff --git a/doc/models/retrieve-employee-response.md b/doc/models/retrieve-employee-response.md index fbd43768..517f0acd 100644 --- a/doc/models/retrieve-employee-response.md +++ b/doc/models/retrieve-employee-response.md @@ -26,19 +26,19 @@ "errors": [ { "category": "AUTHENTICATION_ERROR", - "code": "UNPROCESSABLE_ENTITY", + "code": "MISSING_PIN", "detail": "detail1", "field": "field9" }, { "category": "INVALID_REQUEST_ERROR", - "code": "RATE_LIMITED", + "code": "MISSING_ACCOUNT_TYPE", "detail": "detail2", "field": "field0" }, { "category": "RATE_LIMIT_ERROR", - "code": "NOT_IMPLEMENTED", + "code": "INVALID_POSTAL_CODE", "detail": "detail3", "field": "field1" } diff --git a/doc/models/retrieve-gift-card-from-nonce-request.md b/doc/models/retrieve-gift-card-from-nonce-request.md index d0f15822..95cf4fc5 100644 --- a/doc/models/retrieve-gift-card-from-nonce-request.md +++ b/doc/models/retrieve-gift-card-from-nonce-request.md @@ -1,7 +1,7 @@ # Retrieve Gift Card From Nonce Request -A request to retrieve gift cards by using nonces. +A request to retrieve a gift card by using a payment token. ## Structure @@ -11,7 +11,7 @@ A request to retrieve gift cards by using nonces. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `nonce` | `string` | Required | The nonce of the gift card to retrieve.
**Constraints**: *Minimum Length*: `1` | +| `nonce` | `string` | Required | The payment token of the gift card to retrieve. Payment tokens are generated by the
Web Payments SDK or In-App Payments SDK.
**Constraints**: *Minimum Length*: `1` | ## Example (as JSON) diff --git a/doc/models/retrieve-gift-card-from-nonce-response.md b/doc/models/retrieve-gift-card-from-nonce-response.md index 5884aec4..d4b49fec 100644 --- a/doc/models/retrieve-gift-card-from-nonce-response.md +++ b/doc/models/retrieve-gift-card-from-nonce-response.md @@ -1,8 +1,8 @@ # Retrieve Gift Card From Nonce Response -A response that contains a `GiftCard`. The response might contain a set of `Error` objects -if the request resulted in errors. +A response that contains a `GiftCard` object. If the request resulted in errors, +the response contains a set of `Error` objects. ## Structure diff --git a/doc/models/retrieve-loyalty-program-response.md b/doc/models/retrieve-loyalty-program-response.md index 2ff3dc1f..54a54e96 100644 --- a/doc/models/retrieve-loyalty-program-response.md +++ b/doc/models/retrieve-loyalty-program-response.md @@ -32,7 +32,8 @@ A response that contains the loyalty program. ], "points": 1, "spend_amount_money": { - "amount": 100 + "amount": 100, + "currency": "USD" } } ], diff --git a/doc/models/retrieve-snippet-response.md b/doc/models/retrieve-snippet-response.md index 7e1fabba..0c341656 100644 --- a/doc/models/retrieve-snippet-response.md +++ b/doc/models/retrieve-snippet-response.md @@ -20,10 +20,10 @@ Represents a `RetrieveSnippet` response. The response can include either `snippe { "snippet": { "content": "", - "created_at": "2021-03-11T25:40:09Z", + "created_at": "2021-03-11T25:40:09.000000Z", "id": "snippet_5d178150-a6c0-11eb-a9f1-437e6a2881e7", "site_id": "site_278075276488921835", - "updated_at": "2021-03-11T25:40:09Z" + "updated_at": "2021-03-11T25:40:09.000000Z" } } ``` diff --git a/doc/models/retrieve-subscription-request.md b/doc/models/retrieve-subscription-request.md new file mode 100644 index 00000000..d14ead2d --- /dev/null +++ b/doc/models/retrieve-subscription-request.md @@ -0,0 +1,24 @@ + +# Retrieve Subscription Request + +Defines input parameters in a request to the +[RetrieveSubscription](/doc/api/subscriptions.md#retrieve-subscription) endpoint. + +## Structure + +`Retrieve Subscription Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `include` | `string` | Optional | A query parameter to specify related information to be included in the response.

The supported query parameter values are:

- `actions`: to include scheduled actions on the targeted subscription. | + +## Example (as JSON) + +```json +{ + "include": "include2" +} +``` + diff --git a/doc/models/retrieve-subscription-response.md b/doc/models/retrieve-subscription-response.md index 5f71db65..0287eecf 100644 --- a/doc/models/retrieve-subscription-response.md +++ b/doc/models/retrieve-subscription-response.md @@ -1,7 +1,7 @@ # Retrieve Subscription Response -Defines the fields that are included in the response from the +Defines output parameters in a response from the [RetrieveSubscription](/doc/api/subscriptions.md#retrieve-subscription) endpoint. ## Structure @@ -12,8 +12,8 @@ Defines the fields that are included in the response from the | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information about errors encountered during the request. | -| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a customer subscription to a subscription plan.
For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | ## Example (as JSON) diff --git a/doc/models/search-catalog-items-response.md b/doc/models/search-catalog-items-response.md index bd5d0a52..422399ff 100644 --- a/doc/models/search-catalog-items-response.md +++ b/doc/models/search-catalog-items-response.md @@ -23,19 +23,19 @@ Defines the response body returned from the [SearchCatalogItems](/doc/api/catalo "errors": [ { "category": "AUTHENTICATION_ERROR", - "code": "UNPROCESSABLE_ENTITY", + "code": "MISSING_PIN", "detail": "detail1", "field": "field9" }, { "category": "INVALID_REQUEST_ERROR", - "code": "RATE_LIMITED", + "code": "MISSING_ACCOUNT_TYPE", "detail": "detail2", "field": "field0" }, { "category": "RATE_LIMIT_ERROR", - "code": "NOT_IMPLEMENTED", + "code": "INVALID_POSTAL_CODE", "detail": "detail3", "field": "field1" } diff --git a/doc/models/search-loyalty-accounts-request.md b/doc/models/search-loyalty-accounts-request.md index 83887d7d..002d5d48 100644 --- a/doc/models/search-loyalty-accounts-request.md +++ b/doc/models/search-loyalty-accounts-request.md @@ -12,7 +12,7 @@ A request to search for loyalty accounts. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `query` | [`Search Loyalty Accounts Request Loyalty Account Query`](/doc/models/search-loyalty-accounts-request-loyalty-account-query.md) | Optional | The search criteria for the loyalty accounts. | -| `limit` | `int` | Optional | The maximum number of results to include in the response.
**Constraints**: `>= 1`, `<= 30` | +| `limit` | `int` | Optional | The maximum number of results to include in the response. The default value is 30.
**Constraints**: `>= 1`, `<= 30` | | `cursor` | `string` | Optional | A pagination cursor returned by a previous call to
this endpoint. Provide this to retrieve the next set of
results for the original query.

For more information,
see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). | ## Example (as JSON) diff --git a/doc/models/search-loyalty-rewards-request.md b/doc/models/search-loyalty-rewards-request.md index 4008ff0d..814dd9f2 100644 --- a/doc/models/search-loyalty-rewards-request.md +++ b/doc/models/search-loyalty-rewards-request.md @@ -12,7 +12,7 @@ A request to search for loyalty rewards. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `query` | [`Search Loyalty Rewards Request Loyalty Reward Query`](/doc/models/search-loyalty-rewards-request-loyalty-reward-query.md) | Optional | The set of search requirements. | -| `limit` | `int` | Optional | The maximum number of results to return in the response.
**Constraints**: `>= 1`, `<= 30` | +| `limit` | `int` | Optional | The maximum number of results to return in the response. The default value is 30.
**Constraints**: `>= 1`, `<= 30` | | `cursor` | `string` | Optional | A pagination cursor returned by a previous call to
this endpoint. Provide this to retrieve the next set of
results for the original query.
For more information,
see [Pagination](https://developer.squareup.com/docs/basics/api101/pagination). | ## Example (as JSON) diff --git a/doc/models/search-subscriptions-filter.md b/doc/models/search-subscriptions-filter.md index 39b74492..0dd1ccf3 100644 --- a/doc/models/search-subscriptions-filter.md +++ b/doc/models/search-subscriptions-filter.md @@ -1,7 +1,8 @@ # Search Subscriptions Filter -Represents a set of SearchSubscriptionsQuery filters used to limit the set of Subscriptions returned by SearchSubscriptions. +Represents a set of query expressions (filters) to narrow the scope of targeted subscriptions returned by +the [SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) endpoint. ## Structure @@ -11,8 +12,8 @@ Represents a set of SearchSubscriptionsQuery filters used to limit the set of Su | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `customer_ids` | `List of string` | Optional | A filter to select subscriptions based on the customer. | -| `location_ids` | `List of string` | Optional | A filter to select subscriptions based the location. | +| `customer_ids` | `List of string` | Optional | A filter to select subscriptions based on the subscribing customer IDs. | +| `location_ids` | `List of string` | Optional | A filter to select subscriptions based on the location. | | `source_names` | `List of string` | Optional | A filter to select subscriptions based on the source application. | ## Example (as JSON) diff --git a/doc/models/search-subscriptions-query.md b/doc/models/search-subscriptions-query.md index d9421f40..1f12a8ef 100644 --- a/doc/models/search-subscriptions-query.md +++ b/doc/models/search-subscriptions-query.md @@ -1,7 +1,7 @@ # Search Subscriptions Query -Represents a query (including filtering criteria) used to search for subscriptions. +Represents a query, consisting of specified query expressions, used to search for subscriptions. ## Structure @@ -11,7 +11,7 @@ Represents a query (including filtering criteria) used to search for subscriptio | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `filter` | [`Search Subscriptions Filter`](/doc/models/search-subscriptions-filter.md) | Optional | Represents a set of SearchSubscriptionsQuery filters used to limit the set of Subscriptions returned by SearchSubscriptions. | +| `filter` | [`Search Subscriptions Filter`](/doc/models/search-subscriptions-filter.md) | Optional | Represents a set of query expressions (filters) to narrow the scope of targeted subscriptions returned by
the [SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) endpoint. | ## Example (as JSON) diff --git a/doc/models/search-subscriptions-request.md b/doc/models/search-subscriptions-request.md index d1e36670..388596fa 100644 --- a/doc/models/search-subscriptions-request.md +++ b/doc/models/search-subscriptions-request.md @@ -1,9 +1,8 @@ # Search Subscriptions Request -Defines parameters in a -[SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) endpoint -request. +Defines input parameters in a request to the +[SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) endpoint. ## Structure @@ -13,9 +12,10 @@ request. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `cursor` | `string` | Optional | A pagination cursor returned by a previous call to this endpoint.
Provide this to retrieve the next set of results for the original query.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | -| `limit` | `int` | Optional | The upper limit on the number of subscriptions to return
in the response.

Default: `200`
**Constraints**: `>= 1` | -| `query` | [`Search Subscriptions Query`](/doc/models/search-subscriptions-query.md) | Optional | Represents a query (including filtering criteria) used to search for subscriptions. | +| `cursor` | `string` | Optional | When the total number of resulting subscriptions exceeds the limit of a paged response,
specify the cursor returned from a preceding response here to fetch the next set of results.
If the cursor is unset, the response contains the last page of the results.

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

The supported query parameter values are:

- `actions`: to include scheduled actions on the targeted subscriptions. | ## Example (as JSON) diff --git a/doc/models/search-subscriptions-response.md b/doc/models/search-subscriptions-response.md index 262a3f87..d518f708 100644 --- a/doc/models/search-subscriptions-response.md +++ b/doc/models/search-subscriptions-response.md @@ -1,7 +1,7 @@ # Search Subscriptions Response -Defines the fields that are included in the response from the +Defines output parameters in a response from the [SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) endpoint. ## Structure @@ -12,9 +12,9 @@ Defines the fields that are included in the response from the | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information about errors encountered during the request. | -| `subscriptions` | [`List of Subscription`](/doc/models/subscription.md) | Optional | The search result. | -| `cursor` | `string` | Optional | When a response is truncated, it includes a cursor that you can
use in a subsequent request to fetch the next set of subscriptions.
If empty, this is the final response.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscriptions` | [`List of Subscription`](/doc/models/subscription.md) | Optional | The subscriptions matching the specified query expressions. | +| `cursor` | `string` | Optional | When the total number of resulting subscription exceeds the limit of a paged response,
the response includes a cursor for you to use in a subsequent request to fetch the next set of results.
If the cursor is unset, the response contains the last page of the results.

For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). | ## Example (as JSON) diff --git a/doc/models/snippet-response.md b/doc/models/snippet-response.md index febfdc9a..4c03bb9f 100644 --- a/doc/models/snippet-response.md +++ b/doc/models/snippet-response.md @@ -19,19 +19,19 @@ "errors": [ { "category": "AUTHENTICATION_ERROR", - "code": "UNPROCESSABLE_ENTITY", + "code": "MISSING_PIN", "detail": "detail1", "field": "field9" }, { "category": "INVALID_REQUEST_ERROR", - "code": "RATE_LIMITED", + "code": "MISSING_ACCOUNT_TYPE", "detail": "detail2", "field": "field0" }, { "category": "RATE_LIMIT_ERROR", - "code": "NOT_IMPLEMENTED", + "code": "INVALID_POSTAL_CODE", "detail": "detail3", "field": "field1" } diff --git a/doc/models/subscription-action-type.md b/doc/models/subscription-action-type.md new file mode 100644 index 00000000..9913c93a --- /dev/null +++ b/doc/models/subscription-action-type.md @@ -0,0 +1,18 @@ + +# Subscription Action Type + +Supported types of an action as a pending change to a subscription. + +## Enumeration + +`Subscription Action Type` + +## Fields + +| Name | Description | +| --- | --- | +| `CANCEL` | The action to execute a scheduled cancellation of a subscription. | +| `PAUSE` | The action to execute a scheduled pause of a subscription. | +| `RESUME` | The action to execute a scheduled resumption of a subscription. | +| `SWAP_PLAN` | The action to execute a scheduled swap of a subscription plan in a subscription. | + diff --git a/doc/models/subscription-action.md b/doc/models/subscription-action.md new file mode 100644 index 00000000..24bb8bd3 --- /dev/null +++ b/doc/models/subscription-action.md @@ -0,0 +1,29 @@ + +# Subscription Action + +Represents an action as a pending change to a subscription. + +## Structure + +`Subscription Action` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `id` | `string` | Optional | The ID of an action scoped to a subscription. | +| `type` | [`str (Subscription Action Type)`](/doc/models/subscription-action-type.md) | Optional | Supported types of an action as a pending change to a subscription. | +| `effective_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date when the action occurs on the subscription. | +| `new_plan_id` | `string` | Optional | The target subscription plan a subscription switches to, for a `SWAP_PLAN` action. | + +## Example (as JSON) + +```json +{ + "id": "id0", + "type": "RESUME", + "effective_date": "effective_date0", + "new_plan_id": "new_plan_id4" +} +``` + diff --git a/doc/models/subscription-event-info-code.md b/doc/models/subscription-event-info-code.md index 711db9f9..5394a7da 100644 --- a/doc/models/subscription-event-info-code.md +++ b/doc/models/subscription-event-info-code.md @@ -1,7 +1,7 @@ # Subscription Event Info Code -The possible subscription event info codes. +Supported info codes of a subscription event. ## Enumeration @@ -13,7 +13,8 @@ The possible subscription event info codes. | --- | --- | | `LOCATION_NOT_ACTIVE` | The location is not active. | | `LOCATION_CANNOT_ACCEPT_PAYMENT` | The location cannot accept payments. | -| `CUSTOMER_DELETED` | The customer has been deleted. | -| `CUSTOMER_NO_EMAIL` | The customer doesn't have an email. | -| `CUSTOMER_NO_NAME` | The customer doesn't have a name. | +| `CUSTOMER_DELETED` | The subscribing customer profile has been deleted. | +| `CUSTOMER_NO_EMAIL` | The subscribing customer does not have an email. | +| `CUSTOMER_NO_NAME` | The subscribing customer does not have a name. | +| `USER_PROVIDED` | User-provided detail. | diff --git a/doc/models/subscription-event-info.md b/doc/models/subscription-event-info.md index 67c2f1cc..ea32e212 100644 --- a/doc/models/subscription-event-info.md +++ b/doc/models/subscription-event-info.md @@ -12,14 +12,14 @@ Provides information about the subscription event. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `detail` | `string` | Optional | A human-readable explanation for the event. | -| `code` | [`str (Subscription Event Info Code)`](/doc/models/subscription-event-info-code.md) | Optional | The possible subscription event info codes. | +| `code` | [`str (Subscription Event Info Code)`](/doc/models/subscription-event-info-code.md) | Optional | Supported info codes of a subscription event. | ## Example (as JSON) ```json { "detail": "detail6", - "code": "CUSTOMER_NO_EMAIL" + "code": "CUSTOMER_DELETED" } ``` diff --git a/doc/models/subscription-event-subscription-event-type.md b/doc/models/subscription-event-subscription-event-type.md index 6a2e3aae..6a067580 100644 --- a/doc/models/subscription-event-subscription-event-type.md +++ b/doc/models/subscription-event-subscription-event-type.md @@ -1,7 +1,7 @@ # Subscription Event Subscription Event Type -The possible subscription event types. +Supported types of an event occurred to a subscription. ## Enumeration @@ -11,9 +11,10 @@ The possible subscription event types. | Name | Description | | --- | --- | -| `START_SUBSCRIPTION` | The subscription started. | -| `PLAN_CHANGE` | The subscription plan changed. | -| `STOP_SUBSCRIPTION` | The subscription stopped. | -| `DEACTIVATE_SUBSCRIPTION` | The subscription deactivated | -| `RESUME_SUBSCRIPTION` | The subscription resumed. | +| `START_SUBSCRIPTION` | The subscription was started. | +| `PLAN_CHANGE` | The subscription plan was changed. | +| `STOP_SUBSCRIPTION` | The subscription was stopped. | +| `DEACTIVATE_SUBSCRIPTION` | The subscription was deactivated | +| `RESUME_SUBSCRIPTION` | The subscription was resumed. | +| `PAUSE_SUBSCRIPTION` | The subscription was paused. | diff --git a/doc/models/subscription-event.md b/doc/models/subscription-event.md index 2a98288d..3720d07c 100644 --- a/doc/models/subscription-event.md +++ b/doc/models/subscription-event.md @@ -1,7 +1,7 @@ # Subscription Event -Describes changes to subscription and billing states. +Describes changes to a subscription and the subscription status. ## Structure @@ -12,8 +12,8 @@ Describes changes to subscription and billing states. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `id` | `string` | Required | The ID of the subscription event. | -| `subscription_event_type` | [`str (Subscription Event Subscription Event Type)`](/doc/models/subscription-event-subscription-event-type.md) | Required | The possible subscription event types. | -| `effective_date` | `string` | Required | The date, in YYYY-MM-DD format (for
example, 2013-01-15), when the subscription event went into effect. | +| `subscription_event_type` | [`str (Subscription Event Subscription Event Type)`](/doc/models/subscription-event-subscription-event-type.md) | Required | Supported types of an event occurred to a subscription. | +| `effective_date` | `string` | Required | The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) when the subscription event occurred. | | `plan_id` | `string` | Required | The ID of the subscription plan associated with the subscription. | | `info` | [`Subscription Event Info`](/doc/models/subscription-event-info.md) | Optional | Provides information about the subscription event. | @@ -22,12 +22,12 @@ Describes changes to subscription and billing states. ```json { "id": "id0", - "subscription_event_type": "STOP_SUBSCRIPTION", + "subscription_event_type": "RESUME_SUBSCRIPTION", "effective_date": "effective_date0", "plan_id": "plan_id8", "info": { "detail": "detail6", - "code": "CUSTOMER_NO_EMAIL" + "code": "CUSTOMER_DELETED" } } ``` diff --git a/doc/models/subscription-status.md b/doc/models/subscription-status.md index 468c1cd6..b8e4cc2a 100644 --- a/doc/models/subscription-status.md +++ b/doc/models/subscription-status.md @@ -1,7 +1,7 @@ # Subscription Status -Possible subscription status values. +Supported subscription statuses. ## Enumeration @@ -11,8 +11,9 @@ Possible subscription status values. | Name | Description | | --- | --- | -| `PENDING` | The subscription starts in the future. | +| `PENDING` | The subscription is pending to start in the future. | | `ACTIVE` | The subscription is active. | | `CANCELED` | The subscription is canceled. | | `DEACTIVATED` | The subscription is deactivated. | +| `PAUSED` | The subscription is paused. | diff --git a/doc/models/subscription.md b/doc/models/subscription.md index 61bb2f60..3bc17a66 100644 --- a/doc/models/subscription.md +++ b/doc/models/subscription.md @@ -1,7 +1,8 @@ # Subscription -Represents a customer subscription to a subscription plan. +Represents a subscription to a subscription plan by a subscriber. + For an overview of the `Subscription` type, see [Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). @@ -15,20 +16,21 @@ For an overview of the `Subscription` type, see | --- | --- | --- | --- | | `id` | `string` | Optional | The Square-assigned ID of the subscription.
**Constraints**: *Maximum Length*: `255` | | `location_id` | `string` | Optional | The ID of the location associated with the subscription. | -| `plan_id` | `string` | Optional | The ID of the associated [subscription plan](/doc/models/catalog-subscription-plan.md). | -| `customer_id` | `string` | Optional | The ID of the associated [customer](/doc/models/customer.md) profile. | -| `start_date` | `string` | Optional | The start date of the subscription, in YYYY-MM-DD format (for example,
2013-01-15). | -| `canceled_date` | `string` | Optional | The subscription cancellation date, in YYYY-MM-DD format (for
example, 2013-01-15). On this date, the subscription status changes
to `CANCELED` and the subscription billing stops.
If you don't set this field, the subscription plan dictates if and
when subscription ends.

You cannot update this field, you can only clear it. | -| `charged_through_date` | `string` | Optional | The date up to which the customer is invoiced for the
subscription, in YYYY-MM-DD format (for example, 2013-01-15).

After the invoice is sent for a given billing period,
this date will be the last day of the billing period.
For example,
suppose for the month of May a customer gets an invoice
(or charged the card) on May 1. For the monthly billing scenario,
this date is then set to May 31. | -| `status` | [`str (Subscription Status)`](/doc/models/subscription-status.md) | Optional | Possible subscription status values. | +| `plan_id` | `string` | Optional | The ID of the subscribed-to [subscription plan](/doc/models/catalog-subscription-plan.md). | +| `customer_id` | `string` | Optional | The ID of the subscribing [customer](/doc/models/customer.md) profile. | +| `start_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to start the subscription. | +| `canceled_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to cancel the subscription,
when the subscription status changes to `CANCELED` and the subscription billing stops.

If this field is not set, the subscription ends according its subscription plan.

This field cannot be updated, other than being cleared. | +| `charged_through_date` | `string` | Optional | The `YYYY-MM-DD`-formatted date up to when the subscriber is invoiced for the
subscription.

After the invoice is sent for a given billing period,
this date will be the last day of the billing period.
For example,
suppose for the month of May a subscriber gets an invoice
(or charged the card) on May 1. For the monthly billing scenario,
this date is then set to May 31. | +| `status` | [`str (Subscription Status)`](/doc/models/subscription-status.md) | Optional | Supported subscription statuses. | | `tax_percentage` | `string` | Optional | The tax amount applied when billing the subscription. The
percentage is expressed in decimal form, using a `'.'` as the decimal
separator and without a `'%'` sign. For example, a value of `7.5`
corresponds to 7.5%. | | `invoice_ids` | `List of string` | Optional | The IDs of the [invoices](/doc/models/invoice.md) created for the
subscription, listed in order when the invoices were created
(oldest invoices appear first). | | `price_override_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. | | `version` | `long\|int` | Optional | The version of the object. When updating an object, the version
supplied must match the version in the database, otherwise the write will
be rejected as conflicting. | | `created_at` | `string` | Optional | The timestamp when the subscription was created, in RFC 3339 format. | -| `card_id` | `string` | Optional | The ID of the [customer](/doc/models/customer.md) [card](/doc/models/card.md)
that is charged for the subscription. | +| `card_id` | `string` | Optional | The ID of the [subscriber's](/doc/models/customer.md) [card](/doc/models/card.md)
used to charge for the subscription. | | `timezone` | `string` | Optional | Timezone that will be used in date calculations for the subscription.
Defaults to the timezone of the location based on `location_id`.
Format: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`). | | `source` | [`Subscription Source`](/doc/models/subscription-source.md) | Optional | The origination details of the subscription. | +| `actions` | [`List of Subscription Action`](/doc/models/subscription-action.md) | Optional | The list of scheduled actions on this subscription. It is set only in the response from the
[RetrieveSubscription](/doc/api/subscriptions.md#retrieve-subscription) or
[SearchSubscriptions](/doc/api/subscriptions.md#search-subscriptions) endpoint with the query parameter
of `include=actions`. | ## Example (as JSON) diff --git a/doc/models/swap-plan-request.md b/doc/models/swap-plan-request.md new file mode 100644 index 00000000..d6232cc1 --- /dev/null +++ b/doc/models/swap-plan-request.md @@ -0,0 +1,24 @@ + +# Swap Plan Request + +Defines input parameters in a call to the +[SwapPlan](/doc/api/subscriptions.md#swap-plan) endpoint. + +## Structure + +`Swap Plan Request` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `new_plan_id` | `string` | Required | The ID of the new subscription plan.
**Constraints**: *Minimum Length*: `1` | + +## Example (as JSON) + +```json +{ + "new_plan_id": "new_plan_id4" +} +``` + diff --git a/doc/models/swap-plan-response.md b/doc/models/swap-plan-response.md new file mode 100644 index 00000000..6d4c7792 --- /dev/null +++ b/doc/models/swap-plan-response.md @@ -0,0 +1,50 @@ + +# Swap Plan Response + +Defines output parameters in a response of the +[SwapPlan](/doc/api/subscriptions.md#swap-plan) endpoint. + +## Structure + +`Swap Plan Response` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `actions` | [`List of Subscription Action`](/doc/models/subscription-action.md) | Optional | A list of a `SWAP_PLAN` action created by the request. | + +## Example (as JSON) + +```json +{ + "actions": [ + { + "effective_date": "2021-11-17", + "id": "f0a1dfdc-675b-3a14-a640-99f7ac1cee83", + "new_plan_id": "DPNEOJAP33DKC3GAC5CAZG4O", + "type": "SWAP_PLAN" + } + ], + "subscription": { + "created_at": "2021-10-20T21:53:10Z", + "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G", + "id": "9ba40961-995a-4a3d-8c53-048c40cafc13", + "location_id": "S8GWD5R9QB376", + "plan_id": "6JHXF3B2CW3YKHDV4XEM674H", + "price_override_money": { + "amount": 2000, + "currency": "USD" + }, + "source": { + "name": "My App" + }, + "status": "ACTIVE", + "timezone": "America/Los_Angeles", + "version": 1594311617331 + } +} +``` + diff --git a/doc/models/unlink-customer-from-gift-card-request.md b/doc/models/unlink-customer-from-gift-card-request.md index 85349e29..a3a2abfd 100644 --- a/doc/models/unlink-customer-from-gift-card-request.md +++ b/doc/models/unlink-customer-from-gift-card-request.md @@ -1,7 +1,7 @@ # Unlink Customer From Gift Card Request -A request to unlink a customer to a gift card +A request to unlink a customer from a gift card. ## Structure @@ -11,7 +11,7 @@ A request to unlink a customer to a gift card | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `customer_id` | `string` | Required | **Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | +| `customer_id` | `string` | Required | The ID of the customer to unlink from the gift card.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `191` | ## Example (as JSON) diff --git a/doc/models/unlink-customer-from-gift-card-response.md b/doc/models/unlink-customer-from-gift-card-response.md index 9517ce69..6c09613f 100644 --- a/doc/models/unlink-customer-from-gift-card-response.md +++ b/doc/models/unlink-customer-from-gift-card-response.md @@ -1,8 +1,8 @@ # Unlink Customer From Gift Card Response -A response that contains one `GiftCard` that was unlinked. The response might contain a set of `Error` -objects if the request resulted in errors. +A response that contains the unlinked `GiftCard` object. If the request resulted in errors, +the response contains a set of `Error` objects. ## Structure diff --git a/doc/models/update-subscription-request.md b/doc/models/update-subscription-request.md index a77c3eba..61feec0d 100644 --- a/doc/models/update-subscription-request.md +++ b/doc/models/update-subscription-request.md @@ -1,9 +1,8 @@ # Update Subscription Request -Defines parameters in a -[UpdateSubscription](/doc/api/subscriptions.md#update-subscription) endpoint -request. +Defines input parameters in a request to the +[UpdateSubscription](/doc/api/subscriptions.md#update-subscription) endpoint. ## Structure @@ -13,7 +12,7 @@ request. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a customer subscription to a subscription plan.
For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | ## Example (as JSON) diff --git a/doc/models/update-subscription-response.md b/doc/models/update-subscription-response.md index 8f6d724f..a65f00b3 100644 --- a/doc/models/update-subscription-response.md +++ b/doc/models/update-subscription-response.md @@ -1,7 +1,7 @@ # Update Subscription Response -Defines the fields that are included in the response from the +Defines output parameters in a response from the [UpdateSubscription](/doc/api/subscriptions.md#update-subscription) endpoint. ## Structure @@ -12,8 +12,8 @@ Defines the fields that are included in the response from the | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Information about errors encountered during the request. | -| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a customer subscription to a subscription plan.
For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | +| `errors` | [`List of Error`](/doc/models/error.md) | Optional | Errors encountered during the request. | +| `subscription` | [`Subscription`](/doc/models/subscription.md) | Optional | Represents a subscription to a subscription plan by a subscriber.

For an overview of the `Subscription` type, see
[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). | ## Example (as JSON) diff --git a/doc/models/upsert-snippet-response.md b/doc/models/upsert-snippet-response.md index 44b382a1..7097fbc5 100644 --- a/doc/models/upsert-snippet-response.md +++ b/doc/models/upsert-snippet-response.md @@ -20,10 +20,10 @@ Represents an `UpsertSnippet` response. The response can include either `snippet { "snippet": { "content": "", - "created_at": "2021-03-11T25:40:09Z", + "created_at": "2021-03-11T25:40:09.000000Z", "id": "snippet_5d178150-a6c0-11eb-a9f1-437e6a2881e7", "site_id": "site_278075276488921835", - "updated_at": "2021-03-11T25:40:09Z" + "updated_at": "2021-03-11T25:40:09.000000Z" } } ``` diff --git a/doc/models/v1-list-orders-response.md b/doc/models/v1-list-orders-response.md index 33be3754..30073de7 100644 --- a/doc/models/v1-list-orders-response.md +++ b/doc/models/v1-list-orders-response.md @@ -20,19 +20,19 @@ "errors": [ { "category": "MERCHANT_SUBSCRIPTION_ERROR", - "code": "INVALID_PHONE_NUMBER", + "code": "UNSUPPORTED_ENTRY_METHOD", "detail": "detail8", "field": "field6" }, { "category": "API_ERROR", - "code": "CHECKOUT_EXPIRED", + "code": "INVALID_ENCRYPTED_CARD", "detail": "detail9", "field": "field7" }, { "category": "AUTHENTICATION_ERROR", - "code": "BAD_CERTIFICATE", + "code": "INVALID_CARD", "detail": "detail0", "field": "field8" } @@ -46,7 +46,7 @@ "errors": [ { "category": "API_ERROR", - "code": "CHECKOUT_EXPIRED", + "code": "INVALID_ENCRYPTED_CARD", "detail": "detail9", "field": "field7" } diff --git a/doc/models/v1-order.md b/doc/models/v1-order.md index 22f3fb62..d1181c34 100644 --- a/doc/models/v1-order.md +++ b/doc/models/v1-order.md @@ -44,19 +44,19 @@ V1Order "errors": [ { "category": "AUTHENTICATION_ERROR", - "code": "UNPROCESSABLE_ENTITY", + "code": "MISSING_PIN", "detail": "detail1", "field": "field9" }, { "category": "INVALID_REQUEST_ERROR", - "code": "RATE_LIMITED", + "code": "MISSING_ACCOUNT_TYPE", "detail": "detail2", "field": "field0" }, { "category": "RATE_LIMIT_ERROR", - "code": "NOT_IMPLEMENTED", + "code": "INVALID_POSTAL_CODE", "detail": "detail3", "field": "field1" } diff --git a/doc/models/v1-payment-tax.md b/doc/models/v1-payment-tax.md index 9ce2dcba..cd95802e 100644 --- a/doc/models/v1-payment-tax.md +++ b/doc/models/v1-payment-tax.md @@ -25,19 +25,19 @@ V1PaymentTax "errors": [ { "category": "AUTHENTICATION_ERROR", - "code": "UNPROCESSABLE_ENTITY", + "code": "MISSING_PIN", "detail": "detail1", "field": "field9" }, { "category": "INVALID_REQUEST_ERROR", - "code": "RATE_LIMITED", + "code": "MISSING_ACCOUNT_TYPE", "detail": "detail2", "field": "field0" }, { "category": "RATE_LIMIT_ERROR", - "code": "NOT_IMPLEMENTED", + "code": "INVALID_POSTAL_CODE", "detail": "detail3", "field": "field1" } diff --git a/setup.py b/setup.py index 2fd5585b..7802e4d5 100644 --- a/setup.py +++ b/setup.py @@ -12,7 +12,7 @@ setup( name='squareup', - version='15.0.0.20211020', + version='16.0.0.20211117', description='Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.', long_description=long_description, long_description_content_type="text/markdown", diff --git a/square/api/apple_pay_api.py b/square/api/apple_pay_api.py index 12959f34..4125a666 100644 --- a/square/api/apple_pay_api.py +++ b/square/api/apple_pay_api.py @@ -56,7 +56,7 @@ def register_domain(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/base_api.py b/square/api/base_api.py index 12d14cc9..0ffc0172 100644 --- a/square/api/base_api.py +++ b/square/api/base_api.py @@ -21,7 +21,7 @@ class BaseApi(object): def global_headers(self): return { - 'user-agent': 'Square-Python-SDK/15.0.0.20211020', + 'user-agent': 'Square-Python-SDK/16.0.0.20211117', 'Square-Version': self.config.square_version } diff --git a/square/api/bookings_api.py b/square/api/bookings_api.py index f6400fbc..0e5a29ae 100644 --- a/square/api/bookings_api.py +++ b/square/api/bookings_api.py @@ -13,6 +13,84 @@ class BookingsApi(BaseApi): def __init__(self, config, call_back=None): super(BookingsApi, self).__init__(config, call_back) + def list_bookings(self, + limit=None, + cursor=None, + team_member_id=None, + location_id=None, + start_at_min=None, + start_at_max=None): + """Does a GET request to /v2/bookings. + + Retrieve a collection of bookings. + + Args: + limit (int, optional): The maximum number of results per page to + return in a paged response. + cursor (string, optional): The pagination cursor from the + preceding response to return the next page of the results. Do + not set this when retrieving the first page of the results. + team_member_id (string, optional): The team member for whom to + retrieve bookings. If this is not set, bookings of all members + are retrieved. + location_id (string, optional): The location for which to retrieve + bookings. If this is not set, all locations' bookings are + retrieved. + start_at_min (string, optional): The RFC 3339 timestamp specifying + the earliest of the start time. If this is not set, the + current time is used. + start_at_max (string, optional): The RFC 3339 timestamp specifying + the latest of the start time. If this is not set, the time of + 31 days after `start_at_min` is used. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + # Prepare query URL + _url_path = '/v2/bookings' + _query_builder = self.config.get_base_uri() + _query_builder += _url_path + _query_parameters = { + 'limit': limit, + 'cursor': cursor, + 'team_member_id': team_member_id, + 'location_id': location_id, + 'start_at_min': start_at_min, + 'start_at_max': start_at_max + } + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + _query_parameters + ) + _query_url = APIHelper.clean_url(_query_builder) + + # Prepare headers + _headers = { + 'accept': 'application/json' + } + + # Prepare and execute request + _request = self.config.http_client.get(_query_url, headers=_headers) + OAuth2.apply(self.config, _request) + _response = self.execute_request(_request) + + decoded = APIHelper.json_deserialize(_response.text) + if type(decoded) is dict: + _errors = decoded.get('errors') + else: + _errors = None + _result = ApiResponse(_response, body=decoded, errors=_errors) + return _result + def create_booking(self, body): """Does a POST request to /v2/bookings. @@ -45,7 +123,7 @@ def create_booking(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -93,7 +171,7 @@ def search_availability(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -351,7 +429,7 @@ def update_booking(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -405,7 +483,7 @@ def cancel_booking(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/cards_api.py b/square/api/cards_api.py index 5a9f1095..e89e76b9 100644 --- a/square/api/cards_api.py +++ b/square/api/cards_api.py @@ -121,7 +121,7 @@ def create_card(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/catalog_api.py b/square/api/catalog_api.py index 9381d20b..906b8bf4 100644 --- a/square/api/catalog_api.py +++ b/square/api/catalog_api.py @@ -59,7 +59,7 @@ def batch_delete_catalog_objects(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -115,7 +115,7 @@ def batch_retrieve_catalog_objects(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -178,7 +178,7 @@ def batch_upsert_catalog_objects(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -424,7 +424,7 @@ def upsert_catalog_object(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -631,7 +631,7 @@ def search_catalog_objects(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -696,7 +696,7 @@ def search_catalog_items(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -747,7 +747,7 @@ def update_item_modifier_lists(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -797,7 +797,7 @@ def update_item_taxes(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/checkout_api.py b/square/api/checkout_api.py index ed3b6784..f2e1e000 100644 --- a/square/api/checkout_api.py +++ b/square/api/checkout_api.py @@ -53,7 +53,7 @@ def create_checkout(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/customer_groups_api.py b/square/api/customer_groups_api.py index 1b6c8b02..bbd4e2c9 100644 --- a/square/api/customer_groups_api.py +++ b/square/api/customer_groups_api.py @@ -112,7 +112,7 @@ def create_customer_group(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -262,7 +262,7 @@ def update_customer_group(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/customers_api.py b/square/api/customers_api.py index 583d62d9..9a561fb5 100644 --- a/square/api/customers_api.py +++ b/square/api/customers_api.py @@ -135,7 +135,7 @@ def create_customer(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -194,7 +194,7 @@ def search_customers(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -378,7 +378,7 @@ def update_customer(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -438,7 +438,7 @@ def create_customer_card(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/devices_api.py b/square/api/devices_api.py index e5fe4732..b1bbbf88 100644 --- a/square/api/devices_api.py +++ b/square/api/devices_api.py @@ -118,7 +118,7 @@ def create_device_code(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/disputes_api.py b/square/api/disputes_api.py index 0cd96c9f..6c4d6502 100644 --- a/square/api/disputes_api.py +++ b/square/api/disputes_api.py @@ -358,7 +358,7 @@ def create_dispute_evidence_text(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/gift_card_activities_api.py b/square/api/gift_card_activities_api.py index 78621d40..08e7d7e0 100644 --- a/square/api/gift_card_activities_api.py +++ b/square/api/gift_card_activities_api.py @@ -34,31 +34,38 @@ def list_gift_card_activities(self, time window. Args: - gift_card_id (string, optional): If you provide a gift card ID, - the endpoint returns activities that belong to the specified - gift card. Otherwise, the endpoint returns all gift card - activities for the seller. - mtype (string, optional): If you provide a type, the endpoint - returns gift card activities of this type. Otherwise, the - endpoint returns all types of gift card activities. - location_id (string, optional): If you provide a location ID, the - endpoint returns gift card activities for that location. - Otherwise, the endpoint returns gift card activities for all - locations. + gift_card_id (string, optional): If a gift card ID is provided, + the endpoint returns activities related to the specified gift + card. Otherwise, the endpoint returns all gift card activities + for the seller. + mtype (string, optional): If a [type]($m/GiftCardActivityType) is + provided, the endpoint returns gift card activities of the + specified type. Otherwise, the endpoint returns all types of + gift card activities. + location_id (string, optional): If a location ID is provided, the + endpoint returns gift card activities for the specified + location. Otherwise, the endpoint returns gift card + activities for all locations. begin_time (string, optional): The timestamp for the beginning of - the reporting period, in RFC 3339 format. Inclusive. Default: - The current time minus one year. + the reporting period, in RFC 3339 format. This start time is + inclusive. The default value is the current time minus one + year. end_time (string, optional): The timestamp for the end of the - reporting period, in RFC 3339 format. Inclusive. Default: The - current time. - limit (int, optional): If you provide a limit value, the endpoint - returns the specified number of results (or less) per page. A - maximum value is 100. The default value is 50. + reporting period, in RFC 3339 format. This end time is + inclusive. The default value is the current time. + limit (int, optional): If a limit is provided, the endpoint + returns the specified number of results (or fewer) per page. + The maximum value is 100. The default value is 50. For more + information, see + [Pagination](https://developer.squareup.com/docs/working-with-a + pis/pagination). cursor (string, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to - retrieve the next set of results for the original query. If - you do not provide the cursor, the call returns the first page - of the results. + 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/working-with-a + pis/pagination). sort_order (string, optional): The order in which the endpoint returns the activities, based on `created_at`. - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default). @@ -150,7 +157,7 @@ def create_gift_card_activity(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/gift_cards_api.py b/square/api/gift_cards_api.py index 2a6eae27..6e47584e 100644 --- a/square/api/gift_cards_api.py +++ b/square/api/gift_cards_api.py @@ -25,25 +25,30 @@ def list_gift_cards(self, a subset of the gift cards. Args: - mtype (string, optional): If a type is provided, gift cards of - this type are returned (see [GiftCardType]($m/GiftCardType)). - If no type is provided, it returns gift cards of all types. - state (string, optional): If the state is provided, it returns the - gift cards in the specified state (see - [GiftCardStatus]($m/GiftCardStatus)). Otherwise, it returns - the gift cards of all states. - limit (int, optional): If a value is provided, it returns only - that number of results per page. The maximum number of results - allowed per page is 50. The default value is 30. + mtype (string, optional): If a [type]($m/GiftCardType) is + provided, the endpoint returns gift cards of the specified + type. Otherwise, the endpoint returns gift cards of all + types. + state (string, optional): If a [state]($m/GiftCardStatus) is + provided, the endpoint returns the gift cards in the specified + state. Otherwise, the endpoint returns the gift cards of all + states. + limit (int, optional): If a limit is provided, the endpoint + returns only the specified number of results per page. The + maximum value is 50. The default value is 30. For more + information, see + [Pagination](https://developer.squareup.com/docs/working-with-a + pis/pagination). cursor (string, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a - cursor is not provided, it returns the first page of the - results. For more information, see + cursor is not provided, the endpoint returns the first page of + the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-a pis/pagination). - customer_id (string, optional): If a value is provided, returns - only the gift cards linked to the specified customer + customer_id (string, optional): If a customer ID is provided, the + endpoint returns only the gift cards linked to the specified + customer. Returns: ApiResponse: An object with the response value as well as other @@ -129,7 +134,7 @@ def create_gift_card(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -177,7 +182,7 @@ def retrieve_gift_card_from_gan(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -197,8 +202,8 @@ def retrieve_gift_card_from_nonce(self, body): """Does a POST request to /v2/gift-cards/from-nonce. - Retrieves a gift card using a nonce (a secure token) that represents - the gift card. + Retrieves a gift card using a secure payment token that represents the + gift card. Args: body (RetrieveGiftCardFromNonceRequest): An object containing the @@ -226,7 +231,7 @@ def retrieve_gift_card_from_nonce(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -247,10 +252,11 @@ def link_customer_to_gift_card(self, body): """Does a POST request to /v2/gift-cards/{gift_card_id}/link-customer. - Links a customer to a gift card + Links a customer to a gift card, which is also referred to as adding a + card on file. Args: - gift_card_id (string): The ID of the gift card to link. + gift_card_id (string): The ID of the gift card to be linked. body (LinkCustomerToGiftCardRequest): An object containing the fields to POST for the request. See the corresponding object definition for field details. @@ -279,7 +285,7 @@ def link_customer_to_gift_card(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -300,10 +306,11 @@ def unlink_customer_from_gift_card(self, body): """Does a POST request to /v2/gift-cards/{gift_card_id}/unlink-customer. - Unlinks a customer from a gift card + Unlinks a customer from a gift card, which is also referred to as + removing a card on file. Args: - gift_card_id (string): TODO: type description here. + gift_card_id (string): The ID of the gift card to be unlinked. body (UnlinkCustomerFromGiftCardRequest): An object containing the fields to POST for the request. See the corresponding object definition for field details. @@ -332,7 +339,7 @@ def unlink_customer_from_gift_card(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/inventory_api.py b/square/api/inventory_api.py index 62cf99af..50eccb18 100644 --- a/square/api/inventory_api.py +++ b/square/api/inventory_api.py @@ -153,7 +153,7 @@ def deprecated_batch_change_inventory(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -205,7 +205,7 @@ def deprecated_batch_retrieve_inventory_changes(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -257,7 +257,7 @@ def deprecated_batch_retrieve_inventory_counts(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -308,7 +308,7 @@ def batch_change_inventory(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -362,7 +362,7 @@ def batch_retrieve_inventory_changes(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -421,7 +421,7 @@ def batch_retrieve_inventory_counts(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/invoices_api.py b/square/api/invoices_api.py index 569eca33..1188f53c 100644 --- a/square/api/invoices_api.py +++ b/square/api/invoices_api.py @@ -117,7 +117,7 @@ def create_invoice(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -174,7 +174,7 @@ def search_invoices(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -346,7 +346,7 @@ def update_invoice(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -403,7 +403,7 @@ def cancel_invoice(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -468,7 +468,7 @@ def publish_invoice(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/labor_api.py b/square/api/labor_api.py index 91e79ae5..e24c1d96 100644 --- a/square/api/labor_api.py +++ b/square/api/labor_api.py @@ -121,7 +121,7 @@ def create_break_type(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -271,7 +271,7 @@ def update_break_type(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -448,7 +448,7 @@ def create_shift(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -508,7 +508,7 @@ def search_shifts(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -663,7 +663,7 @@ def update_shift(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -886,7 +886,7 @@ def update_workweek_config(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/locations_api.py b/square/api/locations_api.py index d300ee01..f2cf7e5a 100644 --- a/square/api/locations_api.py +++ b/square/api/locations_api.py @@ -90,7 +90,7 @@ def create_location(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -195,7 +195,7 @@ def update_location(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/loyalty_api.py b/square/api/loyalty_api.py index de0a7641..14d0d38a 100644 --- a/square/api/loyalty_api.py +++ b/square/api/loyalty_api.py @@ -48,7 +48,7 @@ def create_loyalty_account(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -100,7 +100,7 @@ def search_loyalty_accounts(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -219,7 +219,7 @@ def accumulate_loyalty_points(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -277,7 +277,7 @@ def adjust_loyalty_points(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -332,7 +332,7 @@ def search_loyalty_events(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -507,7 +507,7 @@ def calculate_loyalty_points(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -563,7 +563,7 @@ def create_loyalty_reward(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -616,7 +616,7 @@ def search_loyalty_rewards(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -782,7 +782,7 @@ def redeem_loyalty_reward(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/mobile_authorization_api.py b/square/api/mobile_authorization_api.py index 39ee60cb..5d42fcad 100644 --- a/square/api/mobile_authorization_api.py +++ b/square/api/mobile_authorization_api.py @@ -57,7 +57,7 @@ def create_mobile_authorization_code(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/o_auth_api.py b/square/api/o_auth_api.py index 8037983a..b065a4f8 100644 --- a/square/api/o_auth_api.py +++ b/square/api/o_auth_api.py @@ -77,7 +77,7 @@ def renew_token(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8', + 'Content-Type': 'application/json', 'Authorization': authorization } @@ -142,7 +142,7 @@ def revoke_token(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8', + 'Content-Type': 'application/json', 'Authorization': authorization } @@ -211,7 +211,7 @@ def obtain_token(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/orders_api.py b/square/api/orders_api.py index 656a19fc..6cefadd1 100644 --- a/square/api/orders_api.py +++ b/square/api/orders_api.py @@ -52,7 +52,7 @@ def create_order(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -102,7 +102,7 @@ def batch_retrieve_orders(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -151,7 +151,7 @@ def calculate_order(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -202,7 +202,7 @@ def clone_order(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -270,7 +270,7 @@ def search_orders(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -390,7 +390,7 @@ def update_order(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -461,7 +461,7 @@ def pay_order(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/payments_api.py b/square/api/payments_api.py index f69bc7d3..9843f654 100644 --- a/square/api/payments_api.py +++ b/square/api/payments_api.py @@ -153,7 +153,7 @@ def create_payment(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -216,7 +216,7 @@ def cancel_payment_by_idempotency_key(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -319,7 +319,7 @@ def update_payment(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -427,7 +427,7 @@ def complete_payment(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/refunds_api.py b/square/api/refunds_api.py index e4ff1247..bf1d9765 100644 --- a/square/api/refunds_api.py +++ b/square/api/refunds_api.py @@ -152,7 +152,7 @@ def refund_payment(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/sites_api.py b/square/api/sites_api.py index 7ab09343..989589b8 100644 --- a/square/api/sites_api.py +++ b/square/api/sites_api.py @@ -16,7 +16,8 @@ def __init__(self, config, call_back=None): def list_sites(self): """Does a GET request to /v2/sites. - Lists the Square Online sites that belong to a seller. + Lists the Square Online sites that belong to a seller. Sites are + listed in descending order by the `created_at` date. __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online diff --git a/square/api/snippets_api.py b/square/api/snippets_api.py index 4366968a..e65fb5f6 100644 --- a/square/api/snippets_api.py +++ b/square/api/snippets_api.py @@ -174,7 +174,7 @@ def upsert_snippet(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/subscriptions_api.py b/square/api/subscriptions_api.py index 738c665c..20eac9c0 100644 --- a/square/api/subscriptions_api.py +++ b/square/api/subscriptions_api.py @@ -17,7 +17,7 @@ def create_subscription(self, body): """Does a POST request to /v2/subscriptions. - Creates a subscription for a customer to a subscription plan. + Creates a subscription to a subscription plan by a customer. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square bills an invoice to the customer's @@ -53,7 +53,7 @@ def create_subscription(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -117,7 +117,7 @@ def search_subscriptions(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -134,13 +134,18 @@ def search_subscriptions(self, return _result def retrieve_subscription(self, - subscription_id): + subscription_id, + include=None): """Does a GET request to /v2/subscriptions/{subscription_id}. Retrieves a subscription. Args: subscription_id (string): The ID of the subscription to retrieve. + include (string, optional): A query parameter to specify related + information to be included in the response. The supported + query parameter values are: - `actions`: to include + scheduled actions on the targeted subscription. Returns: ApiResponse: An object with the response value as well as other @@ -161,6 +166,13 @@ def retrieve_subscription(self, }) _query_builder = self.config.get_base_uri() _query_builder += _url_path + _query_parameters = { + 'include': include + } + _query_builder = APIHelper.append_url_with_query_parameters( + _query_builder, + _query_parameters + ) _query_url = APIHelper.clean_url(_query_builder) # Prepare headers @@ -190,7 +202,7 @@ def update_subscription(self, `subscription` field values. Args: - subscription_id (string): The ID for the subscription to update. + subscription_id (string): The ID of the subscription to update. body (UpdateSubscriptionRequest): An object containing the fields to POST for the request. See the corresponding object definition for field details. @@ -219,7 +231,7 @@ def update_subscription(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -235,13 +247,67 @@ def update_subscription(self, _result = ApiResponse(_response, body=decoded, errors=_errors) return _result + def delete_subscription_action(self, + subscription_id, + action_id): + """Does a DELETE request to /v2/subscriptions/{subscription_id}/actions/{action_id}. + + Deletes a scheduled action for a subscription. + + Args: + subscription_id (string): The ID of the subscription the targeted + action is to act upon. + action_id (string): The ID of the targeted action to be deleted. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + # Prepare query URL + _url_path = '/v2/subscriptions/{subscription_id}/actions/{action_id}' + _url_path = APIHelper.append_url_with_template_parameters(_url_path, { + 'subscription_id': {'value': subscription_id, 'encode': True}, + 'action_id': {'value': action_id, 'encode': True} + }) + _query_builder = self.config.get_base_uri() + _query_builder += _url_path + _query_url = APIHelper.clean_url(_query_builder) + + # Prepare headers + _headers = { + 'accept': 'application/json' + } + + # Prepare and execute request + _request = self.config.http_client.delete(_query_url, headers=_headers) + OAuth2.apply(self.config, _request) + _response = self.execute_request(_request) + + decoded = APIHelper.json_deserialize(_response.text) + if type(decoded) is dict: + _errors = decoded.get('errors') + else: + _errors = None + _result = ApiResponse(_response, body=decoded, errors=_errors) + return _result + def cancel_subscription(self, subscription_id): """Does a POST request to /v2/subscriptions/{subscription_id}/cancel. - Sets the `canceled_date` field to the end of the active billing - period. - After this date, the status changes from ACTIVE to CANCELED. + Schedules a `CANCEL` action to cancel an active subscription + by setting the `canceled_date` field to the end of the active billing + period + and changing the subscription status from ACTIVE to CANCELED after + this date. Args: subscription_id (string): The ID of the subscription to cancel. @@ -299,15 +365,16 @@ def list_subscription_events(self, Args: subscription_id (string): The ID of the subscription to retrieve the events for. - cursor (string, optional): A pagination cursor returned by a - previous call to this endpoint. Provide this to retrieve the - next set of results for the original query. For more + cursor (string, optional): When the total number of resulting + subscription events exceeds the limit of a paged response, + specify the cursor returned from a preceding response here to + fetch the next set of results. If the cursor is unset, the + response contains the last page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-a pis/pagination). limit (int, optional): The upper limit on the number of - subscription events to return in the response. Default: - `200` + subscription events to return in a paged response. Returns: ApiResponse: An object with the response value as well as other @@ -356,14 +423,72 @@ def list_subscription_events(self, _result = ApiResponse(_response, body=decoded, errors=_errors) return _result + def pause_subscription(self, + subscription_id, + body): + """Does a POST request to /v2/subscriptions/{subscription_id}/pause. + + Schedules a `PAUSE` action to pause an active subscription. + + Args: + subscription_id (string): The ID of the subscription to pause. + body (PauseSubscriptionRequest): An object containing the fields + to POST for the request. See the corresponding object + definition for field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + # Prepare query URL + _url_path = '/v2/subscriptions/{subscription_id}/pause' + _url_path = APIHelper.append_url_with_template_parameters(_url_path, { + 'subscription_id': {'value': subscription_id, 'encode': True} + }) + _query_builder = self.config.get_base_uri() + _query_builder += _url_path + _query_url = APIHelper.clean_url(_query_builder) + + # Prepare headers + _headers = { + 'accept': 'application/json', + 'Content-Type': 'application/json' + } + + # Prepare and execute request + _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body)) + OAuth2.apply(self.config, _request) + _response = self.execute_request(_request) + + decoded = APIHelper.json_deserialize(_response.text) + if type(decoded) is dict: + _errors = decoded.get('errors') + else: + _errors = None + _result = ApiResponse(_response, body=decoded, errors=_errors) + return _result + def resume_subscription(self, - subscription_id): + subscription_id, + body): """Does a POST request to /v2/subscriptions/{subscription_id}/resume. - Resumes a deactivated subscription. + Schedules a `RESUME` action to resume a paused or a deactivated + subscription. Args: subscription_id (string): The ID of the subscription to resume. + body (ResumeSubscriptionRequest): 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 @@ -388,11 +513,67 @@ def resume_subscription(self, # Prepare headers _headers = { - 'accept': 'application/json' + 'accept': 'application/json', + 'Content-Type': 'application/json' } # Prepare and execute request - _request = self.config.http_client.post(_query_url, headers=_headers) + _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body)) + OAuth2.apply(self.config, _request) + _response = self.execute_request(_request) + + decoded = APIHelper.json_deserialize(_response.text) + if type(decoded) is dict: + _errors = decoded.get('errors') + else: + _errors = None + _result = ApiResponse(_response, body=decoded, errors=_errors) + return _result + + def swap_plan(self, + subscription_id, + body): + """Does a POST request to /v2/subscriptions/{subscription_id}/swap-plan. + + Schedules a `SWAP_PLAN` action to swap a subscription plan in an + existing subscription. + + Args: + subscription_id (string): The ID of the subscription to swap the + subscription plan for. + body (SwapPlanRequest): An object containing the fields to POST + for the request. See the corresponding object definition for + field details. + + Returns: + ApiResponse: An object with the response value as well as other + useful information such as status codes and headers. Success + + Raises: + APIException: When an error occurs while fetching the data from + the remote API. This exception includes the HTTP Response + code, an error message, and the HTTP body that was received in + the request. + + """ + + # Prepare query URL + _url_path = '/v2/subscriptions/{subscription_id}/swap-plan' + _url_path = APIHelper.append_url_with_template_parameters(_url_path, { + 'subscription_id': {'value': subscription_id, 'encode': True} + }) + _query_builder = self.config.get_base_uri() + _query_builder += _url_path + _query_url = APIHelper.clean_url(_query_builder) + + # Prepare headers + _headers = { + 'accept': 'application/json', + 'Content-Type': 'application/json' + } + + # Prepare and execute request + _request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body)) OAuth2.apply(self.config, _request) _response = self.execute_request(_request) diff --git a/square/api/team_api.py b/square/api/team_api.py index 7f34c33a..8194e9cd 100644 --- a/square/api/team_api.py +++ b/square/api/team_api.py @@ -53,7 +53,7 @@ def create_team_member(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -110,7 +110,7 @@ def bulk_create_team_members(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -167,7 +167,7 @@ def bulk_update_team_members(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -218,7 +218,7 @@ def search_team_members(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -326,7 +326,7 @@ def update_team_member(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -440,7 +440,7 @@ def update_wage_setting(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/terminal_api.py b/square/api/terminal_api.py index ab0fad75..65dd4579 100644 --- a/square/api/terminal_api.py +++ b/square/api/terminal_api.py @@ -47,7 +47,7 @@ def create_terminal_checkout(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -96,7 +96,7 @@ def search_terminal_checkouts(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -244,7 +244,7 @@ def create_terminal_refund(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -293,7 +293,7 @@ def search_terminal_refunds(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/api/v1_transactions_api.py b/square/api/v1_transactions_api.py index 41934098..aed02568 100644 --- a/square/api/v1_transactions_api.py +++ b/square/api/v1_transactions_api.py @@ -180,7 +180,7 @@ def update_order(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request @@ -489,7 +489,7 @@ def create_refund(self, # Prepare headers _headers = { 'accept': 'application/json', - 'content-type': 'application/json; charset=utf-8' + 'Content-Type': 'application/json' } # Prepare and execute request diff --git a/square/client.py b/square/client.py index d9a48e60..898c964d 100644 --- a/square/client.py +++ b/square/client.py @@ -41,11 +41,11 @@ class Client(object): @staticmethod def sdk_version(): - return '15.0.0.20211020' + return '16.0.0.20211117' @staticmethod def square_version(): - return '2021-10-20' + return '2021-11-17' @lazy_property def mobile_authorization(self): @@ -179,22 +179,27 @@ def team(self): def terminal(self): return TerminalApi(self.config) - def __init__(self, timeout=60, max_retries=0, backoff_factor=2, + def __init__(self, http_client_instance=None, + override_http_client_configuration=False, timeout=60, + max_retries=0, backoff_factor=2, retry_statuses=[408, 413, 429, 500, 502, 503, 504, 521, 522, 524], retry_methods=['GET', 'PUT'], environment='production', custom_url='https://connect.squareup.com', - square_version='2021-10-20', access_token='TODO: Replace', + square_version='2021-11-17', access_token='', additional_headers={}, config=None): if config is None: - self.config = Configuration(timeout=timeout, - max_retries=max_retries, - backoff_factor=backoff_factor, - retry_statuses=retry_statuses, - retry_methods=retry_methods, - environment=environment, - custom_url=custom_url, - square_version=square_version, - access_token=access_token, - additional_headers=additional_headers) + self.config = Configuration( + http_client_instance=http_client_instance, + override_http_client_configuration=override_http_client_configuration, + timeout=timeout, + max_retries=max_retries, + backoff_factor=backoff_factor, + retry_statuses=retry_statuses, + retry_methods=retry_methods, + environment=environment, + custom_url=custom_url, + square_version=square_version, + access_token=access_token, + additional_headers=additional_headers) else: self.config = config diff --git a/square/configuration.py b/square/configuration.py index 450e8bb7..c6877197 100644 --- a/square/configuration.py +++ b/square/configuration.py @@ -13,6 +13,14 @@ class Configuration(object): def http_client(self): return self._http_client + @property + def http_client_instance(self): + return self._http_client_instance + + @property + def override_http_client_configuration(self): + return self._override_http_client_configuration + @property def timeout(self): return self._timeout @@ -54,12 +62,20 @@ def additional_headers(self): return deepcopy(self._additional_headers) def __init__( - self, timeout=60, max_retries=0, backoff_factor=2, + self, http_client_instance=None, + override_http_client_configuration=False, timeout=60, max_retries=0, + backoff_factor=2, retry_statuses=[408, 413, 429, 500, 502, 503, 504, 521, 522, 524], retry_methods=['GET', 'PUT'], environment='production', - custom_url='https://connect.squareup.com', square_version='2021-10-20', - access_token='TODO: Replace', additional_headers={} + custom_url='https://connect.squareup.com', square_version='2021-11-17', + access_token='', additional_headers={} ): + # The Http Client passed from the sdk user for making requests + self._http_client_instance = http_client_instance + + # The value which determines to override properties of the passed Http Client from the sdk user + self._override_http_client_configuration = override_http_client_configuration + # The value to use for connection timeout self._timeout = timeout @@ -95,10 +111,14 @@ def __init__( # The Http Client to use for making requests. self._http_client = self.create_http_client() - def clone_with(self, timeout=None, max_retries=None, backoff_factor=None, - retry_statuses=None, retry_methods=None, environment=None, - custom_url=None, square_version=None, access_token=None, + def clone_with(self, http_client_instance=None, + override_http_client_configuration=None, timeout=None, + max_retries=None, backoff_factor=None, retry_statuses=None, + retry_methods=None, environment=None, custom_url=None, + square_version=None, access_token=None, additional_headers=None): + http_client_instance = http_client_instance or self.http_client_instance + override_http_client_configuration = override_http_client_configuration or self.override_http_client_configuration timeout = timeout or self.timeout max_retries = max_retries or self.max_retries backoff_factor = backoff_factor or self.backoff_factor @@ -110,21 +130,24 @@ def clone_with(self, timeout=None, max_retries=None, backoff_factor=None, access_token = access_token or self.access_token additional_headers = additional_headers or self.additional_headers - return Configuration(timeout=timeout, max_retries=max_retries, - backoff_factor=backoff_factor, - retry_statuses=retry_statuses, - retry_methods=retry_methods, - environment=environment, custom_url=custom_url, - square_version=square_version, - access_token=access_token, - additional_headers=additional_headers) + return Configuration( + http_client_instance=http_client_instance, + override_http_client_configuration=override_http_client_configuration, + timeout=timeout, max_retries=max_retries, + backoff_factor=backoff_factor, retry_statuses=retry_statuses, + retry_methods=retry_methods, environment=environment, + custom_url=custom_url, square_version=square_version, + access_token=access_token, additional_headers=additional_headers + ) def create_http_client(self): - return RequestsClient(timeout=self.timeout, - max_retries=self.max_retries, - backoff_factor=self.backoff_factor, - retry_statuses=self.retry_statuses, - retry_methods=self.retry_methods) + return RequestsClient( + timeout=self.timeout, max_retries=self.max_retries, + backoff_factor=self.backoff_factor, retry_statuses=self.retry_statuses, + retry_methods=self.retry_methods, + http_client_instance=self.http_client_instance, + override_http_client_configuration=self.override_http_client_configuration + ) # All the environments the SDK can run in environments = { diff --git a/square/http/requests_client.py b/square/http/requests_client.py index 3ed0d15e..e2d94c65 100644 --- a/square/http/requests_client.py +++ b/square/http/requests_client.py @@ -26,13 +26,41 @@ def __init__(self, backoff_factor=None, retry_statuses=None, retry_methods=None, - verify=True): + verify=True, + http_client_instance=None, + override_http_client_configuration=False): """The constructor. Args: timeout (float): The default global timeout(seconds). """ + if http_client_instance == None: + self.create_default_http_cient(timeout, cache, max_retries, + backoff_factor, retry_statuses, + retry_methods, verify) + else: + if override_http_client_configuration == True: + http_client_instance.timeout = timeout + http_client_instance.session.verify = verify + adapters = http_client_instance.session.adapters + for adapter in adapters.values(): + adapter.max_retries.total = max_retries + adapter.max_retries.backoff_factor = backoff_factor + adapter.max_retries.status_forcelist = retry_statuses + adapter.max_retries.allowed_methods = retry_methods + + self.timeout = http_client_instance.timeout + self.session = http_client_instance.session + + def create_default_http_cient(self, + timeout=60, + cache=False, + max_retries=None, + backoff_factor=None, + retry_statuses=None, + retry_methods=None, + verify=True): self.timeout = timeout self.session = session()