Merge pull request #116 from square/release/28.0.0.20230608

Generated PR for Release: 28.0.0.20230608

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "square/square",
     "description": "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.",
-    "version": "27.0.0.20230517",
+    "version": "28.0.0.20230608",
     "type": "library",
     "keywords": [
         "Square",

doc/apis/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.
@@ -50,7 +50,7 @@ function renewToken(string $clientId, RenewTokenRequest $body, string $authoriza
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `clientId` | `string` | Template, Required | Your application ID, which is available in the OAuth page in the [Developer Dashboard](https://developer.squareup.com/apps). |
+| `clientId` | `string` | Template, Required | Your application ID, which is available on the **OAuth** page in the [Developer Dashboard](https://developer.squareup.com/apps). |
 | `body` | [`RenewTokenRequest`](../../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 |
 
@@ -103,8 +103,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.
 
@@ -159,7 +159,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/apis/subscriptions.md

@@ -24,13 +24,15 @@ $subscriptionsApi = $client->getSubscriptionsApi();
 
 # 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).
+
 ```php
 function createSubscription(CreateSubscriptionRequest $body): ApiResponse
 ```
@@ -50,10 +52,10 @@ This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` met
 ```php
 $body = CreateSubscriptionRequestBuilder::init(
     'S8GWD5R9QB376',
-    '6JHXF3B2CW3YKHDV4XEM674H',
     'CHFGVKYY8RSV93M5KCYTG4PN0G'
 )
     ->idempotencyKey('8193148c-9586-11e6-99f9-28cfe92138cf')
+    ->planId('6JHXF3B2CW3YKHDV4XEM674H')
     ->startDate('2021-10-20')
     ->taxPercentage('5')
     ->priceOverrideMoney(
@@ -102,9 +104,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).
-
 ```php
 function searchSubscriptions(SearchSubscriptionsRequest $body): ApiResponse
 ```
@@ -164,7 +163,7 @@ var_dump($apiResponse->getHeaders());
 
 # Retrieve Subscription
 
-Retrieves a subscription.
+Retrieves a specific subscription.
 
 ```php
 function retrieveSubscription(string $subscriptionId, ?string $mInclude = null): ApiResponse
@@ -202,8 +201,8 @@ var_dump($apiResponse->getHeaders());
 
 # 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`.
 
 ```php
 function updateSubscription(string $subscriptionId, UpdateSubscriptionRequest $body): ApiResponse
@@ -292,9 +291,9 @@ var_dump($apiResponse->getHeaders());
 
 # 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.
 
 ```php
 function cancelSubscription(string $subscriptionId): ApiResponse
@@ -331,7 +330,7 @@ var_dump($apiResponse->getHeaders());
 
 # 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.
 
 ```php
 function listSubscriptionEvents(string $subscriptionId, ?string $cursor = null, ?int $limit = null): ApiResponse
@@ -342,7 +341,7 @@ function listSubscriptionEvents(string $subscriptionId, ?string $cursor = null,
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `subscriptionId` | `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
@@ -456,7 +455,8 @@ var_dump($apiResponse->getHeaders());
 
 # 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).
 
 ```php
 function swapPlan(string $subscriptionId, SwapPlanRequest $body): ApiResponse
@@ -478,9 +478,7 @@ This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` met
 ```php
 $subscriptionId = 'subscription_id0';
 
-$body = SwapPlanRequestBuilder::init(
-    ''
-)->build();
+$body = SwapPlanRequestBuilder::init()->build();
 
 $apiResponse = $subscriptionsApi->swapPlan(
     $subscriptionId,

doc/apis/terminal.md

@@ -14,6 +14,7 @@ $terminalApi = $client->getTerminalApi();
 * [Search Terminal Actions](../../doc/apis/terminal.md#search-terminal-actions)
 * [Get Terminal Action](../../doc/apis/terminal.md#get-terminal-action)
 * [Cancel Terminal Action](../../doc/apis/terminal.md#cancel-terminal-action)
+* [Dismiss Terminal Action](../../doc/apis/terminal.md#dismiss-terminal-action)
 * [Create Terminal Checkout](../../doc/apis/terminal.md#create-terminal-checkout)
 * [Search Terminal Checkouts](../../doc/apis/terminal.md#search-terminal-checkouts)
 * [Get Terminal Checkout](../../doc/apis/terminal.md#get-terminal-checkout)
@@ -144,7 +145,7 @@ function getTerminalAction(string $actionId): ApiResponse
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `actionId` | `string` | Template, Required | Unique ID for the desired `TerminalAction` |
+| `actionId` | `string` | Template, Required | Unique ID for the desired `TerminalAction`. |
 
 ## Response Type
 
@@ -181,7 +182,7 @@ function cancelTerminalAction(string $actionId): ApiResponse
 
 | Parameter | Type | Tags | Description |
 |  --- | --- | --- | --- |
-| `actionId` | `string` | Template, Required | Unique ID for the desired `TerminalAction` |
+| `actionId` | `string` | Template, Required | Unique ID for the desired `TerminalAction`. |
 
 ## Response Type
 
@@ -206,6 +207,45 @@ var_dump($apiResponse->getHeaders());
 ```
 
 
+# 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.
+
+```php
+function dismissTerminalAction(string $actionId): ApiResponse
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `actionId` | `string` | Template, Required | Unique ID for the `TerminalAction` associated with the waiting dialog to be dismissed. |
+
+## Response Type
+
+This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` method on this instance returns the response data which is of type [`DismissTerminalActionResponse`](../../doc/models/dismiss-terminal-action-response.md).
+
+## Example Usage
+
+```php
+$actionId = 'action_id6';
+
+$apiResponse = $terminalApi->dismissTerminalAction($actionId);
+
+if ($apiResponse->isSuccess()) {
+    $dismissTerminalActionResponse = $apiResponse->getResult();
+} else {
+    $errors = $apiResponse->getErrors();
+}
+
+// Getting more response information
+var_dump($apiResponse->getStatusCode());
+var_dump($apiResponse->getHeaders());
+```
+
+
 # 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 |
 |  --- | --- | --- |
-| `squareVersion` | `string` | Square Connect API versions<br>*Default*: `'2023-05-17'` |
+| `squareVersion` | `string` | Square Connect API versions<br>*Default*: `'2023-06-08'` |
 | `customUrl` | `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`** |
 | `timeout` | `int` | Timeout for API calls in seconds.<br>*Default*: `60` |
@@ -26,7 +26,7 @@ The API client can be initialized as follows:
 ```php
 $client = SquareClientBuilder::init()
     ->accessToken('AccessToken')
-    ->squareVersion('2023-05-17')
+    ->squareVersion('2023-06-08')
     ->environment('production')
     ->customUrl('https://connect.squareup.com')
     ->build();
@@ -51,7 +51,7 @@ use Square\SquareClientBuilder;
 
 $client = SquareClientBuilder::init()
     ->accessToken('AccessToken')
-    ->squareVersion('2023-05-17')
+    ->squareVersion('2023-06-08')
     ->build();
 
 $apiResponse = $client->getLocationsApi()->listLocations();

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 | Getter | Setter |
 |  --- | --- | --- | --- | --- | --- |
 | `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void |
-| `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). | getSubscription(): ?Subscription | setSubscription(?Subscription subscription): void |
+| `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). | getSubscription(): ?Subscription | setSubscription(?Subscription subscription): void |
 | `actions` | [`?(SubscriptionAction[])`](../../doc/models/subscription-action.md) | Optional | A list of a single `CANCEL` action scheduled for the subscription. | getActions(): ?array | setActions(?array actions): void |
 
 ## 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,