Merge pull request #114 from square/release/28.0.0.20230608

Generated PR for Release: 28.0.0.20230608

Author: jessdelacruzsantos

doc/api/o-auth.md

@@ -37,7 +37,7 @@ following format:
 Authorization: Client APPLICATION_SECRET
 ```
 
-Replace `APPLICATION_SECRET` with the application secret on the Credentials
+Replace `APPLICATION_SECRET` with the application secret on the **Credentials**
 page in the [Developer Dashboard](https://developer.squareup.com/apps).
 
 :information_source: **Note** This endpoint does not require authentication.
@@ -53,7 +53,7 @@ def renew_token(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `client_id` | `string` | Template, Required | Your application ID, which is available in the OAuth page in the [Developer Dashboard](https://developer.squareup.com/apps). |
+| `client_id` | `string` | Template, Required | Your application ID, which is available on the **OAuth** page in the [Developer Dashboard](https://developer.squareup.com/apps). |
 | `body` | [`Renew Token Request`](../../doc/models/renew-token-request.md) | Body, Required | An object containing the fields to POST for the request.<br><br>See the corresponding object definition for field details. |
 | `authorization` | `string` | Header, Required | Client APPLICATION_SECRET |
 
@@ -102,8 +102,8 @@ following format:
 Authorization: Client APPLICATION_SECRET
 ```
 
-Replace `APPLICATION_SECRET` with the application secret on the OAuth
-page for your application on the Developer Dashboard.
+Replace `APPLICATION_SECRET` with the application secret on the **OAuth**
+page for your application in the Developer Dashboard.
 
 :information_source: **Note** This endpoint does not require authentication.
 
@@ -156,7 +156,7 @@ returns only an access token.
 The `grant_type` parameter specifies the type of OAuth request. If
 `grant_type` is `authorization_code`, you must include the authorization
 code you received when a seller granted you authorization. If `grant_type`
-is `refresh_token`, you must provide a valid refresh token. If you are using
+is `refresh_token`, you must provide a valid refresh token. If you're using
 an old version of the Square APIs (prior to March 13, 2019), `grant_type`
 can be `migration_token` and you must provide a valid migration token.
 

doc/api/subscriptions.md

@@ -24,13 +24,15 @@ subscriptions_api = client.subscriptions
 
 # Create Subscription
 
-Creates a subscription to a subscription plan by a customer.
+Enrolls a customer in a subscription.
 
 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
+the subscription. Otherwise, Square sends an invoice to the customer's email
 address. The subscription starts immediately, unless the request includes
 the optional `start_date`. Each individual subscription is associated with a particular location.
 
+For more information, see [Create a subscription](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#create-a-subscription).
+
 ```python
 def create_subscription(self,
                        body)
@@ -51,9 +53,9 @@ def create_subscription(self,
 ```python
 body = {
     'location_id': 'S8GWD5R9QB376',
-    'plan_id': '6JHXF3B2CW3YKHDV4XEM674H',
     'customer_id': 'CHFGVKYY8RSV93M5KCYTG4PN0G',
     'idempotency_key': '8193148c-9586-11e6-99f9-28cfe92138cf',
+    'plan_id': '6JHXF3B2CW3YKHDV4XEM674H',
     'start_date': '2021-10-20',
     'tax_percentage': '5',
     'price_override_money': {
@@ -94,9 +96,6 @@ If the request specifies customer IDs, the endpoint orders results
 first by location, within location by customer ID, and within
 customer by subscription creation date.
 
-For more information, see
-[Retrieve subscriptions](https://developer.squareup.com/docs/subscriptions-api/overview#retrieve-subscriptions).
-
 ```python
 def search_subscriptions(self,
                         body)
@@ -143,7 +142,7 @@ elif result.is_error():
 
 # Retrieve Subscription
 
-Retrieves a subscription.
+Retrieves a specific subscription.
 
 ```python
 def retrieve_subscription(self,
@@ -179,8 +178,8 @@ elif result.is_error():
 
 # Update Subscription
 
-Updates a subscription. You can set, modify, and clear the
-`subscription` field values.
+Updates a subscription by modifying or clearing `subscription` field values.
+To clear a field, set its value to `null`.
 
 ```python
 def update_subscription(self,
@@ -264,9 +263,9 @@ elif result.is_error():
 
 # Cancel Subscription
 
-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.
+Schedules a `CANCEL` action to cancel an active subscription. This
+sets the `canceled_date` field to the end of the active billing period. After this date,
+the subscription status changes from ACTIVE to CANCELED.
 
 ```python
 def cancel_subscription(self,
@@ -300,7 +299,7 @@ elif result.is_error():
 
 # List Subscription Events
 
-Lists all events for a specific subscription.
+Lists all [events](https://developer.squareup.com/docs/subscriptions-api/actions-events) for a specific subscription.
 
 ```python
 def list_subscription_events(self,
@@ -314,7 +313,7 @@ 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 | When the total number of resulting subscription events exceeds the limit of a paged response,<br>specify the cursor returned from a preceding response here to fetch the next set of results.<br>If the cursor is unset, the response contains the last page of the results.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
+| `cursor` | `string` | Query, Optional | When the total number of resulting subscription events exceeds the limit of a paged response,<br>specify the cursor returned from a preceding response here to fetch the next set of results.<br>If the cursor is unset, the response contains the last page of the results.<br><br>For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
 | `limit` | `int` | Query, Optional | The upper limit on the number of subscription events to return<br>in a paged response. |
 
 ## Response Type
@@ -420,7 +419,8 @@ elif result.is_error():
 
 # Swap Plan
 
-Schedules a `SWAP_PLAN` action to swap a subscription plan in an existing subscription.
+Schedules a `SWAP_PLAN` action to swap a subscription plan variation in an existing subscription.
+For more information, see [Swap Subscription Plan Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).
 
 ```python
 def swap_plan(self,
@@ -444,9 +444,7 @@ def swap_plan(self,
 ```python
 subscription_id = 'subscription_id0'
 
-body = {
-    None
-}
+body = {}
 
 result = subscriptions_api.swap_plan(
     subscription_id,

doc/api/terminal.md

@@ -14,6 +14,7 @@ terminal_api = client.terminal
 * [Search Terminal Actions](../../doc/api/terminal.md#search-terminal-actions)
 * [Get Terminal Action](../../doc/api/terminal.md#get-terminal-action)
 * [Cancel Terminal Action](../../doc/api/terminal.md#cancel-terminal-action)
+* [Dismiss Terminal Action](../../doc/api/terminal.md#dismiss-terminal-action)
 * [Create Terminal Checkout](../../doc/api/terminal.md#create-terminal-checkout)
 * [Search Terminal Checkouts](../../doc/api/terminal.md#search-terminal-checkouts)
 * [Get Terminal Checkout](../../doc/api/terminal.md#get-terminal-checkout)
@@ -128,7 +129,7 @@ def get_terminal_action(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `action_id` | `string` | Template, Required | Unique ID for the desired `TerminalAction` |
+| `action_id` | `string` | Template, Required | Unique ID for the desired `TerminalAction`. |
 
 ## Response Type
 
@@ -162,7 +163,7 @@ def cancel_terminal_action(self,
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `action_id` | `string` | Template, Required | Unique ID for the desired `TerminalAction` |
+| `action_id` | `string` | Template, Required | Unique ID for the desired `TerminalAction`. |
 
 ## Response Type
 
@@ -183,6 +184,42 @@ elif result.is_error():
 ```
 
 
+# Dismiss Terminal Action
+
+Dismisses a Terminal action request if the status and type of the request permits it.
+
+See [Link and Dismiss Actions](https://developer.squareup.com/docs/terminal-api/advanced-features/custom-workflows/link-and-dismiss-actions) for more details.
+
+```python
+def dismiss_terminal_action(self,
+                           action_id)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `action_id` | `string` | Template, Required | Unique ID for the `TerminalAction` associated with the waiting dialog to be dismissed. |
+
+## Response Type
+
+[`Dismiss Terminal Action Response`](../../doc/models/dismiss-terminal-action-response.md)
+
+## Example Usage
+
+```python
+action_id = 'action_id6'
+
+result = terminal_api.dismiss_terminal_action(action_id)
+print(result)
+
+if result.is_success():
+    print(result.body)
+elif result.is_error():
+    print(result.errors)
+```
+
+
 # Create Terminal Checkout
 
 Creates a Terminal checkout request and sends it to the specified device to take a payment

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `square_version` | `string` | Square Connect API versions<br>*Default*: `'2023-05-17'` |
+| `square_version` | `string` | Square Connect API versions<br>*Default*: `'2023-06-08'` |
 | `custom_url` | `string` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`<br>*Default*: `'https://connect.squareup.com'` |
 | `environment` | `string` | The API environment. <br> **Default: `production`** |
 | `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests |
@@ -25,7 +25,7 @@ The API client can be initialized as follows:
 ```python
 from square.client import Client
 client = Client(
-    square_version='2023-05-17',
+    square_version='2023-06-08',
     access_token='AccessToken'
 )
 ```
@@ -48,7 +48,7 @@ API calls return an `ApiResponse` object that includes the following fields:
 ```python
 from square.client import Client
 client = Client(
-    square_version='2023-05-17',
+    square_version='2023-06-08',
     access_token='AccessToken'
 )
 

doc/models/activity-type.md

@@ -44,4 +44,8 @@
 | `THIRD_PARTY_FEE` | Fees collected by a third-party platform. |
 | `THIRD_PARTY_FEE_REFUND` | Refunded fees from a third-party platform. |
 | `PAYOUT` | Balance change due to money transfer. |
+| `AUTOMATIC_BITCOIN_CONVERSIONS` | Indicates the withholding of a portion of each payment by Square that has been<br>automatically converted into bitcoin using Cash App. The seller manages their bitcoin in<br>their Cash App account. |
+| `AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED` | Indicates a return of the payment withholding that had been scheduled to be converted<br>into bitcoin using Cash App to the Square payments balance. |
+| `CREDIT_CARD_REPAYMENT` | The repayment made toward the outstanding balance on the seller's Square credit card. |
+| `CREDIT_CARD_REPAYMENT_REVERSED` | The reversal of the repayment made toward the outstanding balance on the seller's<br>Square credit card. |
 

doc/models/cancel-subscription-response.md

@@ -13,7 +13,7 @@ Defines output parameters in a response from the
 | 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.<br><br>For an overview of the `Subscription` type, see<br>[Subscription object](https://developer.squareup.com/docs/subscriptions-api/overview#subscription-object-overview). |
+| `subscription` | [`Subscription`](../../doc/models/subscription.md) | Optional | Represents a subscription purchased by a customer.<br><br>For more information, see<br>[Manage Subscriptions](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions). |
 | `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)
@@ -35,7 +35,8 @@ Defines output parameters in a response from the
     "start_date": "2021-10-20",
     "status": "ACTIVE",
     "timezone": "America/Los_Angeles",
-    "version": 1594311617331
+    "version": 1594311617331,
+    "plan_variation_id": "plan_variation_id8"
   },
   "errors": [
     {
@@ -62,19 +63,61 @@ Defines output parameters in a response from the
       "id": "id9",
       "type": "PAUSE",
       "effective_date": "effective_date1",
-      "new_plan_id": "new_plan_id5"
+      "phases": [
+        {
+          "uid": "uid6",
+          "ordinal": 186,
+          "order_template_id": "order_template_id8",
+          "plan_phase_uid": "plan_phase_uid2"
+        }
+      ],
+      "new_plan_variation_id": "new_plan_variation_id9"
     },
     {
       "id": "id0",
       "type": "CANCEL",
       "effective_date": "effective_date0",
-      "new_plan_id": "new_plan_id6"
+      "phases": [
+        {
+          "uid": "uid5",
+          "ordinal": 185,
+          "order_template_id": "order_template_id7",
+          "plan_phase_uid": "plan_phase_uid1"
+        },
+        {
+          "uid": "uid6",
+          "ordinal": 186,
+          "order_template_id": "order_template_id8",
+          "plan_phase_uid": "plan_phase_uid2"
+        },
+        {
+          "uid": "uid7",
+          "ordinal": 187,
+          "order_template_id": "order_template_id9",
+          "plan_phase_uid": "plan_phase_uid3"
+        }
+      ],
+      "new_plan_variation_id": "new_plan_variation_id0"
     },
     {
       "id": "id1",
       "type": "SWAP_PLAN",
       "effective_date": "effective_date9",
-      "new_plan_id": "new_plan_id7"
+      "phases": [
+        {
+          "uid": "uid4",
+          "ordinal": 184,
+          "order_template_id": "order_template_id6",
+          "plan_phase_uid": "plan_phase_uid0"
+        },
+        {
+          "uid": "uid5",
+          "ordinal": 185,
+          "order_template_id": "order_template_id7",
+          "plan_phase_uid": "plan_phase_uid1"
+        }
+      ],
+      "new_plan_variation_id": "new_plan_variation_id1"
     }
   ]
 }

doc/models/cancel-terminal-checkout-response.md

@@ -24,7 +24,7 @@
     "app_id": "APP_ID",
     "cancel_reason": "SELLER_CANCELED",
     "created_at": "2020-03-16T15:31:19.934Z",
-    "deadline_duration": "PT10M",
+    "deadline_duration": "PT5M",
     "device_options": {
       "device_id": "dbb5d83a-7838-11ea-bc55-0242ac130003",
       "skip_receipt_screen": true,

doc/models/catalog-custom-attribute-definition.md

@@ -41,9 +41,9 @@ to store any sensitive information (personally identifiable information, card de
     "name": "name2"
   },
   "allowed_object_types": [
-    "PRICING_RULE",
-    "PRODUCT_SET",
-    "TIME_PERIOD"
+    "TIME_PERIOD",
+    "MEASUREMENT_UNIT",
+    "SUBSCRIPTION_PLAN_VARIATION"
   ],
   "seller_visibility": "SELLER_VISIBILITY_HIDDEN",
   "app_visibility": "APP_VISIBILITY_HIDDEN",

doc/models/catalog-item-option.md

@@ -27,7 +27,7 @@ A group of variations for a `CatalogItem`.
   "show_colors": false,
   "values": [
     {
-      "type": "MODIFIER",
+      "type": "TAX",
       "id": "id0",
       "updated_at": "updated_at6",
       "version": 100,
@@ -71,7 +71,7 @@ A group of variations for a `CatalogItem`.
       ]
     },
     {
-      "type": "MODIFIER_LIST",
+      "type": "ITEM_VARIATION",
       "id": "id1",
       "updated_at": "updated_at7",
       "version": 101,
@@ -100,7 +100,7 @@ A group of variations for a `CatalogItem`.
       ]
     },
     {
-      "type": "DISCOUNT",
+      "type": "CATEGORY",
       "id": "id2",
       "updated_at": "updated_at8",
       "version": 102,