square · Esawyer25 · Aug 21, 2024 · Aug 20, 2024
diff --git a/doc/api/catalog.md b/doc/api/catalog.md
@@ -39,7 +39,7 @@ children.
 IDs can be deleted. The response will only include IDs that were
 actually deleted.
 
-To ensure consistency, only one delete request is processed at a time per seller account. 
+To ensure consistency, only one delete request is processed at a time per seller account.
 While one (batch or non-batch) delete request is being processed, other (batched and non-batched)
 delete requests are rejected with the `429` error code.
 
@@ -143,7 +143,7 @@ batches will be processed in order as long as the total object count for the
 request (items, variations, modifier lists, discounts, and taxes) is no more
 than 10,000.
 
-To ensure consistency, only one update request is processed at a time per seller account. 
+To ensure consistency, only one update request is processed at a time per seller account.
 While one (batch or non-batch) update request is being processed, other (batched and non-batched)
 update requests are rejected with the `429` error code.
 
@@ -483,7 +483,7 @@ try {
 
 Creates a new or updates the specified [CatalogObject](../../doc/models/catalog-object.md).
 
-To ensure consistency, only one update request is processed at a time per seller account. 
+To ensure consistency, only one update request is processed at a time per seller account.
 While one (batch or non-batch) update request is being processed, other (batched and non-batched)
 update requests are rejected with the `429` error code.
 
@@ -565,7 +565,7 @@ are also deleted. For example, deleting a [CatalogItem](../../doc/models/catalog
 will also delete all of its
 [CatalogItemVariation](../../doc/models/catalog-item-variation.md) children.
 
-To ensure consistency, only one delete request is processed at a time per seller account. 
+To ensure consistency, only one delete request is processed at a time per seller account.
 While one (batch or non-batch) delete request is being processed, other (batched and non-batched)
 delete requests are rejected with the `429` error code.
 

diff --git a/doc/api/gift-card-activities.md b/doc/api/gift-card-activities.md
@@ -70,8 +70,7 @@ try {
 # Create Gift Card Activity
 
 Creates a gift card activity to manage the balance or state of a [gift card](../../doc/models/gift-card.md).
-For example, you create an `ACTIVATE` activity to activate a gift card with an initial balance
-before the gift card can be used.
+For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before first use.
 
 ```ts
 async createGiftCardActivity( body: CreateGiftCardActivityRequest,

diff --git a/doc/api/gift-cards.md b/doc/api/gift-cards.md
@@ -66,9 +66,11 @@ try {
 
 # Create Gift Card
 
-Creates a digital gift card or registers a physical (plastic) gift card. After the gift card
-is created, you must call [CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity)
-to activate the card with an initial balance before it can be used for payment.
+Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card
+has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call
+[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) and create an `ACTIVATE`
+activity with the initial balance. Alternatively, you can use [RefundPayment](../../doc/api/refunds.md#refund-payment)
+to refund a payment to the new gift card.
 
 ```ts
 async createGiftCard( body: CreateGiftCardRequest,

diff --git a/doc/api/o-auth.md b/doc/api/o-auth.md
@@ -156,18 +156,14 @@ where `ACCESS_TOKEN` is a
 
 If the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` error.
 
-:information_source: **Note** This endpoint does not require authentication.
-
 ```ts
-async retrieveTokenStatus( authorization: string,
-requestOptions?: RequestOptions): Promise<ApiResponse<RetrieveTokenStatusResponse>>
+async retrieveTokenStatus(requestOptions?: RequestOptions): Promise<ApiResponse<RetrieveTokenStatusResponse>>
 ```
 
 ## Parameters
 
 | Parameter | Type | Tags | Description |
 | --- | --- | --- | --- |
-| `authorization` | `string` | Header, Required | Client APPLICATION_SECRET |
 | `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. |
 
 ## Response Type
@@ -177,10 +173,8 @@ requestOptions?: RequestOptions): Promise<ApiResponse<RetrieveTokenStatusRespons
 ## Example Usage
 
 ```ts
-const authorization = 'Client CLIENT_SECRET';
-
 try {
- const { result, ...httpResponse } = await oAuthApi.retrieveTokenStatus(authorization);
+ const { result, ...httpResponse } = await oAuthApi.retrieveTokenStatus();
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
 } catch (error) {

diff --git a/doc/api/payments.md b/doc/api/payments.md
@@ -38,6 +38,9 @@ async listPayments( beginTime?: string,
  last4?: string,
  cardBrand?: string,
  limit?: number,
+ isOfflinePayment?: boolean,
+ offlineBeginTime?: string,
+ offlineEndTime?: string,
 requestOptions?: RequestOptions): Promise<ApiResponse<ListPaymentsResponse>>
 ```
 
@@ -54,6 +57,9 @@ requestOptions?: RequestOptions): Promise<ApiResponse<ListPaymentsResponse>>
 | `last4` | `string \| undefined` | Query, Optional | The last four digits of a payment card. |
 | `cardBrand` | `string \| undefined` | Query, Optional | The brand of the payment card (for example, VISA). |
 | `limit` | `number \| undefined` | Query, Optional | The maximum number of results to be returned in a single page.<br>It is possible to receive fewer results than the specified limit on a given page.<br><br>The default value of 100 is also the maximum allowed value. If the provided value is<br>greater than 100, it is ignored and the default value is used instead.<br><br>Default: `100` |
+| `isOfflinePayment` | `boolean \| undefined` | Query, Optional | Whether the payment was taken offline or not. |
+| `offlineBeginTime` | `string \| undefined` | Query, Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339<br>format for timestamps. The range is determined using the<br>`offline_payment_details.client_created_at` field for each Payment. If set, payments without a<br>value set in `offline_payment_details.client_created_at` will not be returned.<br><br>Default: The current time. |
+| `offlineEndTime` | `string \| undefined` | Query, Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339<br>format for timestamps. The range is determined using the<br>`offline_payment_details.client_created_at` field for each Payment. If set, payments without a<br>value set in `offline_payment_details.client_created_at` will not be returned.<br><br>Default: The current time. |
 | `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. |
 
 ## Response Type
@@ -63,8 +69,21 @@ requestOptions?: RequestOptions): Promise<ApiResponse<ListPaymentsResponse>>
 ## Example Usage
 
 ```ts
+const isOfflinePayment = false;
+
 try {
- const { result, ...httpResponse } = await paymentsApi.listPayments();
+ const { result, ...httpResponse } = await paymentsApi.listPayments(
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ isOfflinePayment
+);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
 } catch (error) {

diff --git a/doc/client.md b/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*: `'2024-07-17'` |
+| `squareVersion` | `string` | Square Connect API versions<br>*Default*: `'2024-08-21'` |
 | `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`** |
 | `additionalHeaders` | `Readonly<Record<string, string>>` | Additional headers to add to each API call<br>*Default*: `{}` |
@@ -43,7 +43,7 @@ const client = new Client({
  bearerAuthCredentials: {
  accessToken: 'AccessToken'
  },
- squareVersion: '2024-07-17',
+ squareVersion: '2024-08-21',
  timeout: 60000,
  additionalHeaders: {},
  userAgentDetail: '',
@@ -61,7 +61,7 @@ const client = new Client({
  bearerAuthCredentials: {
  accessToken: 'AccessToken'
  },
- squareVersion: '2024-07-17',
+ squareVersion: '2024-08-21',
  timeout: 60000,
  additionalHeaders: {},
  userAgentDetail: '',

diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md
@@ -35,6 +35,7 @@ Describes a request to create a payment using
 | `cashDetails` | [`CashPaymentDetails \| undefined`](../../doc/models/cash-payment-details.md) | Optional | Stores details about a cash payment. Contains only non-confidential information. For more information, see<br>[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments). |
 | `externalDetails` | [`ExternalPaymentDetails \| undefined`](../../doc/models/external-payment-details.md) | Optional | Stores details about an external payment. Contains only non-confidential information.<br>For more information, see<br>[Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments). |
 | `customerDetails` | [`CustomerDetails \| undefined`](../../doc/models/customer-details.md) | Optional | Details about the customer making the payment. |
+| `offlinePaymentDetails` | [`OfflinePaymentDetails \| undefined`](../../doc/models/offline-payment-details.md) | Optional | Details specific to offline payments. |
 
 ## Example (as JSON)
 

diff --git a/doc/models/gift-card-activity-activate.md b/doc/models/gift-card-activity-activate.md
@@ -15,7 +15,7 @@ Represents details about an `ACTIVATE` [gift card activity type](../../doc/model
 | `orderId` | `string \| null \| undefined` | Optional | The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.<br><br>Applications that use the Square Orders API to process orders must specify the order ID<br>[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. |
 | `lineItemUid` | `string \| null \| undefined` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase.<br><br>Applications that use the Square Orders API to process orders must specify the line item UID<br>in the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. |
 | `referenceId` | `string \| null \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.<br><br>Applications that use a custom order processing system can use this field to track information<br>related to an order or payment. |
-| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks. |
+| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks.<br><br>Each buyer payment instrument ID can contain a maximum of 255 characters. |
 
 ## Example (as JSON)
 

diff --git a/doc/models/gift-card-activity-load.md b/doc/models/gift-card-activity-load.md
@@ -15,7 +15,7 @@ Represents details about a `LOAD` [gift card activity type](../../doc/models/gif
 | `orderId` | `string \| null \| undefined` | Optional | The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.<br><br>Applications that use the Square Orders API to process orders must specify the order ID in the<br>[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. |
 | `lineItemUid` | `string \| null \| undefined` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card.<br><br>Applications that use the Square Orders API to process orders must specify the line item UID<br>in the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. |
 | `referenceId` | `string \| null \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.<br><br>Applications that use a custom order processing system can use this field to track information related to<br>an order or payment. |
-| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks. |
+| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks.<br><br>Each buyer payment instrument ID can contain a maximum of 255 characters. |
 
 ## Example (as JSON)
 

diff --git a/doc/models/gift-card-activity-refund.md b/doc/models/gift-card-activity-refund.md
@@ -11,10 +11,10 @@ Represents details about a `REFUND` [gift card activity type](../../doc/models/g
 
 | Name | Type | Tags | Description |
 | --- | --- | --- | --- |
-| `redeemActivityId` | `string \| null \| undefined` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the<br>`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request<br>represents a redemption made by the same gift card. Note that you must use `RefundPayment`<br>to refund a gift card payment to the same gift card if the payment was processed by Square.<br><br>For applications that use a custom payment processing system, this field is required when creating<br>a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. |
+| `redeemActivityId` | `string \| null \| undefined` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the<br>`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request<br>represents a gift card redemption.<br><br>For applications that use a custom payment processing system, this field is required when creating<br>a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. |
 | `amountMoney` | [`Money \| undefined`](../../doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.<br>Fields that do not explicitly define whether they are signed or unsigned are<br>considered unsigned and can only hold positive amounts. For signed fields, the<br>sign of the value indicates the purpose of the money transfer. See<br>[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)<br>for more information. |
 | `referenceId` | `string \| null \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system. |
-| `paymentId` | `string \| undefined` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a<br>payment processed by Square and one of the following conditions is true:<br><br>- The Refunds API is used to refund a gift card payment to the same gift card.<br>- A seller initiated the refund from Square Point of Sale or the Seller Dashboard. The payment source can be the<br> same gift card or a cross-tender payment from a credit card or a different gift card. |
+| `paymentId` | `string \| undefined` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a<br>payment processed by Square. This field matches the `payment_id` in the corresponding<br>[RefundPayment](api-endpoint:Refunds-RefundPayment) request. |
 
 ## Example (as JSON)
 

diff --git a/doc/models/gift-card-activity-type.md b/doc/models/gift-card-activity-type.md
@@ -18,7 +18,7 @@ Indicates the type of [gift card activity](../../doc/models/gift-card-activity.m
 | `DEACTIVATE` | Permanently blocked a gift card from balance-changing activities. |
 | `ADJUST_INCREMENT` | Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow. |
 | `ADJUST_DECREMENT` | Deducted money from a gift card outside of a typical `REDEEM` activity flow. |
-| `REFUND` | Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to<br>a Square payment, depending on how the payment and refund are processed. For example:<br><br>- A gift card payment processed by Square can be refunded to the same gift card using Square Point of Sale,<br> the Square Seller Dashboard, or the Refunds API.<br>- A cross-tender payment processed by Square can be refunded to a gift card using Square Point of Sale or the<br> Square Seller Dashboard. The payment source might be a credit card or different gift card.<br>- A payment processed using a custom payment processing system can be refunded to the same gift card. |
+| `REFUND` | Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to<br>a Square payment, depending on how the payment and refund are processed. For example:<br><br>- A payment processed by Square can be refunded to a `PENDING` or `ACTIVE` gift card using the Square<br> Seller Dashboard, Square Point of Sale, or Refunds API.<br>- A payment processed using a custom processing system can be refunded to the same gift card. |
 | `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card from a refunded transaction that was processed using a custom payment<br>processing system and not linked to the gift card. |
 | `IMPORT` | Imported a third-party gift card with a balance. `IMPORT` activities are managed<br>by Square and cannot be created using the Gift Card Activities API. |
 | `BLOCK` | Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities<br>are managed by Square and cannot be created using the Gift Card Activities API. |

diff --git a/doc/models/gift-card-status.md b/doc/models/gift-card-status.md
@@ -14,5 +14,5 @@ Indicates the gift card state.
 | `ACTIVE` | The gift card is active and can be used as a payment source. |
 | `DEACTIVATED` | Any activity that changes the gift card balance is permanently forbidden. |
 | `BLOCKED` | Any activity that changes the gift card balance is temporarily forbidden. |
-| `PENDING` | The gift card is pending activation.<br>This is the initial state when a gift card is created. You must activate the gift card<br>before it can be used. |
+| `PENDING` | The gift card is pending activation.<br>This is the initial state when a gift card is created. Typically, you'll call<br>[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) to create an<br>`ACTIVATE` activity that activates the gift card with an initial balance before first use. |