From f17f32df704a40e796d5a0621e12d3c35c2ff85d Mon Sep 17 00:00:00 2001 From: autobot Date: Thu, 16 Jun 2022 15:18:43 +0000 Subject: [PATCH] Generated PR for Release: 19.1.0 --- .github/workflows/node.js.yml | 2 +- README.md | 2 +- doc/api/catalog.md | 2 +- doc/api/gift-cards.md | 2 +- doc/api/loyalty.md | 6 +- doc/api/terminal.md | 3 +- doc/client.md | 6 +- doc/models/appointment-segment.md | 8 +-- ...atch-retrieve-inventory-changes-request.md | 5 +- ...batch-retrieve-inventory-counts-request.md | 1 + .../calculate-loyalty-points-response.md | 2 +- doc/models/cancel-terminal-action-response.md | 2 +- doc/models/card-co-brand.md | 17 ++++++ doc/models/card.md | 4 +- doc/models/catalog-item-variation.md | 4 +- doc/models/catalog-subscription-plan.md | 10 +--- .../create-gift-card-activity-request.md | 2 +- .../create-gift-card-activity-response.md | 2 +- doc/models/create-payment-request.md | 3 +- doc/models/create-payment-response.md | 2 +- doc/models/create-terminal-action-request.md | 2 +- doc/models/create-terminal-action-response.md | 2 +- doc/models/create-terminal-refund-request.md | 2 +- doc/models/device-metadata.md | 43 +++++++++++++++ doc/models/get-terminal-action-response.md | 2 +- doc/models/gift-card-activity-activate.md | 10 ++-- ...t-card-activity-adjust-decrement-reason.md | 2 + .../gift-card-activity-adjust-decrement.md | 4 +- ...t-card-activity-adjust-increment-reason.md | 4 +- .../gift-card-activity-adjust-increment.md | 4 +- doc/models/gift-card-activity-block-reason.md | 2 + doc/models/gift-card-activity-block.md | 4 +- ...gift-card-activity-clear-balance-reason.md | 2 + .../gift-card-activity-clear-balance.md | 4 +- .../gift-card-activity-deactivate-reason.md | 4 +- doc/models/gift-card-activity-deactivate.md | 4 +- .../gift-card-activity-import-reversal.md | 2 +- doc/models/gift-card-activity-import.md | 5 +- doc/models/gift-card-activity-load.md | 10 ++-- .../gift-card-activity-redeem-status.md | 19 +++++++ doc/models/gift-card-activity-redeem.md | 10 ++-- doc/models/gift-card-activity-refund.md | 10 ++-- doc/models/gift-card-activity-type.md | 26 ++++----- .../gift-card-activity-unblock-reason.md | 2 + doc/models/gift-card-activity-unblock.md | 4 +- ...-card-activity-unlinked-activity-refund.md | 6 +- doc/models/gift-card-activity.md | 40 +++++++------- doc/models/list-catalog-request.md | 2 +- doc/models/payment-options.md | 2 +- doc/models/payment.md | 4 +- doc/models/payout.md | 2 +- doc/models/search-catalog-objects-request.md | 2 +- doc/models/subscription-phase.md | 7 +-- doc/models/terminal-action-action-type.md | 1 + doc/models/terminal-action.md | 6 +- package.json | 2 +- src/api/catalogApi.ts | 7 +-- src/api/giftCardsApi.ts | 2 +- src/api/loyaltyApi.ts | 6 +- src/api/terminalApi.ts | 3 +- src/client.ts | 4 +- src/defaultConfiguration.ts | 2 +- src/index.ts | 1 + src/models/appointmentSegment.ts | 8 +-- .../batchRetrieveInventoryChangesRequest.ts | 4 +- .../batchRetrieveInventoryCountsRequest.ts | 4 +- src/models/calculateLoyaltyPointsResponse.ts | 5 +- src/models/cancelTerminalActionResponse.ts | 1 + src/models/card.ts | 3 + src/models/catalogItemVariation.ts | 4 +- src/models/createGiftCardActivityRequest.ts | 6 +- src/models/createGiftCardActivityResponse.ts | 6 +- src/models/createPaymentRequest.ts | 18 ++++-- src/models/createTerminalActionRequest.ts | 1 + src/models/createTerminalActionResponse.ts | 1 + src/models/deviceMetadata.ts | 55 +++++++++++++++++++ src/models/getTerminalActionResponse.ts | 1 + src/models/giftCardActivity.ts | 51 ++++++++++------- src/models/giftCardActivityActivate.ts | 27 +++++---- src/models/giftCardActivityAdjustDecrement.ts | 3 +- src/models/giftCardActivityAdjustIncrement.ts | 3 +- src/models/giftCardActivityBlock.ts | 3 +- src/models/giftCardActivityClearBalance.ts | 3 +- src/models/giftCardActivityDeactivate.ts | 3 +- src/models/giftCardActivityImport.ts | 5 +- src/models/giftCardActivityImportReversal.ts | 2 +- src/models/giftCardActivityLoad.ts | 27 +++++---- src/models/giftCardActivityRedeem.ts | 20 ++++--- src/models/giftCardActivityRefund.ts | 27 +++++---- src/models/giftCardActivityUnblock.ts | 3 +- .../giftCardActivityUnlinkedActivityRefund.ts | 13 +---- src/models/listCatalogRequest.ts | 4 +- src/models/payment.ts | 6 +- src/models/paymentOptions.ts | 6 +- src/models/payout.ts | 2 +- src/models/searchCatalogObjectsRequest.ts | 4 +- src/models/subscriptionPhase.ts | 7 ++- src/models/terminalAction.ts | 7 +++ 98 files changed, 470 insertions(+), 240 deletions(-) create mode 100644 doc/models/card-co-brand.md create mode 100644 doc/models/device-metadata.md create mode 100644 doc/models/gift-card-activity-redeem-status.md create mode 100644 src/models/deviceMetadata.ts diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml index c959a822..ddebc061 100644 --- a/.github/workflows/node.js.yml +++ b/.github/workflows/node.js.yml @@ -19,7 +19,7 @@ jobs: strategy: matrix: - node-version: [10.x, 12.x, 14.x] + node-version: [14.x, 16.x, 18.x] # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: diff --git a/README.md b/README.md index bdc209f7..cbf1b282 100644 --- a/README.md +++ b/README.md @@ -170,4 +170,4 @@ npm test [Cards]: doc/api/cards.md [Payouts]: doc/api/payouts.md [Gift Cards]: doc/api/gift-cards.md -[Gift Card Activities]: doc/api/gift-card-activities.md \ No newline at end of file +[Gift Card Activities]: doc/api/gift-card-activities.md diff --git a/doc/api/catalog.md b/doc/api/catalog.md index 4fd1b86e..4d562058 100644 --- a/doc/api/catalog.md +++ b/doc/api/catalog.md @@ -471,7 +471,7 @@ async listCatalog( | Parameter | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `string \| undefined` | Query, Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
The page size is currently set to be 100.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `types` | `string \| undefined` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | +| `types` | `string \| undefined` | Query, Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST,
PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | | `catalogVersion` | `bigint \| undefined` | Query, Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](../../doc/models/catalog-object.md)s' `version` attribute. If not included, results will
be from the current version of the catalog. | | `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. | diff --git a/doc/api/gift-cards.md b/doc/api/gift-cards.md index ffe92b3a..0deb7927 100644 --- a/doc/api/gift-cards.md +++ b/doc/api/gift-cards.md @@ -22,7 +22,7 @@ const giftCardsApi = client.giftCardsApi; # List Gift Cards Lists all gift cards. You can specify optional filters to retrieve -a subset of the gift cards. +a subset of the gift cards. Results are sorted by `created_at` in ascending order. ```ts async listGiftCards( diff --git a/doc/api/loyalty.md b/doc/api/loyalty.md index 8072c2d9..835c10ee 100644 --- a/doc/api/loyalty.md +++ b/doc/api/loyalty.md @@ -176,7 +176,7 @@ try { # Accumulate Loyalty Points -Adds points to a loyalty account. +Adds points earned from the base loyalty program to a loyalty account. - If you are using the Orders API to manage orders, you only provide the `order_id`. The endpoint reads the order to compute points to add to the buyer's account. @@ -186,6 +186,8 @@ Adds points to a loyalty account. [CalculateLoyaltyPoints](../../doc/api/loyalty.md#calculate-loyalty-points) to compute the points that you provide to this endpoint. +This endpoint excludes additional points earned from loyalty promotions. + ```ts async accumulateLoyaltyPoints( accountId: string, @@ -433,7 +435,7 @@ try { # Calculate Loyalty Points -Calculates the points a purchase earns. +Calculates the points a purchase earns from the base loyalty program. - If you are using the Orders API to manage orders, you provide the `order_id` in the request. The endpoint calculates the points by reading the order. diff --git a/doc/api/terminal.md b/doc/api/terminal.md index 43ddacc1..343ea1df 100644 --- a/doc/api/terminal.md +++ b/doc/api/terminal.md @@ -26,8 +26,7 @@ const terminalApi = client.terminalApi; # Create Terminal Action -Creates a Terminal action request and sends it to the specified device to take a payment -for the requested amount. +Creates a Terminal action request and sends it to the specified device. ```ts async createTerminalAction( diff --git a/doc/client.md b/doc/client.md index 04a40968..51efe529 100644 --- a/doc/client.md +++ b/doc/client.md @@ -5,7 +5,7 @@ The following parameters are configurable for the API Client: | Parameter | Type | Description | | --- | --- | --- | -| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2022-05-12'` | +| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2022-06-16'` | | `customUrl` | `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`** | | `additionalHeaders` | `Readonly>` | Additional headers to add to each API call
*Default*: `{}` | @@ -40,7 +40,7 @@ The API client can be initialized as follows: ```ts const client = new Client({ - squareVersion: '2022-05-12', + squareVersion: '2022-06-16', timeout: 60000, additionalHeaders: {}, userAgentDetail: '', @@ -56,7 +56,7 @@ import fs from 'fs'; import { ApiError, Client, FileWrapper, LocationsApi } from 'square'; const client = new Client({ - squareVersion: '2022-05-12', + squareVersion: '2022-06-16', timeout: 60000, additionalHeaders: {}, userAgentDetail: '', diff --git a/doc/models/appointment-segment.md b/doc/models/appointment-segment.md index 61aa0f7e..00c54f9e 100644 --- a/doc/models/appointment-segment.md +++ b/doc/models/appointment-segment.md @@ -12,9 +12,9 @@ Defines an appointment segment of a booking. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `durationMinutes` | `number \| undefined` | Optional | The time span in minutes of an appointment segment.
**Constraints**: `<= 1500` | -| `serviceVariationId` | `string` | Required | The ID of the [CatalogItemVariation](../../doc/models/catalog-item-variation.md) object representing the service booked in this segment.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `36` | +| `serviceVariationId` | `string \| undefined` | Optional | The ID of the [CatalogItemVariation](../../doc/models/catalog-item-variation.md) object representing the service booked in this segment.
**Constraints**: *Maximum Length*: `36` | | `teamMemberId` | `string` | Required | The ID of the [TeamMember](../../doc/models/team-member.md) object representing the team member booked in this segment.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `32` | -| `serviceVariationVersion` | `bigint` | Required | The current version of the item variation representing the service booked in this segment. | +| `serviceVariationVersion` | `bigint \| undefined` | Optional | The current version of the item variation representing the service booked in this segment. | | `intermissionMinutes` | `number \| undefined` | Optional | Time between the end of this segment and the beginning of the subsequent segment. | | `anyTeamMember` | `boolean \| undefined` | Optional | Whether the customer accepts any team member, instead of a specific one, to serve this segment. | | `resourceIds` | `string[] \| undefined` | Optional | The IDs of the seller-accessible resources used for this appointment segment. | @@ -24,9 +24,9 @@ Defines an appointment segment of a booking. ```json { "duration_minutes": null, - "service_variation_id": "service_variation_id6", + "service_variation_id": null, "team_member_id": "team_member_id0", - "service_variation_version": 56, + "service_variation_version": null, "intermission_minutes": null, "any_team_member": null, "resource_ids": null diff --git a/doc/models/batch-retrieve-inventory-changes-request.md b/doc/models/batch-retrieve-inventory-changes-request.md index 92983f5b..8d386bc9 100644 --- a/doc/models/batch-retrieve-inventory-changes-request.md +++ b/doc/models/batch-retrieve-inventory-changes-request.md @@ -13,9 +13,10 @@ | `locationIds` | `string[] \| undefined` | Optional | The filter to return results by `Location` ID.
The filter is only applicable when set. The default value is null. | | `types` | [`string[] \| undefined`](../../doc/models/inventory-change-type.md) | Optional | The filter to return results by `InventoryChangeType` values other than `TRANSFER`.
The default value is `[PHYSICAL_COUNT, ADJUSTMENT]`. | | `states` | [`string[] \| undefined`](../../doc/models/inventory-state.md) | Optional | The filter to return `ADJUSTMENT` query results by
`InventoryState`. This filter is only applied when set.
The default value is null. | -| `updatedAfter` | `string \| undefined` | Optional | The filter to return results with their `calculated_at` value
after the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | -| `updatedBefore` | `string \| undefined` | Optional | The filter to return results with their `created_at` or `calculated_at` value
strictly before the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | +| `updatedAfter` | `string \| undefined` | Optional | The filter to return results with their `calculated_at` value
after the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | +| `updatedBefore` | `string \| undefined` | Optional | The filter to return results with their `created_at` or `calculated_at` value
strictly before the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | | `cursor` | `string \| undefined` | 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.

See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. | +| `limit` | `number \| undefined` | Optional | **Constraints**: `>= 1`, `<= 1000` | ## Example (as JSON) diff --git a/doc/models/batch-retrieve-inventory-counts-request.md b/doc/models/batch-retrieve-inventory-counts-request.md index 0063afe7..3a98eaca 100644 --- a/doc/models/batch-retrieve-inventory-counts-request.md +++ b/doc/models/batch-retrieve-inventory-counts-request.md @@ -14,6 +14,7 @@ | `updatedAfter` | `string \| undefined` | Optional | The filter to return results with their `calculated_at` value
after the given time as specified in an RFC 3339 timestamp.
The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`). | | `cursor` | `string \| undefined` | 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.

See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. | | `states` | [`string[] \| undefined`](../../doc/models/inventory-state.md) | Optional | The filter to return results by `InventoryState`. The filter is only applicable when set.
Ignored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`.
The default is null. | +| `limit` | `number \| undefined` | Optional | **Constraints**: `>= 1`, `<= 1000` | ## Example (as JSON) diff --git a/doc/models/calculate-loyalty-points-response.md b/doc/models/calculate-loyalty-points-response.md index 58e8a4be..fcd8ab7c 100644 --- a/doc/models/calculate-loyalty-points-response.md +++ b/doc/models/calculate-loyalty-points-response.md @@ -13,7 +13,7 @@ a specified purchase. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`Error[] \| undefined`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `points` | `number \| undefined` | Optional | The points that the buyer can earn from a specified purchase. | +| `points` | `number \| undefined` | Optional | The points that the buyer can earn from a specified purchase.
This value does not include additional points earned from a loyalty promotion. | ## Example (as JSON) diff --git a/doc/models/cancel-terminal-action-response.md b/doc/models/cancel-terminal-action-response.md index 843f8389..6ab320d5 100644 --- a/doc/models/cancel-terminal-action-response.md +++ b/doc/models/cancel-terminal-action-response.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`Error[] \| undefined`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `action` | [`TerminalAction \| undefined`](../../doc/models/terminal-action.md) | Optional | - | +| `action` | [`TerminalAction \| undefined`](../../doc/models/terminal-action.md) | Optional | Represents an action processed by the Square Terminal. | ## Example (as JSON) diff --git a/doc/models/card-co-brand.md b/doc/models/card-co-brand.md new file mode 100644 index 00000000..8e5872da --- /dev/null +++ b/doc/models/card-co-brand.md @@ -0,0 +1,17 @@ + +# Card Co Brand + +Indicates the brand for a co-branded card. + +## Enumeration + +`CardCoBrand` + +## Fields + +| Name | +| --- | +| `UNKNOWN` | +| `AFTERPAY` | +| `CLEARPAY` | + diff --git a/doc/models/card.md b/doc/models/card.md index 964ada61..d852c460 100644 --- a/doc/models/card.md +++ b/doc/models/card.md @@ -28,6 +28,7 @@ details are determined by the payment token generated by Web Payments SDK. | `prepaidType` | [`string \| undefined`](../../doc/models/card-prepaid-type.md) | Optional | Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`. | | `bin` | `string \| undefined` | Optional | The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API
returns this field.
**Constraints**: *Maximum Length*: `6` | | `version` | `bigint \| undefined` | Optional | Current version number of the card. Increments with each card update. Requests to update an
existing Card object will be rejected unless the version in the request matches the current
version for the Card. | +| `cardCoBrand` | [`string \| undefined`](../../doc/models/card-co-brand.md) | Optional | Indicates the brand for a co-branded card. | ## Example (as JSON) @@ -48,7 +49,8 @@ details are determined by the payment token generated by Web Payments SDK. "card_type": null, "prepaid_type": null, "bin": null, - "version": null + "version": null, + "card_co_brand": null } ``` diff --git a/doc/models/catalog-item-variation.md b/doc/models/catalog-item-variation.md index 9d5b2c6a..2545717a 100644 --- a/doc/models/catalog-item-variation.md +++ b/doc/models/catalog-item-variation.md @@ -36,8 +36,8 @@ decreases by 2, and the stockable count automatically decreases by 0.4 bottle ac | `availableForBooking` | `boolean \| undefined` | Optional | If the `CatalogItem` that owns this item variation is of type
`APPOINTMENTS_SERVICE`, a bool representing whether this service is available for booking. | | `itemOptionValues` | [`CatalogItemOptionValueForItemVariation[] \| undefined`](../../doc/models/catalog-item-option-value-for-item-variation.md) | Optional | List of item option values associated with this item variation. Listed
in the same order as the item options of the parent item. | | `measurementUnitId` | `string \| undefined` | Optional | ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity
sold of this item variation. If left unset, the item will be sold in
whole quantities. | -| `sellable` | `boolean \| undefined` | Optional | Whether this variation can be sold. The inventory count of a sellable variation indicates
the number of units available for sale. When a variation is both stockable and sellable,
its sellable inventory count can be smaller than or equal to its stocable count. | -| `stockable` | `boolean \| undefined` | Optional | Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE).
The inventory count of a stockable variation keeps track of the number of units of this variation in stock
and is not an indicator of the number of units of the variation that can be sold. | +| `sellable` | `boolean \| undefined` | Optional | Whether this variation can be sold. The inventory count of a sellable variation indicates
the number of units available for sale. When a variation is both stockable and sellable,
its sellable inventory count can be smaller than or equal to its stockable count. | +| `stockable` | `boolean \| undefined` | Optional | Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE).
When a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock
and is not an indicator of the number of units of the variation that can be sold. | | `imageIds` | `string[] \| undefined` | Optional | The IDs of images associated with this `CatalogItemVariation` instance.
These images will be shown to customers in Square Online Store. | | `teamMemberIds` | `string[] \| undefined` | Optional | Tokens of employees that can perform the service represented by this variation. Only valid for
variations of type `APPOINTMENTS_SERVICE`. | | `stockableConversion` | [`CatalogStockConversion \| undefined`](../../doc/models/catalog-stock-conversion.md) | Optional | Represents the rule of conversion between a stockable [CatalogItemVariation](../../doc/models/catalog-item-variation.md)
and a non-stockable sell-by or receive-by `CatalogItemVariation` that
share the same underlying stock. | diff --git a/doc/models/catalog-subscription-plan.md b/doc/models/catalog-subscription-plan.md index e82f575c..654b3712 100644 --- a/doc/models/catalog-subscription-plan.md +++ b/doc/models/catalog-subscription-plan.md @@ -25,20 +25,14 @@ Describes a subscription plan. For more information, see "uid": null, "cadence": "EVERY_FOUR_MONTHS", "periods": null, - "recurring_price_money": { - "amount": null, - "currency": null - }, + "recurring_price_money": null, "ordinal": null }, { "uid": null, "cadence": "QUARTERLY", "periods": null, - "recurring_price_money": { - "amount": null, - "currency": null - }, + "recurring_price_money": null, "ordinal": null } ] diff --git a/doc/models/create-gift-card-activity-request.md b/doc/models/create-gift-card-activity-request.md index 781c89f5..91cdbda2 100644 --- a/doc/models/create-gift-card-activity-request.md +++ b/doc/models/create-gift-card-activity-request.md @@ -12,7 +12,7 @@ A request to create a gift card activity. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `idempotencyKey` | `string` | Required | A unique string that identifies the `CreateGiftCardActivity` request.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `128` | -| `giftCardActivity` | [`GiftCardActivity`](../../doc/models/gift-card-activity.md) | Required | Represents an action performed on a gift card that affects its state or balance. | +| `giftCardActivity` | [`GiftCardActivity`](../../doc/models/gift-card-activity.md) | Required | Represents an action performed on a [gift card](../../doc/models/gift-card.md) that affects its state or balance.
A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity
includes a `redeem_activity_details` field that contains information about the redemption. | ## Example (as JSON) diff --git a/doc/models/create-gift-card-activity-response.md b/doc/models/create-gift-card-activity-response.md index ae235b71..1c73f165 100644 --- a/doc/models/create-gift-card-activity-response.md +++ b/doc/models/create-gift-card-activity-response.md @@ -13,7 +13,7 @@ The response might contain a set of `Error` objects if the request resulted in e | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`Error[] \| undefined`](../../doc/models/error.md) | Optional | Any errors that occurred during the request. | -| `giftCardActivity` | [`GiftCardActivity \| undefined`](../../doc/models/gift-card-activity.md) | Optional | Represents an action performed on a gift card that affects its state or balance. | +| `giftCardActivity` | [`GiftCardActivity \| undefined`](../../doc/models/gift-card-activity.md) | Optional | Represents an action performed on a [gift card](../../doc/models/gift-card.md) that affects its state or balance.
A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity
includes a `redeem_activity_details` field that contains information about the redemption. | ## Example (as JSON) diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index 188f646f..54537d5f 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -17,7 +17,8 @@ Describes a request to create a payment using | `amountMoney` | [`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. | | `tipMoney` | [`Money \| undefined`](../../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. | | `appFeeMoney` | [`Money \| undefined`](../../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. | -| `delayDuration` | `string \| undefined` | Optional | The duration of time after the payment's creation when Square automatically cancels the
payment. This automatic cancellation applies only to payments that do not reach a terminal state
(COMPLETED, CANCELED, or FAILED) before the `delay_duration` time period.

This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value
of 1 minute.

Note: This feature is only supported for card payments. This parameter can only be set for a delayed
capture payment (`autocomplete=false`).

Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | +| `delayDuration` | `string \| undefined` | Optional | The duration of time after the payment's creation when Square automatically
either completes or cancels the payment depending on the `delay_action` field value.
For more information, see
[Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

This parameter should be specified as a time duration, in RFC 3339 format.

Note: This feature is only supported for card payments. This parameter can only be set for a delayed
capture payment (`autocomplete=false`).

Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | +| `delayAction` | `string \| undefined` | Optional | The action to be applied to the payment when the `delay_duration` has elapsed. The action must be
CANCEL or COMPLETE. For more information, see
[Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).

Default: CANCEL | | `autocomplete` | `boolean \| undefined` | Optional | If set to `true`, this payment will be completed when possible. If
set to `false`, this payment is held in an approved state until either
explicitly completed (captured) or canceled (voided). For more information, see
[Delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).

Default: true | | `orderId` | `string \| undefined` | Optional | Associates a previously created order with this payment. | | `customerId` | `string \| undefined` | Optional | The [Customer](../../doc/models/customer.md) ID of the customer associated with the payment.

This is required if the `source_id` refers to a card on file created using the Customers API. | diff --git a/doc/models/create-payment-response.md b/doc/models/create-payment-response.md index 225ca9f3..30476dea 100644 --- a/doc/models/create-payment-response.md +++ b/doc/models/create-payment-response.md @@ -70,7 +70,7 @@ present, or it might be present with a status of `FAILED`. "note": "Brief Description", "order_id": "pRsjRTgFWATl7so6DxdKBJa7ssbZY", "receipt_number": "R2B3", - "receipt_url": "https://squareupstaging.com/receipt/preview/R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY", + "receipt_url": "https://squareup.com/receipt/preview/EXAMPLE_RECEIPT_ID", "reference_id": "123456", "risk_evaluation": { "created_at": "2021-10-13T21:14:30.423Z", diff --git a/doc/models/create-terminal-action-request.md b/doc/models/create-terminal-action-request.md index dbd39687..f0004dd9 100644 --- a/doc/models/create-terminal-action-request.md +++ b/doc/models/create-terminal-action-request.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `idempotencyKey` | `string` | Required | A unique string that identifies this `CreateAction` request. Keys can be any valid string
but must be unique for every `CreateAction` request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `64` | -| `action` | [`TerminalAction`](../../doc/models/terminal-action.md) | Required | - | +| `action` | [`TerminalAction`](../../doc/models/terminal-action.md) | Required | Represents an action processed by the Square Terminal. | ## Example (as JSON) diff --git a/doc/models/create-terminal-action-response.md b/doc/models/create-terminal-action-response.md index 56cd2de0..c8466b0e 100644 --- a/doc/models/create-terminal-action-response.md +++ b/doc/models/create-terminal-action-response.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`Error[] \| undefined`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `action` | [`TerminalAction \| undefined`](../../doc/models/terminal-action.md) | Optional | - | +| `action` | [`TerminalAction \| undefined`](../../doc/models/terminal-action.md) | Optional | Represents an action processed by the Square Terminal. | ## Example (as JSON) diff --git a/doc/models/create-terminal-refund-request.md b/doc/models/create-terminal-refund-request.md index 97bee490..e50eef3e 100644 --- a/doc/models/create-terminal-refund-request.md +++ b/doc/models/create-terminal-refund-request.md @@ -9,7 +9,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `idempotencyKey` | `string` | Required | A unique string that identifies this `CreateRefund` request. Keys can be any valid string but
must be unique for every `CreateRefund` request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1` | +| `idempotencyKey` | `string` | Required | A unique string that identifies this `CreateRefund` request. Keys can be any valid string but
must be unique for every `CreateRefund` request.

See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.
**Constraints**: *Minimum Length*: `1`, *Maximum Length*: `64` | | `refund` | [`TerminalRefund \| undefined`](../../doc/models/terminal-refund.md) | Optional | Represents a payment refund processed by the Square Terminal. Only supports Interac (Canadian debit network) payment refunds. | ## Example (as JSON) diff --git a/doc/models/device-metadata.md b/doc/models/device-metadata.md new file mode 100644 index 00000000..1a92ad7b --- /dev/null +++ b/doc/models/device-metadata.md @@ -0,0 +1,43 @@ + +# Device Metadata + +## Structure + +`DeviceMetadata` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `batteryPercentage` | `string \| undefined` | Optional | The Terminal’s remaining battery percentage, between 1-100. | +| `chargingState` | `string \| undefined` | Optional | The current charging state of the Terminal.
Options: `CHARGING`, `NOT_CHARGING` | +| `locationId` | `string \| undefined` | Optional | The ID of the Square seller business location associated with the Terminal. | +| `merchantId` | `string \| undefined` | Optional | The ID of the Square merchant account that is currently signed-in to the Terminal. | +| `networkConnectionType` | `string \| undefined` | Optional | The Terminal’s current network connection type.
Options: `WIFI`, `ETHERNET` | +| `paymentRegion` | `string \| undefined` | Optional | The country in which the Terminal is authorized to take payments. | +| `serialNumber` | `string \| undefined` | Optional | The unique identifier assigned to the Terminal, which can be found on the lower back
of the device. | +| `osVersion` | `string \| undefined` | Optional | The current version of the Terminal’s operating system. | +| `appVersion` | `string \| undefined` | Optional | The current version of the application running on the Terminal. | +| `wifiNetworkName` | `string \| undefined` | Optional | The name of the Wi-Fi network to which the Terminal is connected. | +| `wifiNetworkStrength` | `string \| undefined` | Optional | The signal strength of the Wi-FI network connection.
Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT` | +| `ipAddress` | `string \| undefined` | Optional | The IP address of the Terminal. | + +## Example (as JSON) + +```json +{ + "battery_percentage": null, + "charging_state": null, + "location_id": null, + "merchant_id": null, + "network_connection_type": null, + "payment_region": null, + "serial_number": null, + "os_version": null, + "app_version": null, + "wifi_network_name": null, + "wifi_network_strength": null, + "ip_address": null +} +``` + diff --git a/doc/models/get-terminal-action-response.md b/doc/models/get-terminal-action-response.md index ac6f1705..3773b7af 100644 --- a/doc/models/get-terminal-action-response.md +++ b/doc/models/get-terminal-action-response.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `errors` | [`Error[] \| undefined`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | -| `action` | [`TerminalAction \| undefined`](../../doc/models/terminal-action.md) | Optional | - | +| `action` | [`TerminalAction \| undefined`](../../doc/models/terminal-action.md) | Optional | Represents an action processed by the Square Terminal. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-activate.md b/doc/models/gift-card-activity-activate.md index 9605b16d..5ae290dc 100644 --- a/doc/models/gift-card-activity-activate.md +++ b/doc/models/gift-card-activity-activate.md @@ -1,7 +1,7 @@ # Gift Card Activity Activate -Describes a gift card activity of the ACTIVATE type. +Represents details about an `ACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,10 +12,10 @@ Describes a gift card activity of the ACTIVATE type. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `amountMoney` | [`Money \| undefined`](../../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. | -| `orderId` | `string \| undefined` | Optional | The ID of the order associated with the activity.
This is required if your application uses the Square Orders API. | -| `lineItemUid` | `string \| undefined` | Optional | The `line_item_uid` of the gift card line item in an order.
This is required if your application uses the Square Orders API. | -| `referenceId` | `string \| undefined` | Optional | If your application does not use the Square Orders API, you can optionally use this field
to associate the gift card activity with a client-side entity. | -| `buyerPaymentInstrumentIds` | `string[] \| undefined` | Optional | Required if your application does not use the Square Orders API.
This is a list of client-provided payment instrument IDs.
Square uses this information to perform compliance checks.
If you use the Square Orders API, Square has the necessary instrument IDs to perform necessary
compliance checks. | +| `orderId` | `string \| undefined` | Optional | The ID of the [order](../../doc/models/order.md) that contains the `GIFT_CARD` line item.

Applications that use the Square Orders API to process orders must specify the order ID
[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) request. | +| `lineItemUid` | `string \| undefined` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase.

Applications that use the Square Orders API to process orders must specify the line item UID
in the [CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) request. | +| `referenceId` | `string \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom order processing system can use this field to track information
related to an order or payment. | +| `buyerPaymentInstrumentIds` | `string[] \| undefined` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-adjust-decrement-reason.md b/doc/models/gift-card-activity-adjust-decrement-reason.md index 9487073f..cc777eb5 100644 --- a/doc/models/gift-card-activity-adjust-decrement-reason.md +++ b/doc/models/gift-card-activity-adjust-decrement-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Adjust Decrement Reason +Indicates the reason for deducting money from a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityAdjustDecrementReason` diff --git a/doc/models/gift-card-activity-adjust-decrement.md b/doc/models/gift-card-activity-adjust-decrement.md index 3736e592..4741983f 100644 --- a/doc/models/gift-card-activity-adjust-decrement.md +++ b/doc/models/gift-card-activity-adjust-decrement.md @@ -1,7 +1,7 @@ # Gift Card Activity Adjust Decrement -Describes a gift card activity of the ADJUST_DECREMENT type. +Represents details about an `ADJUST_DECREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,7 +12,7 @@ Describes a gift card activity of the ADJUST_DECREMENT type. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `amountMoney` | [`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. | -| `reason` | [`string`](../../doc/models/gift-card-activity-adjust-decrement-reason.md) | Required | - | +| `reason` | [`string`](../../doc/models/gift-card-activity-adjust-decrement-reason.md) | Required | Indicates the reason for deducting money from a [gift card](../../doc/models/gift-card.md). | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-adjust-increment-reason.md b/doc/models/gift-card-activity-adjust-increment-reason.md index 9e39b65d..c7bebb4d 100644 --- a/doc/models/gift-card-activity-adjust-increment-reason.md +++ b/doc/models/gift-card-activity-adjust-increment-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Adjust Increment Reason +Indicates the reason for adding money to a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityAdjustIncrementReason` @@ -9,7 +11,7 @@ | Name | Description | | --- | --- | -| `COMPLIMENTARY` | Seller gifted a complimentary gift card balance increase. | +| `COMPLIMENTARY` | The seller gifted a complimentary gift card balance increase. | | `SUPPORT_ISSUE` | The seller increased the gift card balance
to accommodate support issues. | | `TRANSACTION_VOIDED` | The transaction is voided. | diff --git a/doc/models/gift-card-activity-adjust-increment.md b/doc/models/gift-card-activity-adjust-increment.md index 37af5307..2cecd142 100644 --- a/doc/models/gift-card-activity-adjust-increment.md +++ b/doc/models/gift-card-activity-adjust-increment.md @@ -1,7 +1,7 @@ # Gift Card Activity Adjust Increment -Describes a gift card activity of the ADJUST_INCREMENT type. +Represents details about an `ADJUST_INCREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,7 +12,7 @@ Describes a gift card activity of the ADJUST_INCREMENT type. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `amountMoney` | [`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. | -| `reason` | [`string`](../../doc/models/gift-card-activity-adjust-increment-reason.md) | Required | - | +| `reason` | [`string`](../../doc/models/gift-card-activity-adjust-increment-reason.md) | Required | Indicates the reason for adding money to a [gift card](../../doc/models/gift-card.md). | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-block-reason.md b/doc/models/gift-card-activity-block-reason.md index f1d82bf0..6bf54c74 100644 --- a/doc/models/gift-card-activity-block-reason.md +++ b/doc/models/gift-card-activity-block-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Block Reason +Indicates the reason for blocking a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityBlockReason` diff --git a/doc/models/gift-card-activity-block.md b/doc/models/gift-card-activity-block.md index d647b091..107514f9 100644 --- a/doc/models/gift-card-activity-block.md +++ b/doc/models/gift-card-activity-block.md @@ -1,7 +1,7 @@ # Gift Card Activity Block -Describes a gift card activity of the BLOCK type. +Represents details about a `BLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Describes a gift card activity of the BLOCK type. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_BLOCK'` | +| `reason` | `string` | Required, Constant | Indicates the reason for blocking a [gift card](../../doc/models/gift-card.md).
**Default**: `'CHARGEBACK_BLOCK'` | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-clear-balance-reason.md b/doc/models/gift-card-activity-clear-balance-reason.md index 39a15c31..9995993f 100644 --- a/doc/models/gift-card-activity-clear-balance-reason.md +++ b/doc/models/gift-card-activity-clear-balance-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Clear Balance Reason +Indicates the reason for clearing the balance of a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityClearBalanceReason` diff --git a/doc/models/gift-card-activity-clear-balance.md b/doc/models/gift-card-activity-clear-balance.md index 65a27061..8df6f71d 100644 --- a/doc/models/gift-card-activity-clear-balance.md +++ b/doc/models/gift-card-activity-clear-balance.md @@ -1,7 +1,7 @@ # Gift Card Activity Clear Balance -Describes a gift card activity of the CLEAR_BALANCE type. +Represents details about a `CLEAR_BALANCE` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Describes a gift card activity of the CLEAR_BALANCE type. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `reason` | [`string`](../../doc/models/gift-card-activity-clear-balance-reason.md) | Required | - | +| `reason` | [`string`](../../doc/models/gift-card-activity-clear-balance-reason.md) | Required | Indicates the reason for clearing the balance of a [gift card](../../doc/models/gift-card.md). | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-deactivate-reason.md b/doc/models/gift-card-activity-deactivate-reason.md index 491717ce..6797f7b5 100644 --- a/doc/models/gift-card-activity-deactivate-reason.md +++ b/doc/models/gift-card-activity-deactivate-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Deactivate Reason +Indicates the reason for deactivating a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityDeactivateReason` @@ -10,6 +12,6 @@ | Name | Description | | --- | --- | | `SUSPICIOUS_ACTIVITY` | The seller suspects suspicious activity. | -| `UNKNOWN_REASON` | The gift card deactivated for an unknown reason. | +| `UNKNOWN_REASON` | The gift card was deactivated for an unknown reason. | | `CHARGEBACK_DEACTIVATE` | A chargeback on the gift card purchase (or the gift card load) was ruled in favor of the buyer. | diff --git a/doc/models/gift-card-activity-deactivate.md b/doc/models/gift-card-activity-deactivate.md index c0a7974f..cdc0d6b1 100644 --- a/doc/models/gift-card-activity-deactivate.md +++ b/doc/models/gift-card-activity-deactivate.md @@ -1,7 +1,7 @@ # Gift Card Activity Deactivate -Describes a gift card activity of the DEACTIVATE type. +Represents details about a `DEACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Describes a gift card activity of the DEACTIVATE type. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `reason` | [`string`](../../doc/models/gift-card-activity-deactivate-reason.md) | Required | - | +| `reason` | [`string`](../../doc/models/gift-card-activity-deactivate-reason.md) | Required | Indicates the reason for deactivating a [gift card](../../doc/models/gift-card.md). | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-import-reversal.md b/doc/models/gift-card-activity-import-reversal.md index ca114dd0..4a5644eb 100644 --- a/doc/models/gift-card-activity-import-reversal.md +++ b/doc/models/gift-card-activity-import-reversal.md @@ -1,7 +1,7 @@ # Gift Card Activity Import Reversal -Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER +Represents details about an `IMPORT_REVERSAL` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure diff --git a/doc/models/gift-card-activity-import.md b/doc/models/gift-card-activity-import.md index 5fcedb75..c84c5509 100644 --- a/doc/models/gift-card-activity-import.md +++ b/doc/models/gift-card-activity-import.md @@ -1,8 +1,9 @@ # Gift Card Activity Import -Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER -(a third-party gift card). +Represents details about an `IMPORT` [gift card activity type](../../doc/models/gift-card-activity-type.md). +This activity type is used when Square imports a third-party gift card, in which case the +`gan_source` of the gift card is set to `OTHER`. ## Structure diff --git a/doc/models/gift-card-activity-load.md b/doc/models/gift-card-activity-load.md index a7312e82..d5cddd21 100644 --- a/doc/models/gift-card-activity-load.md +++ b/doc/models/gift-card-activity-load.md @@ -1,7 +1,7 @@ # Gift Card Activity Load -Present only when `GiftCardActivityType` is LOAD. +Represents details about a `LOAD` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,10 +12,10 @@ Present only when `GiftCardActivityType` is LOAD. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `amountMoney` | [`Money \| undefined`](../../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. | -| `orderId` | `string \| undefined` | Optional | The `order_id` of the order associated with the activity.
It is populated along with `line_item_uid` and is required if using the Square Orders API. | -| `lineItemUid` | `string \| undefined` | Optional | The `line_item_uid` of the gift card’s line item in the order associated with the activity.
It is populated along with `order_id` and is required if using the Square Orders API. | -| `referenceId` | `string \| undefined` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Orders
API is not being used. | -| `buyerPaymentInstrumentIds` | `string[] \| undefined` | Optional | If you are not using the Orders API, this field is required because it is used to identify a buyer
to perform compliance checks. | +| `orderId` | `string \| undefined` | Optional | The ID of the [order](../../doc/models/order.md) that contains the `GIFT_CARD` line item.

Applications that use the Square Orders API to process orders must specify the order ID in the
[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) request. | +| `lineItemUid` | `string \| undefined` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card.

Applications that use the Square Orders API to process orders must specify the line item UID
in the [CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) request. | +| `referenceId` | `string \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom order processing system can use this field to track information related to
an order or payment. | +| `buyerPaymentInstrumentIds` | `string[] \| undefined` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-redeem-status.md b/doc/models/gift-card-activity-redeem-status.md new file mode 100644 index 00000000..ea411fbe --- /dev/null +++ b/doc/models/gift-card-activity-redeem-status.md @@ -0,0 +1,19 @@ + +# Gift Card Activity Redeem Status + +Indicates the status of a [gift card](../../doc/models/gift-card.md) redemption. This status is relevant only for +redemptions made from Square products (such as Square Point of Sale) because Square products use a +two-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` status. + +## Enumeration + +`GiftCardActivityRedeemStatus` + +## Fields + +| Name | Description | +| --- | --- | +| `PENDING` | The gift card redemption is pending. `PENDING` is a temporary status that applies when a
gift card is redeemed from Square Point of Sale or another Square product. A `PENDING` status is updated to
`COMPLETED` if the payment is captured or `CANCELED` if the authorization is voided. | +| `COMPLETED` | The gift card redemption is completed. | +| `CANCELED` | The gift card redemption is canceled. A redemption is canceled if the authorization
on the gift card is voided. | + diff --git a/doc/models/gift-card-activity-redeem.md b/doc/models/gift-card-activity-redeem.md index 00f0948c..aef2faa1 100644 --- a/doc/models/gift-card-activity-redeem.md +++ b/doc/models/gift-card-activity-redeem.md @@ -1,7 +1,7 @@ # Gift Card Activity Redeem -Present only when `GiftCardActivityType` is REDEEM. +Represents details about a `REDEEM` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,8 +12,9 @@ Present only when `GiftCardActivityType` is REDEEM. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `amountMoney` | [`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. | -| `paymentId` | `string \| undefined` | Optional | When the Square Payments API is used, Redeem is not called on the Gift Cards API.
However, when Square reads a Redeem activity from the Gift Cards API, developers need to know the
associated `payment_id`. | -| `referenceId` | `string \| undefined` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Orders
API is not being used. | +| `paymentId` | `string \| undefined` | Optional | The ID of the payment that represents the gift card redemption. Square populates this field
if the payment was processed by Square. | +| `referenceId` | `string \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom payment processing system can use this field to track information
related to an order or payment. | +| `status` | [`string \| undefined`](../../doc/models/gift-card-activity-redeem-status.md) | Optional | Indicates the status of a [gift card](../../doc/models/gift-card.md) redemption. This status is relevant only for
redemptions made from Square products (such as Square Point of Sale) because Square products use a
two-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` status. | ## Example (as JSON) @@ -24,7 +25,8 @@ Present only when `GiftCardActivityType` is REDEEM. "currency": null }, "payment_id": null, - "reference_id": null + "reference_id": null, + "status": null } ``` diff --git a/doc/models/gift-card-activity-refund.md b/doc/models/gift-card-activity-refund.md index 6e6a10d9..eb0a1311 100644 --- a/doc/models/gift-card-activity-refund.md +++ b/doc/models/gift-card-activity-refund.md @@ -1,7 +1,7 @@ # Gift Card Activity Refund -Present only when `GiftCardActivityType` is REFUND. +Represents details about a `REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,16 +11,16 @@ Present only when `GiftCardActivityType` is REFUND. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `redeemActivityId` | `string` | Required | The ID for the Redeem activity that needs to be refunded. Hence, the activity it
refers to has to be of the REDEEM type. | +| `redeemActivityId` | `string \| undefined` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the
`payment_id` in the corresponding [RefundPayment](../../doc/api/refunds.md#refund-payment) request
represents a redemption made by the same gift card.

Applications that use a custom payment processing system can use this field in a
[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity)
request to link a refund with a `REDEEM` activity for the same gift card. | | `amountMoney` | [`Money \| undefined`](../../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. | -| `referenceId` | `string \| undefined` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Orders
API is not being used. | -| `paymentId` | `string \| undefined` | Optional | When the Square Payments API is used, Refund is not called on the Gift Cards API.
However, when Square reads a Refund activity from the Gift Cards API, the developer needs to know the
ID of the payment (made using this gift card) that is being refunded. | +| `referenceId` | `string \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom payment processing system can use this field to track information
related to an order or payment. | +| `paymentId` | `string \| undefined` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a
payment processed by Square. The payment source can be the same gift card or a cross-tender payment from a
credit card or a different gift card. Cross-tender payments can only be refunded from Square Point of Sale
or other Square products. | ## Example (as JSON) ```json { - "redeem_activity_id": "redeem_activity_id0", + "redeem_activity_id": null, "amount_money": null, "reference_id": null, "payment_id": null diff --git a/doc/models/gift-card-activity-type.md b/doc/models/gift-card-activity-type.md index fc5a5b53..e1caba82 100644 --- a/doc/models/gift-card-activity-type.md +++ b/doc/models/gift-card-activity-type.md @@ -1,7 +1,7 @@ # Gift Card Activity Type -Indicates the gift card activity type. +Indicates the type of [gift card activity](../../doc/models/gift-card-activity.md). ## Enumeration @@ -11,17 +11,17 @@ Indicates the gift card activity type. | Name | Description | | --- | --- | -| `ACTIVATE` | Activated a gift card with a balance. | +| `ACTIVATE` | Activated a gift card with a balance. When a gift card is activated, Square changes
the gift card state from `PENDING` to `ACTIVE`. A gift card must be in the `ACTIVE` state
to be used for other balance-changing activities. | | `LOAD` | Loaded a gift card with additional funds. | -| `REDEEM` | Redeemed a gift card. | -| `CLEAR_BALANCE` | Cleared a gift card balance to zero. | -| `DEACTIVATE` | Permanently blocked a gift card from a balance-changing
activity. | -| `ADJUST_INCREMENT` | Manually increased a gift card balance. | -| `ADJUST_DECREMENT` | Manually decreased a gift card balance. | -| `REFUND` | Added money to a gift card because a transaction
paid with this gift card was refunded. | -| `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card because a transaction
not linked to this gift card was refunded
to this gift card. | -| `IMPORT` | Imported a third-party gift card. | -| `BLOCK` | Temporarily blocked a gift card from balance-changing
activities. | -| `UNBLOCK` | Unblocked a gift card. It can resume balance-changing activities. | -| `IMPORT_REVERSAL` | A third-party gift card was imported with a balance.
The import is reversed. | +| `REDEEM` | Redeemed a gift card for a purchase. | +| `CLEAR_BALANCE` | Set the balance of a gift card to zero. | +| `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. The refund might be linked to
a Square payment, depending on how the payment and refund are processed. For example:

- A gift card payment processed by Square can be refunded to the same gift card.
- A cross-tender payment processed by Square can be refunded to a gift card. The cross-tender
payment source can be a credit card or different gift card.
- A payment processed with a custom processing system (instead of the Square Payments API) can
be refunded to a gift card. | +| `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card from a refunded transaction that is not linked to the gift card.

This activity type is included for backward compatibility and should not be used to create a refund.
Instead, use the `REFUND` activity type. | +| `IMPORT` | Imported a third-party gift card with a balance. `IMPORT` activities are managed
by Square and cannot be created using the Gift Card Activities API. | +| `BLOCK` | Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities
are managed by Square and cannot be created using the Gift Card Activities API. | +| `UNBLOCK` | Unblocked a gift card, which enables it to resume balance-changing activities. `UNBLOCK`
activities are managed by Square and cannot be created using the Gift Card Activities API. | +| `IMPORT_REVERSAL` | Reversed the import of a third-party gift card, which sets the gift card state to
`PENDING` and clears the balance. `IMPORT_REVERSAL` activities are managed by Square and
cannot be created using the Gift Card Activities API. | diff --git a/doc/models/gift-card-activity-unblock-reason.md b/doc/models/gift-card-activity-unblock-reason.md index 40304220..11ccbda8 100644 --- a/doc/models/gift-card-activity-unblock-reason.md +++ b/doc/models/gift-card-activity-unblock-reason.md @@ -1,6 +1,8 @@ # Gift Card Activity Unblock Reason +Indicates the reason for unblocking a [gift card](../../doc/models/gift-card.md). + ## Enumeration `GiftCardActivityUnblockReason` diff --git a/doc/models/gift-card-activity-unblock.md b/doc/models/gift-card-activity-unblock.md index bf73da8c..c2e830af 100644 --- a/doc/models/gift-card-activity-unblock.md +++ b/doc/models/gift-card-activity-unblock.md @@ -1,7 +1,7 @@ # Gift Card Activity Unblock -Present only when `GiftCardActivityType` is UNBLOCK. +Represents details about an `UNBLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -11,7 +11,7 @@ Present only when `GiftCardActivityType` is UNBLOCK. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `reason` | `string` | Required, Constant | **Default**: `'CHARGEBACK_UNBLOCK'` | +| `reason` | `string` | Required, Constant | Indicates the reason for unblocking a [gift card](../../doc/models/gift-card.md).
**Default**: `'CHARGEBACK_UNBLOCK'` | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-unlinked-activity-refund.md b/doc/models/gift-card-activity-unlinked-activity-refund.md index bc6b7eb9..df9509ee 100644 --- a/doc/models/gift-card-activity-unlinked-activity-refund.md +++ b/doc/models/gift-card-activity-unlinked-activity-refund.md @@ -1,7 +1,7 @@ # Gift Card Activity Unlinked Activity Refund -Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. +Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). ## Structure @@ -12,8 +12,8 @@ Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. | Name | Type | Tags | Description | | --- | --- | --- | --- | | `amountMoney` | [`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. | -| `referenceId` | `string \| undefined` | Optional | A client-specified ID to associate an entity, in another system, with this gift card
activity. This can be used to track the order or payment related information when the Square Payments
API is not being used. | -| `paymentId` | `string \| undefined` | Optional | When using the Square Payments API, the ID of the payment that was refunded to this gift
card. | +| `referenceId` | `string \| 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. This field is not used starting in Square version 2022-06-16. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity.md b/doc/models/gift-card-activity.md index f77e0b81..a8683d76 100644 --- a/doc/models/gift-card-activity.md +++ b/doc/models/gift-card-activity.md @@ -1,7 +1,9 @@ # Gift Card Activity -Represents an action performed on a gift card that affects its state or balance. +Represents an action performed on a [gift card](../../doc/models/gift-card.md) that affects its state or balance. +A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity +includes a `redeem_activity_details` field that contains information about the redemption. ## Structure @@ -11,26 +13,26 @@ Represents an action performed on a gift card that affects its state or balance. | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `id` | `string \| undefined` | Optional | The unique ID of the gift card activity. | -| `type` | [`string`](../../doc/models/gift-card-activity-type.md) | Required | Indicates the gift card activity type. | -| `locationId` | `string` | Required | The ID of the location at which the activity occurred. | +| `id` | `string \| undefined` | Optional | The Square-assigned ID of the gift card activity. | +| `type` | [`string`](../../doc/models/gift-card-activity-type.md) | Required | Indicates the type of [gift card activity](../../doc/models/gift-card-activity.md). | +| `locationId` | `string` | Required | The ID of the [business location](../../doc/models/location.md) where the activity occurred. | | `createdAt` | `string \| undefined` | Optional | The timestamp when the gift card activity was created, in RFC 3339 format. | -| `giftCardId` | `string \| undefined` | Optional | The gift card ID. The ID is not required if a GAN is present. | -| `giftCardGan` | `string \| undefined` | Optional | The gift card GAN. The GAN is not required if `gift_card_id` is present. | +| `giftCardId` | `string \| undefined` | Optional | The gift card ID. When creating a gift card activity, `gift_card_id` is not required if
`gift_card_gan` is specified. | +| `giftCardGan` | `string \| undefined` | Optional | The gift card account number (GAN). When creating a gift card activity, `gift_card_gan`
is not required if `gift_card_id` is specified. | | `giftCardBalanceMoney` | [`Money \| undefined`](../../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. | -| `loadActivityDetails` | [`GiftCardActivityLoad \| undefined`](../../doc/models/gift-card-activity-load.md) | Optional | Present only when `GiftCardActivityType` is LOAD. | -| `activateActivityDetails` | [`GiftCardActivityActivate \| undefined`](../../doc/models/gift-card-activity-activate.md) | Optional | Describes a gift card activity of the ACTIVATE type. | -| `redeemActivityDetails` | [`GiftCardActivityRedeem \| undefined`](../../doc/models/gift-card-activity-redeem.md) | Optional | Present only when `GiftCardActivityType` is REDEEM. | -| `clearBalanceActivityDetails` | [`GiftCardActivityClearBalance \| undefined`](../../doc/models/gift-card-activity-clear-balance.md) | Optional | Describes a gift card activity of the CLEAR_BALANCE type. | -| `deactivateActivityDetails` | [`GiftCardActivityDeactivate \| undefined`](../../doc/models/gift-card-activity-deactivate.md) | Optional | Describes a gift card activity of the DEACTIVATE type. | -| `adjustIncrementActivityDetails` | [`GiftCardActivityAdjustIncrement \| undefined`](../../doc/models/gift-card-activity-adjust-increment.md) | Optional | Describes a gift card activity of the ADJUST_INCREMENT type. | -| `adjustDecrementActivityDetails` | [`GiftCardActivityAdjustDecrement \| undefined`](../../doc/models/gift-card-activity-adjust-decrement.md) | Optional | Describes a gift card activity of the ADJUST_DECREMENT type. | -| `refundActivityDetails` | [`GiftCardActivityRefund \| undefined`](../../doc/models/gift-card-activity-refund.md) | Optional | Present only when `GiftCardActivityType` is REFUND. | -| `unlinkedActivityRefundActivityDetails` | [`GiftCardActivityUnlinkedActivityRefund \| undefined`](../../doc/models/gift-card-activity-unlinked-activity-refund.md) | Optional | Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. | -| `importActivityDetails` | [`GiftCardActivityImport \| undefined`](../../doc/models/gift-card-activity-import.md) | Optional | Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER
(a third-party gift card). | -| `blockActivityDetails` | [`GiftCardActivityBlock \| undefined`](../../doc/models/gift-card-activity-block.md) | Optional | Describes a gift card activity of the BLOCK type. | -| `unblockActivityDetails` | [`GiftCardActivityUnblock \| undefined`](../../doc/models/gift-card-activity-unblock.md) | Optional | Present only when `GiftCardActivityType` is UNBLOCK. | -| `importReversalActivityDetails` | [`GiftCardActivityImportReversal \| undefined`](../../doc/models/gift-card-activity-import-reversal.md) | Optional | Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER | +| `loadActivityDetails` | [`GiftCardActivityLoad \| undefined`](../../doc/models/gift-card-activity-load.md) | Optional | Represents details about a `LOAD` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `activateActivityDetails` | [`GiftCardActivityActivate \| undefined`](../../doc/models/gift-card-activity-activate.md) | Optional | Represents details about an `ACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `redeemActivityDetails` | [`GiftCardActivityRedeem \| undefined`](../../doc/models/gift-card-activity-redeem.md) | Optional | Represents details about a `REDEEM` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `clearBalanceActivityDetails` | [`GiftCardActivityClearBalance \| undefined`](../../doc/models/gift-card-activity-clear-balance.md) | Optional | Represents details about a `CLEAR_BALANCE` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `deactivateActivityDetails` | [`GiftCardActivityDeactivate \| undefined`](../../doc/models/gift-card-activity-deactivate.md) | Optional | Represents details about a `DEACTIVATE` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `adjustIncrementActivityDetails` | [`GiftCardActivityAdjustIncrement \| undefined`](../../doc/models/gift-card-activity-adjust-increment.md) | Optional | Represents details about an `ADJUST_INCREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `adjustDecrementActivityDetails` | [`GiftCardActivityAdjustDecrement \| undefined`](../../doc/models/gift-card-activity-adjust-decrement.md) | Optional | Represents details about an `ADJUST_DECREMENT` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `refundActivityDetails` | [`GiftCardActivityRefund \| undefined`](../../doc/models/gift-card-activity-refund.md) | Optional | Represents details about a `REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `unlinkedActivityRefundActivityDetails` | [`GiftCardActivityUnlinkedActivityRefund \| undefined`](../../doc/models/gift-card-activity-unlinked-activity-refund.md) | Optional | Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `importActivityDetails` | [`GiftCardActivityImport \| undefined`](../../doc/models/gift-card-activity-import.md) | Optional | Represents details about an `IMPORT` [gift card activity type](../../doc/models/gift-card-activity-type.md).
This activity type is used when Square imports a third-party gift card, in which case the
`gan_source` of the gift card is set to `OTHER`. | +| `blockActivityDetails` | [`GiftCardActivityBlock \| undefined`](../../doc/models/gift-card-activity-block.md) | Optional | Represents details about a `BLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `unblockActivityDetails` | [`GiftCardActivityUnblock \| undefined`](../../doc/models/gift-card-activity-unblock.md) | Optional | Represents details about an `UNBLOCK` [gift card activity type](../../doc/models/gift-card-activity-type.md). | +| `importReversalActivityDetails` | [`GiftCardActivityImportReversal \| undefined`](../../doc/models/gift-card-activity-import-reversal.md) | Optional | Represents details about an `IMPORT_REVERSAL` [gift card activity type](../../doc/models/gift-card-activity-type.md). | ## Example (as JSON) diff --git a/doc/models/list-catalog-request.md b/doc/models/list-catalog-request.md index 16f0d504..d395f61e 100644 --- a/doc/models/list-catalog-request.md +++ b/doc/models/list-catalog-request.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `string \| undefined` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
The page size is currently set to be 100.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `types` | `string \| undefined` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | +| `types` | `string \| undefined` | Optional | An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the [CatalogObjectType](../../doc/models/catalog-object-type.md) enum, for example,
`ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,
`MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST,
PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | | `catalogVersion` | `bigint \| undefined` | Optional | The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the [CatalogObject](../../doc/models/catalog-object.md)s' `version` attribute. If not included, results will
be from the current version of the catalog. | ## Example (as JSON) diff --git a/doc/models/payment-options.md b/doc/models/payment-options.md index ef606a48..76703a85 100644 --- a/doc/models/payment-options.md +++ b/doc/models/payment-options.md @@ -11,7 +11,7 @@ | --- | --- | --- | --- | | `autocomplete` | `boolean \| undefined` | Optional | Indicates whether the `Payment` objects created from this `TerminalCheckout` are automatically
`COMPLETED` or left in an `APPROVED` state for later modification. | | `delayDuration` | `string \| undefined` | Optional | The duration of time after the payment's creation when Square automatically cancels the
payment. This automatic cancellation applies only to payments that do not reach a terminal state
(COMPLETED, CANCELED, or FAILED) before the `delay_duration` time period.

This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value
of 1 minute.

Note: This feature is only supported for card payments. This parameter can only be set for a delayed
capture payment (`autocomplete=false`).
Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time. | -| `acceptPartialAuthorization` | `boolean \| undefined` | Optional | If set to `true` and charging a Square Gift Card, a payment might be returned with
`amount_money` equal to less than what was requested. For example, a request for $20 when charging
a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose
to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card
payment. This field cannot be `true` when `autocomplete = true`.

For more information, see
[Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).

Default: false | +| `acceptPartialAuthorization` | `boolean \| undefined` | Optional | If set to `true` and charging a Square Gift Card, a payment might be returned with
`amount_money` equal to less than what was requested. For example, a request for $20 when charging
a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose
to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card
payment.

This field cannot be `true` when `autocomplete = true`.
This field cannot be `true` when an `order_id` isn't specified.

For more information, see
[Take Partial Payments](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/partial-payments-with-gift-cards).

Default: false | ## Example (as JSON) diff --git a/doc/models/payment.md b/doc/models/payment.md index 09f39e2a..b976e450 100644 --- a/doc/models/payment.md +++ b/doc/models/payment.md @@ -23,7 +23,7 @@ Represents a payment processed by the Square API. | `refundedMoney` | [`Money \| undefined`](../../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. | | `status` | `string \| undefined` | Optional | Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.
**Constraints**: *Maximum Length*: `50` | | `delayDuration` | `string \| undefined` | 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. | -| `delayAction` | `string \| undefined` | Optional | The action to be applied to the payment when the `delay_duration` has elapsed. This field
is read-only.

Current values include `CANCEL`. | +| `delayAction` | `string \| undefined` | Optional | The action to be applied to the payment when the `delay_duration` has elapsed.

Current values include `CANCEL` and `COMPLETE`. | | `delayedUntil` | `string \| undefined` | 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. | | `sourceType` | `string \| undefined` | Optional | The source type for this payment.

Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `CASH`, or
`EXTERNAL`. For information about these payment source types,
see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).
**Constraints**: *Maximum Length*: `50` | | `cardDetails` | [`CardPaymentDetails \| undefined`](../../doc/models/card-payment-details.md) | Optional | Reflects the current status of a card payment. Contains only non-confidential information. | @@ -45,7 +45,7 @@ Represents a payment processed by the Square API. | `shippingAddress` | [`Address \| undefined`](../../doc/models/address.md) | Optional | Represents a postal address in a country.
For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | | `note` | `string \| undefined` | Optional | An optional note to include when creating a payment.
**Constraints**: *Maximum Length*: `500` | | `statementDescriptionIdentifier` | `string \| undefined` | Optional | Additional payment information that gets added to the customer's card statement
as part of the statement description.

Note that the `statement_description_identifier` might get truncated on the statement description
to fit the required information including the Square identifier (SQ *) and the name of the
seller taking the payment. | -| `capabilities` | `string[] \| undefined` | Optional | Actions that can be performed on this payment:

- `EDIT_AMOUNT_UP` - The payment amount can be edited up.
- `EDIT_AMOUNT_DOWN` - The payment amount can be edited down.
- `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up.
- `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down. | +| `capabilities` | `string[] \| undefined` | Optional | Actions that can be performed on this payment:

- `EDIT_AMOUNT_UP` - The payment amount can be edited up.
- `EDIT_AMOUNT_DOWN` - The payment amount can be edited down.
- `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up.
- `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down.
- `EDIT_DELAY_ACTION` - The delay_action can be edited. | | `receiptNumber` | `string \| undefined` | Optional | The payment's receipt number.
The field is missing if a payment is canceled.
**Constraints**: *Maximum Length*: `4` | | `receiptUrl` | `string \| undefined` | Optional | The URL for the payment's receipt.
The field is only populated for COMPLETED payments.
**Constraints**: *Maximum Length*: `255` | | `deviceDetails` | [`DeviceDetails \| undefined`](../../doc/models/device-details.md) | Optional | Details about the device that took the payment. | diff --git a/doc/models/payout.md b/doc/models/payout.md index 3aa9bd57..4cdd0727 100644 --- a/doc/models/payout.md +++ b/doc/models/payout.md @@ -21,7 +21,7 @@ external bank account or to the Square balance. | `destination` | [`Destination \| undefined`](../../doc/models/destination.md) | Optional | Information about the destination against which the payout was made. | | `version` | `number \| undefined` | Optional | The version number, which is incremented each time an update is made to this payout record.
The version number helps developers receive event notifications or feeds out of order. | | `type` | [`string \| undefined`](../../doc/models/payout-type.md) | Optional | The type of payout: “BATCH” or “SIMPLE”.
BATCH payouts include a list of payout entries that can be considered settled.
SIMPLE payouts do not have any payout entries associated with them
and will show up as one of the payout entries in a future BATCH payout. | -| `payoutFee` | [`PayoutFee[] \| undefined`](../../doc/models/payout-fee.md) | Optional | A list of processing fees and any taxes on the fees assessed by Square for this payout. | +| `payoutFee` | [`PayoutFee[] \| undefined`](../../doc/models/payout-fee.md) | Optional | A list of transfer fees and any taxes on the fees assessed by Square for this payout. | | `arrivalDate` | `string \| undefined` | Optional | The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination. | ## Example (as JSON) diff --git a/doc/models/search-catalog-objects-request.md b/doc/models/search-catalog-objects-request.md index afac58e6..9718d178 100644 --- a/doc/models/search-catalog-objects-request.md +++ b/doc/models/search-catalog-objects-request.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `cursor` | `string \| undefined` | Optional | The pagination cursor returned in the previous response. Leave unset for an initial request.
See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | -| `objectTypes` | [`string[] \| undefined`](../../doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION,
SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | +| `objectTypes` | [`string[] \| undefined`](../../doc/models/catalog-object-type.md) | Optional | The desired set of object types to appear in the search results.

If this is unspecified, the operation returns objects of all the top level types at the version
of the Square API used to make the request. Object types that are nested onto other object types
are not included in the defaults.

At the current API version the default object types are:
ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST,
PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,
SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. | | `includeDeletedObjects` | `boolean \| undefined` | Optional | If `true`, deleted objects will be included in the results. Deleted objects will have their
`is_deleted` field set to `true`. | | `includeRelatedObjects` | `boolean \| undefined` | Optional | If `true`, the response will include additional objects that are related to the
requested objects. Related objects are objects that are referenced by object ID by the objects
in the response. This is helpful if the objects are being fetched for immediate display to a user.
This process only goes one level deep. Objects referenced by the related objects will not be included.
For example:

If the `objects` field of the response contains a CatalogItem, its associated
CatalogCategory objects, CatalogTax objects, CatalogImage objects and
CatalogModifierLists will be returned in the `related_objects` field of the
response. If the `objects` field of the response contains a CatalogItemVariation,
its parent CatalogItem will be returned in the `related_objects` field of
the response.

Default value: `false` | | `beginTime` | `string \| undefined` | Optional | Return objects modified after this [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates), in RFC 3339
format, e.g., `2016-09-04T23:59:33.123Z`. The timestamp is exclusive - objects with a
timestamp equal to `begin_time` will not be included in the response. | diff --git a/doc/models/subscription-phase.md b/doc/models/subscription-phase.md index 9506ce76..6772b093 100644 --- a/doc/models/subscription-phase.md +++ b/doc/models/subscription-phase.md @@ -15,7 +15,7 @@ Describes a phase in a subscription plan. For more information, see | `uid` | `string \| undefined` | Optional | The Square-assigned ID of the subscription phase. This field cannot be changed after a `SubscriptionPhase` is created. | | `cadence` | [`string`](../../doc/models/subscription-cadence.md) | Required | Determines the billing cadence of a [Subscription](../../doc/models/subscription.md) | | `periods` | `number \| undefined` | Optional | The number of `cadence`s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after a `SubscriptionPhase` is created. | -| `recurringPriceMoney` | [`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. | +| `recurringPriceMoney` | [`Money \| undefined`](../../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. | | `ordinal` | `bigint \| undefined` | Optional | The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created. | ## Example (as JSON) @@ -25,10 +25,7 @@ Describes a phase in a subscription plan. For more information, see "uid": null, "cadence": "DAILY", "periods": null, - "recurring_price_money": { - "amount": null, - "currency": null - }, + "recurring_price_money": null, "ordinal": null } ``` diff --git a/doc/models/terminal-action-action-type.md b/doc/models/terminal-action-action-type.md index 61f563bc..96a39d96 100644 --- a/doc/models/terminal-action-action-type.md +++ b/doc/models/terminal-action-action-type.md @@ -11,5 +11,6 @@ Describes the type of this unit and indicates which field contains the unit info | Name | Description | | --- | --- | +| `PING` | The action represents a request to check if the specific device is
online or currently active with the merchant in question. Does not require an action options value. | | `SAVE_CARD` | Represents a request to save a card for future card-on-file use. | diff --git a/doc/models/terminal-action.md b/doc/models/terminal-action.md index 70074ea5..19a46df4 100644 --- a/doc/models/terminal-action.md +++ b/doc/models/terminal-action.md @@ -1,6 +1,8 @@ # Terminal Action +Represents an action processed by the Square Terminal. + ## Structure `TerminalAction` @@ -19,6 +21,7 @@ | `appId` | `string \| undefined` | Optional | The ID of the application that created the action. | | `type` | [`string \| undefined`](../../doc/models/terminal-action-action-type.md) | Optional | Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. | | `saveCardOptions` | [`SaveCardOptions \| undefined`](../../doc/models/save-card-options.md) | Optional | Describes save-card action fields. | +| `deviceMetadata` | [`DeviceMetadata \| undefined`](../../doc/models/device-metadata.md) | Optional | - | ## Example (as JSON) @@ -33,7 +36,8 @@ "updated_at": null, "app_id": null, "type": null, - "save_card_options": null + "save_card_options": null, + "device_metadata": null } ``` diff --git a/package.json b/package.json index ae8f24d8..2f08ae31 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "version": "19.0.0", + "version": "19.1.0", "license": "MIT", "sideEffects": false, "main": "dist/index.js", diff --git a/src/api/catalogApi.ts b/src/api/catalogApi.ts index 618b1583..e8bc6a49 100644 --- a/src/api/catalogApi.ts +++ b/src/api/catalogApi.ts @@ -292,10 +292,9 @@ export class CatalogApi extends BaseApi { * returns objects of all the top level types at the version of the Square API used * to make the request. Object types that are nested onto other object types are not * included in the defaults. At the current API version the default object types - * are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, - * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, - * QUICK_AMOUNT_SETTINGS. + * are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, + * TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, + * CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. * @param catalogVersion The specific version of the catalog objects to be included in the response. * This allows you to retrieve historical versions of objects. The specified version * value is matched against the [CatalogObject]($m/CatalogObject)s' `version` diff --git a/src/api/giftCardsApi.ts b/src/api/giftCardsApi.ts index cf8f7431..45cc5584 100644 --- a/src/api/giftCardsApi.ts +++ b/src/api/giftCardsApi.ts @@ -53,7 +53,7 @@ import { BaseApi } from './baseApi'; export class GiftCardsApi extends BaseApi { /** * Lists all gift cards. You can specify optional filters to retrieve - * a subset of the gift cards. + * a subset of the gift cards. Results are sorted by `created_at` in ascending order. * * @param type 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. diff --git a/src/api/loyaltyApi.ts b/src/api/loyaltyApi.ts index f222c386..60ec933e 100644 --- a/src/api/loyaltyApi.ts +++ b/src/api/loyaltyApi.ts @@ -160,7 +160,7 @@ export class LoyaltyApi extends BaseApi { } /** - * Adds points to a loyalty account. + * Adds points earned from the base loyalty program to a loyalty account. * * - If you are using the Orders API to manage orders, you only provide the `order_id`. * The endpoint reads the order to compute points to add to the buyer's account. @@ -170,6 +170,8 @@ export class LoyaltyApi extends BaseApi { * [CalculateLoyaltyPoints]($e/Loyalty/CalculateLoyaltyPoints) to compute the points * that you provide to this endpoint. * + * This endpoint excludes additional points earned from loyalty promotions. + * * @param accountId The [loyalty account]($m/LoyaltyAccount) ID to which * to add the points. * @param body An object containing the fields to POST for the @@ -299,7 +301,7 @@ export class LoyaltyApi extends BaseApi { } /** - * Calculates the points a purchase earns. + * Calculates the points a purchase earns from the base loyalty program. * * - If you are using the Orders API to manage orders, you provide the `order_id` in the request. The * endpoint calculates the points by reading the order. diff --git a/src/api/terminalApi.ts b/src/api/terminalApi.ts index 28dc8e4b..2b7b944a 100644 --- a/src/api/terminalApi.ts +++ b/src/api/terminalApi.ts @@ -76,8 +76,7 @@ import { BaseApi } from './baseApi'; export class TerminalApi extends BaseApi { /** - * Creates a Terminal action request and sends it to the specified device to take a payment - * for the requested amount. + * Creates a Terminal action request and sends it to the specified device. * * @param body An object containing the fields to POST for the request. * See the corresponding object definition for field diff --git a/src/client.ts b/src/client.ts index 60ba8b14..41abeb8f 100644 --- a/src/client.ts +++ b/src/client.ts @@ -63,7 +63,7 @@ import { import { XmlSerialization } from './http/xmlSerialization'; /** Current SDK version */ -export const SDK_VERSION = '19.0.0'; +export const SDK_VERSION = '19.1.0'; export class Client implements ClientInterface { private _config: Readonly; private _timeout: number; @@ -122,7 +122,7 @@ export class Client implements ClientInterface { ? this._config.httpClientOptions.timeout : this._config.timeout; this._userAgent = updateUserAgent( - 'Square-TypeScript-SDK/19.0.0 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}', + 'Square-TypeScript-SDK/19.1.0 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}', this._config.squareVersion, this._config.userAgentDetail ); diff --git a/src/defaultConfiguration.ts b/src/defaultConfiguration.ts index 0a329790..f7617438 100644 --- a/src/defaultConfiguration.ts +++ b/src/defaultConfiguration.ts @@ -4,7 +4,7 @@ import { RetryConfiguration } from './core'; /** Default values for the configuration parameters of the client. */ export const DEFAULT_CONFIGURATION: Configuration = { timeout: 60000, - squareVersion: '2022-05-12', + squareVersion: '2022-06-16', additionalHeaders: {}, userAgentDetail: '', environment: Environment.Production, diff --git a/src/index.ts b/src/index.ts index 8b70d693..a117450c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -281,6 +281,7 @@ export { Device } from './models/device'; export { DeviceCheckoutOptions } from './models/deviceCheckoutOptions'; export { DeviceCode } from './models/deviceCode'; export { DeviceDetails } from './models/deviceDetails'; +export { DeviceMetadata } from './models/deviceMetadata'; export { DigitalWalletDetails } from './models/digitalWalletDetails'; export { DisableCardResponse } from './models/disableCardResponse'; export { Dispute } from './models/dispute'; diff --git a/src/models/appointmentSegment.ts b/src/models/appointmentSegment.ts index 3c55b5f2..5223a4dc 100644 --- a/src/models/appointmentSegment.ts +++ b/src/models/appointmentSegment.ts @@ -14,11 +14,11 @@ export interface AppointmentSegment { /** The time span in minutes of an appointment segment. */ durationMinutes?: number; /** The ID of the [CatalogItemVariation]($m/CatalogItemVariation) object representing the service booked in this segment. */ - serviceVariationId: string; + serviceVariationId?: string; /** The ID of the [TeamMember]($m/TeamMember) object representing the team member booked in this segment. */ teamMemberId: string; /** The current version of the item variation representing the service booked in this segment. */ - serviceVariationVersion: bigint; + serviceVariationVersion?: bigint; /** Time between the end of this segment and the beginning of the subsequent segment. */ intermissionMinutes?: number; /** Whether the customer accepts any team member, instead of a specific one, to serve this segment. */ @@ -29,9 +29,9 @@ export interface AppointmentSegment { export const appointmentSegmentSchema: Schema = object({ durationMinutes: ['duration_minutes', optional(number())], - serviceVariationId: ['service_variation_id', string()], + serviceVariationId: ['service_variation_id', optional(string())], teamMemberId: ['team_member_id', string()], - serviceVariationVersion: ['service_variation_version', bigint()], + serviceVariationVersion: ['service_variation_version', optional(bigint())], intermissionMinutes: ['intermission_minutes', optional(number())], anyTeamMember: ['any_team_member', optional(boolean())], resourceIds: ['resource_ids', optional(array(string()))], diff --git a/src/models/batchRetrieveInventoryChangesRequest.ts b/src/models/batchRetrieveInventoryChangesRequest.ts index 8c5aac73..ac39b365 100644 --- a/src/models/batchRetrieveInventoryChangesRequest.ts +++ b/src/models/batchRetrieveInventoryChangesRequest.ts @@ -1,4 +1,4 @@ -import { array, object, optional, Schema, string } from '../schema'; +import { array, number, object, optional, Schema, string } from '../schema'; export interface BatchRetrieveInventoryChangesRequest { /** @@ -40,6 +40,7 @@ export interface BatchRetrieveInventoryChangesRequest { * See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. */ cursor?: string; + limit?: number; } export const batchRetrieveInventoryChangesRequestSchema: Schema = object( @@ -51,5 +52,6 @@ export const batchRetrieveInventoryChangesRequestSchema: Schema = object( @@ -38,5 +39,6 @@ export const batchRetrieveInventoryCountsRequestSchema: Schema = object({ @@ -83,4 +85,5 @@ export const cardSchema: Schema = object({ prepaidType: ['prepaid_type', optional(string())], bin: ['bin', optional(string())], version: ['version', optional(bigint())], + cardCoBrand: ['card_co_brand', optional(string())], }); diff --git a/src/models/catalogItemVariation.ts b/src/models/catalogItemVariation.ts index 6d342ba1..b560f7e2 100644 --- a/src/models/catalogItemVariation.ts +++ b/src/models/catalogItemVariation.ts @@ -106,12 +106,12 @@ export interface CatalogItemVariation { /** * Whether this variation can be sold. The inventory count of a sellable variation indicates * the number of units available for sale. When a variation is both stockable and sellable, - * its sellable inventory count can be smaller than or equal to its stocable count. + * its sellable inventory count can be smaller than or equal to its stockable count. */ sellable?: boolean; /** * Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE). - * The inventory count of a stockable variation keeps track of the number of units of this variation in stock + * When a variation is both stockable and sellable, the inventory count of a stockable variation keeps track of the number of units of this variation in stock * and is not an indicator of the number of units of the variation that can be sold. */ stockable?: boolean; diff --git a/src/models/createGiftCardActivityRequest.ts b/src/models/createGiftCardActivityRequest.ts index 8570bbb3..e917aecc 100644 --- a/src/models/createGiftCardActivityRequest.ts +++ b/src/models/createGiftCardActivityRequest.ts @@ -5,7 +5,11 @@ import { GiftCardActivity, giftCardActivitySchema } from './giftCardActivity'; export interface CreateGiftCardActivityRequest { /** A unique string that identifies the `CreateGiftCardActivity` request. */ idempotencyKey: string; - /** Represents an action performed on a gift card that affects its state or balance. */ + /** + * Represents an action performed on a [gift card]($m/GiftCard) that affects its state or balance. + * A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity + * includes a `redeem_activity_details` field that contains information about the redemption. + */ giftCardActivity: GiftCardActivity; } diff --git a/src/models/createGiftCardActivityResponse.ts b/src/models/createGiftCardActivityResponse.ts index 99977518..dc12b49f 100644 --- a/src/models/createGiftCardActivityResponse.ts +++ b/src/models/createGiftCardActivityResponse.ts @@ -9,7 +9,11 @@ import { GiftCardActivity, giftCardActivitySchema } from './giftCardActivity'; export interface CreateGiftCardActivityResponse { /** Any errors that occurred during the request. */ errors?: Error[]; - /** Represents an action performed on a gift card that affects its state or balance. */ + /** + * Represents an action performed on a [gift card]($m/GiftCard) that affects its state or balance. + * A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity + * includes a `redeem_activity_details` field that contains information about the redemption. + */ giftCardActivity?: GiftCardActivity; } diff --git a/src/models/createPaymentRequest.ts b/src/models/createPaymentRequest.ts index f0112f97..bf1e6fa7 100644 --- a/src/models/createPaymentRequest.ts +++ b/src/models/createPaymentRequest.ts @@ -60,11 +60,11 @@ export interface CreatePaymentRequest { */ appFeeMoney?: Money; /** - * The duration of time after the payment's creation when Square automatically cancels the - * payment. This automatic cancellation applies only to payments that do not reach a terminal state - * (COMPLETED, CANCELED, or FAILED) before the `delay_duration` time period. - * This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value - * of 1 minute. + * The duration of time after the payment's creation when Square automatically + * either completes or cancels the payment depending on the `delay_action` field value. + * For more information, see + * [Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). + * This parameter should be specified as a time duration, in RFC 3339 format. * Note: This feature is only supported for card payments. This parameter can only be set for a delayed * capture payment (`autocomplete=false`). * Default: @@ -72,6 +72,13 @@ export interface CreatePaymentRequest { * - Card-not-present payments: "P7D" (7 days) from the creation time. */ delayDuration?: string; + /** + * The action to be applied to the payment when the `delay_duration` has elapsed. The action must be + * CANCEL or COMPLETE. For more information, see + * [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). + * Default: CANCEL + */ + delayAction?: string; /** * If set to `true`, this payment will be completed when possible. If * set to `false`, this payment is held in an approved state until either @@ -164,6 +171,7 @@ export const createPaymentRequestSchema: Schema = object({ tipMoney: ['tip_money', optional(lazy(() => moneySchema))], appFeeMoney: ['app_fee_money', optional(lazy(() => moneySchema))], delayDuration: ['delay_duration', optional(string())], + delayAction: ['delay_action', optional(string())], autocomplete: ['autocomplete', optional(boolean())], orderId: ['order_id', optional(string())], customerId: ['customer_id', optional(string())], diff --git a/src/models/createTerminalActionRequest.ts b/src/models/createTerminalActionRequest.ts index 96aefdc4..fe9d70fd 100644 --- a/src/models/createTerminalActionRequest.ts +++ b/src/models/createTerminalActionRequest.ts @@ -8,6 +8,7 @@ export interface CreateTerminalActionRequest { * See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. */ idempotencyKey: string; + /** Represents an action processed by the Square Terminal. */ action: TerminalAction; } diff --git a/src/models/createTerminalActionResponse.ts b/src/models/createTerminalActionResponse.ts index 6dca4a6b..e33476d9 100644 --- a/src/models/createTerminalActionResponse.ts +++ b/src/models/createTerminalActionResponse.ts @@ -5,6 +5,7 @@ import { TerminalAction, terminalActionSchema } from './terminalAction'; export interface CreateTerminalActionResponse { /** Information on errors encountered during the request. */ errors?: Error[]; + /** Represents an action processed by the Square Terminal. */ action?: TerminalAction; } diff --git a/src/models/deviceMetadata.ts b/src/models/deviceMetadata.ts new file mode 100644 index 00000000..f747d34a --- /dev/null +++ b/src/models/deviceMetadata.ts @@ -0,0 +1,55 @@ +import { object, optional, Schema, string } from '../schema'; + +export interface DeviceMetadata { + /** The Terminal’s remaining battery percentage, between 1-100. */ + batteryPercentage?: string; + /** + * The current charging state of the Terminal. + * Options: `CHARGING`, `NOT_CHARGING` + */ + chargingState?: string; + /** The ID of the Square seller business location associated with the Terminal. */ + locationId?: string; + /** The ID of the Square merchant account that is currently signed-in to the Terminal. */ + merchantId?: string; + /** + * The Terminal’s current network connection type. + * Options: `WIFI`, `ETHERNET` + */ + networkConnectionType?: string; + /** The country in which the Terminal is authorized to take payments. */ + paymentRegion?: string; + /** + * The unique identifier assigned to the Terminal, which can be found on the lower back + * of the device. + */ + serialNumber?: string; + /** The current version of the Terminal’s operating system. */ + osVersion?: string; + /** The current version of the application running on the Terminal. */ + appVersion?: string; + /** The name of the Wi-Fi network to which the Terminal is connected. */ + wifiNetworkName?: string; + /** + * The signal strength of the Wi-FI network connection. + * Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT` + */ + wifiNetworkStrength?: string; + /** The IP address of the Terminal. */ + ipAddress?: string; +} + +export const deviceMetadataSchema: Schema = object({ + batteryPercentage: ['battery_percentage', optional(string())], + chargingState: ['charging_state', optional(string())], + locationId: ['location_id', optional(string())], + merchantId: ['merchant_id', optional(string())], + networkConnectionType: ['network_connection_type', optional(string())], + paymentRegion: ['payment_region', optional(string())], + serialNumber: ['serial_number', optional(string())], + osVersion: ['os_version', optional(string())], + appVersion: ['app_version', optional(string())], + wifiNetworkName: ['wifi_network_name', optional(string())], + wifiNetworkStrength: ['wifi_network_strength', optional(string())], + ipAddress: ['ip_address', optional(string())], +}); diff --git a/src/models/getTerminalActionResponse.ts b/src/models/getTerminalActionResponse.ts index c262baab..8817a5f4 100644 --- a/src/models/getTerminalActionResponse.ts +++ b/src/models/getTerminalActionResponse.ts @@ -5,6 +5,7 @@ import { TerminalAction, terminalActionSchema } from './terminalAction'; export interface GetTerminalActionResponse { /** Information on errors encountered during the request. */ errors?: Error[]; + /** Represents an action processed by the Square Terminal. */ action?: TerminalAction; } diff --git a/src/models/giftCardActivity.ts b/src/models/giftCardActivity.ts index 9f1f7a7a..df8a86dc 100644 --- a/src/models/giftCardActivity.ts +++ b/src/models/giftCardActivity.ts @@ -53,19 +53,29 @@ import { } from './giftCardActivityUnlinkedActivityRefund'; import { Money, moneySchema } from './money'; -/** Represents an action performed on a gift card that affects its state or balance. */ +/** + * Represents an action performed on a [gift card]($m/GiftCard) that affects its state or balance. + * A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity + * includes a `redeem_activity_details` field that contains information about the redemption. + */ export interface GiftCardActivity { - /** The unique ID of the gift card activity. */ + /** The Square-assigned ID of the gift card activity. */ id?: string; - /** Indicates the gift card activity type. */ + /** Indicates the type of [gift card activity]($m/GiftCardActivity). */ type: string; - /** The ID of the location at which the activity occurred. */ + /** The ID of the [business location]($m/Location) where the activity occurred. */ locationId: string; /** The timestamp when the gift card activity was created, in RFC 3339 format. */ createdAt?: string; - /** The gift card ID. The ID is not required if a GAN is present. */ + /** + * The gift card ID. When creating a gift card activity, `gift_card_id` is not required if + * `gift_card_gan` is specified. + */ giftCardId?: string; - /** The gift card GAN. The GAN is not required if `gift_card_id` is present. */ + /** + * The gift card account number (GAN). When creating a gift card activity, `gift_card_gan` + * is not required if `gift_card_id` is specified. + */ giftCardGan?: string; /** * Represents an amount of money. `Money` fields can be signed or unsigned. @@ -76,34 +86,35 @@ export interface GiftCardActivity { * for more information. */ giftCardBalanceMoney?: Money; - /** Present only when `GiftCardActivityType` is LOAD. */ + /** Represents details about a `LOAD` [gift card activity type]($m/GiftCardActivityType). */ loadActivityDetails?: GiftCardActivityLoad; - /** Describes a gift card activity of the ACTIVATE type. */ + /** Represents details about an `ACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ activateActivityDetails?: GiftCardActivityActivate; - /** Present only when `GiftCardActivityType` is REDEEM. */ + /** Represents details about a `REDEEM` [gift card activity type]($m/GiftCardActivityType). */ redeemActivityDetails?: GiftCardActivityRedeem; - /** Describes a gift card activity of the CLEAR_BALANCE type. */ + /** Represents details about a `CLEAR_BALANCE` [gift card activity type]($m/GiftCardActivityType). */ clearBalanceActivityDetails?: GiftCardActivityClearBalance; - /** Describes a gift card activity of the DEACTIVATE type. */ + /** Represents details about a `DEACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ deactivateActivityDetails?: GiftCardActivityDeactivate; - /** Describes a gift card activity of the ADJUST_INCREMENT type. */ + /** Represents details about an `ADJUST_INCREMENT` [gift card activity type]($m/GiftCardActivityType). */ adjustIncrementActivityDetails?: GiftCardActivityAdjustIncrement; - /** Describes a gift card activity of the ADJUST_DECREMENT type. */ + /** Represents details about an `ADJUST_DECREMENT` [gift card activity type]($m/GiftCardActivityType). */ adjustDecrementActivityDetails?: GiftCardActivityAdjustDecrement; - /** Present only when `GiftCardActivityType` is REFUND. */ + /** Represents details about a `REFUND` [gift card activity type]($m/GiftCardActivityType). */ refundActivityDetails?: GiftCardActivityRefund; - /** Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. */ + /** Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type]($m/GiftCardActivityType). */ unlinkedActivityRefundActivityDetails?: GiftCardActivityUnlinkedActivityRefund; /** - * Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER - * (a third-party gift card). + * Represents details about an `IMPORT` [gift card activity type]($m/GiftCardActivityType). + * This activity type is used when Square imports a third-party gift card, in which case the + * `gan_source` of the gift card is set to `OTHER`. */ importActivityDetails?: GiftCardActivityImport; - /** Describes a gift card activity of the BLOCK type. */ + /** Represents details about a `BLOCK` [gift card activity type]($m/GiftCardActivityType). */ blockActivityDetails?: GiftCardActivityBlock; - /** Present only when `GiftCardActivityType` is UNBLOCK. */ + /** Represents details about an `UNBLOCK` [gift card activity type]($m/GiftCardActivityType). */ unblockActivityDetails?: GiftCardActivityUnblock; - /** Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER */ + /** Represents details about an `IMPORT_REVERSAL` [gift card activity type]($m/GiftCardActivityType). */ importReversalActivityDetails?: GiftCardActivityImportReversal; } diff --git a/src/models/giftCardActivityActivate.ts b/src/models/giftCardActivityActivate.ts index cd9dd7a4..23da4755 100644 --- a/src/models/giftCardActivityActivate.ts +++ b/src/models/giftCardActivityActivate.ts @@ -1,7 +1,7 @@ import { array, lazy, object, optional, Schema, string } from '../schema'; import { Money, moneySchema } from './money'; -/** Describes a gift card activity of the ACTIVATE type. */ +/** Represents details about an `ACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityActivate { /** * Represents an amount of money. `Money` fields can be signed or unsigned. @@ -13,26 +13,31 @@ export interface GiftCardActivityActivate { */ amountMoney?: Money; /** - * The ID of the order associated with the activity. - * This is required if your application uses the Square Orders API. + * The ID of the [order]($m/Order) that contains the `GIFT_CARD` line item. + * Applications that use the Square Orders API to process orders must specify the order ID + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ orderId?: string; /** - * The `line_item_uid` of the gift card line item in an order. - * This is required if your application uses the Square Orders API. + * The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase. + * Applications that use the Square Orders API to process orders must specify the line item UID + * in the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ lineItemUid?: string; /** - * If your application does not use the Square Orders API, you can optionally use this field - * to associate the gift card activity with a client-side entity. + * A client-specified ID that associates the gift card activity with an entity in another system. + * Applications that use a custom order processing system can use this field to track information + * related to an order or payment. */ referenceId?: string; /** - * Required if your application does not use the Square Orders API. - * This is a list of client-provided payment instrument IDs. + * The payment instrument IDs used to process the gift card purchase, such as a credit card ID + * or bank account ID. + * Applications that use a custom order processing system must specify payment instrument IDs in + * the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. * Square uses this information to perform compliance checks. - * If you use the Square Orders API, Square has the necessary instrument IDs to perform necessary - * compliance checks. + * For applications that use the Square Orders API to process payments, Square has the necessary + * instrument IDs to perform compliance checks. */ buyerPaymentInstrumentIds?: string[]; } diff --git a/src/models/giftCardActivityAdjustDecrement.ts b/src/models/giftCardActivityAdjustDecrement.ts index aa1a6008..ad64c8ee 100644 --- a/src/models/giftCardActivityAdjustDecrement.ts +++ b/src/models/giftCardActivityAdjustDecrement.ts @@ -1,7 +1,7 @@ import { lazy, object, Schema, string } from '../schema'; import { Money, moneySchema } from './money'; -/** Describes a gift card activity of the ADJUST_DECREMENT type. */ +/** Represents details about an `ADJUST_DECREMENT` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityAdjustDecrement { /** * Represents an amount of money. `Money` fields can be signed or unsigned. @@ -12,6 +12,7 @@ export interface GiftCardActivityAdjustDecrement { * for more information. */ amountMoney: Money; + /** Indicates the reason for deducting money from a [gift card]($m/GiftCard). */ reason: string; } diff --git a/src/models/giftCardActivityAdjustIncrement.ts b/src/models/giftCardActivityAdjustIncrement.ts index 56906f42..8c190ad3 100644 --- a/src/models/giftCardActivityAdjustIncrement.ts +++ b/src/models/giftCardActivityAdjustIncrement.ts @@ -1,7 +1,7 @@ import { lazy, object, Schema, string } from '../schema'; import { Money, moneySchema } from './money'; -/** Describes a gift card activity of the ADJUST_INCREMENT type. */ +/** Represents details about an `ADJUST_INCREMENT` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityAdjustIncrement { /** * Represents an amount of money. `Money` fields can be signed or unsigned. @@ -12,6 +12,7 @@ export interface GiftCardActivityAdjustIncrement { * for more information. */ amountMoney: Money; + /** Indicates the reason for adding money to a [gift card]($m/GiftCard). */ reason: string; } diff --git a/src/models/giftCardActivityBlock.ts b/src/models/giftCardActivityBlock.ts index b46bbe3f..06cbc1f1 100644 --- a/src/models/giftCardActivityBlock.ts +++ b/src/models/giftCardActivityBlock.ts @@ -1,7 +1,8 @@ import { object, Schema, string } from '../schema'; -/** Describes a gift card activity of the BLOCK type. */ +/** Represents details about a `BLOCK` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityBlock { + /** Indicates the reason for blocking a [gift card]($m/GiftCard). */ reason: string; } diff --git a/src/models/giftCardActivityClearBalance.ts b/src/models/giftCardActivityClearBalance.ts index f804913c..daeeae64 100644 --- a/src/models/giftCardActivityClearBalance.ts +++ b/src/models/giftCardActivityClearBalance.ts @@ -1,7 +1,8 @@ import { object, Schema, string } from '../schema'; -/** Describes a gift card activity of the CLEAR_BALANCE type. */ +/** Represents details about a `CLEAR_BALANCE` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityClearBalance { + /** Indicates the reason for clearing the balance of a [gift card]($m/GiftCard). */ reason: string; } diff --git a/src/models/giftCardActivityDeactivate.ts b/src/models/giftCardActivityDeactivate.ts index c4fb7ba2..c4e6d9e6 100644 --- a/src/models/giftCardActivityDeactivate.ts +++ b/src/models/giftCardActivityDeactivate.ts @@ -1,7 +1,8 @@ import { object, Schema, string } from '../schema'; -/** Describes a gift card activity of the DEACTIVATE type. */ +/** Represents details about a `DEACTIVATE` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityDeactivate { + /** Indicates the reason for deactivating a [gift card]($m/GiftCard). */ reason: string; } diff --git a/src/models/giftCardActivityImport.ts b/src/models/giftCardActivityImport.ts index f3273ebb..bb1ea3a9 100644 --- a/src/models/giftCardActivityImport.ts +++ b/src/models/giftCardActivityImport.ts @@ -2,8 +2,9 @@ import { lazy, object, Schema } from '../schema'; import { Money, moneySchema } from './money'; /** - * Describes a gift card activity of the IMPORT type and the `GiftCardGANSource` is OTHER - * (a third-party gift card). + * Represents details about an `IMPORT` [gift card activity type]($m/GiftCardActivityType). + * This activity type is used when Square imports a third-party gift card, in which case the + * `gan_source` of the gift card is set to `OTHER`. */ export interface GiftCardActivityImport { /** diff --git a/src/models/giftCardActivityImportReversal.ts b/src/models/giftCardActivityImportReversal.ts index 0cdea70d..1abbb546 100644 --- a/src/models/giftCardActivityImportReversal.ts +++ b/src/models/giftCardActivityImportReversal.ts @@ -1,7 +1,7 @@ import { lazy, object, Schema } from '../schema'; import { Money, moneySchema } from './money'; -/** Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER */ +/** Represents details about an `IMPORT_REVERSAL` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityImportReversal { /** * Represents an amount of money. `Money` fields can be signed or unsigned. diff --git a/src/models/giftCardActivityLoad.ts b/src/models/giftCardActivityLoad.ts index b616abb8..286582b2 100644 --- a/src/models/giftCardActivityLoad.ts +++ b/src/models/giftCardActivityLoad.ts @@ -1,7 +1,7 @@ import { array, lazy, object, optional, Schema, string } from '../schema'; import { Money, moneySchema } from './money'; -/** Present only when `GiftCardActivityType` is LOAD. */ +/** Represents details about a `LOAD` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityLoad { /** * Represents an amount of money. `Money` fields can be signed or unsigned. @@ -13,24 +13,31 @@ export interface GiftCardActivityLoad { */ amountMoney?: Money; /** - * The `order_id` of the order associated with the activity. - * It is populated along with `line_item_uid` and is required if using the Square Orders API. + * The ID of the [order]($m/Order) that contains the `GIFT_CARD` line item. + * Applications that use the Square Orders API to process orders must specify the order ID in the + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ orderId?: string; /** - * The `line_item_uid` of the gift card’s line item in the order associated with the activity. - * It is populated along with `order_id` and is required if using the Square Orders API. + * The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card. + * Applications that use the Square Orders API to process orders must specify the line item UID + * in the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. */ lineItemUid?: string; /** - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * Applications that use a custom order processing system can use this field to track information related to + * an order or payment. */ referenceId?: string; /** - * If you are not using the Orders API, this field is required because it is used to identify a buyer - * to perform compliance checks. + * The payment instrument IDs used to process the order for the additional funds, such as a credit card ID + * or bank account ID. + * Applications that use a custom order processing system must specify payment instrument IDs in + * the [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) request. + * Square uses this information to perform compliance checks. + * For applications that use the Square Orders API to process payments, Square has the necessary + * instrument IDs to perform compliance checks. */ buyerPaymentInstrumentIds?: string[]; } diff --git a/src/models/giftCardActivityRedeem.ts b/src/models/giftCardActivityRedeem.ts index 602cab69..7b5e8de2 100644 --- a/src/models/giftCardActivityRedeem.ts +++ b/src/models/giftCardActivityRedeem.ts @@ -1,7 +1,7 @@ import { lazy, object, optional, Schema, string } from '../schema'; import { Money, moneySchema } from './money'; -/** Present only when `GiftCardActivityType` is REDEEM. */ +/** Represents details about a `REDEEM` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityRedeem { /** * Represents an amount of money. `Money` fields can be signed or unsigned. @@ -13,17 +13,22 @@ export interface GiftCardActivityRedeem { */ amountMoney: Money; /** - * When the Square Payments API is used, Redeem is not called on the Gift Cards API. - * However, when Square reads a Redeem activity from the Gift Cards API, developers need to know the - * associated `payment_id`. + * The ID of the payment that represents the gift card redemption. Square populates this field + * if the payment was processed by Square. */ paymentId?: string; /** - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * Applications that use a custom payment processing system can use this field to track information + * related to an order or payment. */ referenceId?: string; + /** + * Indicates the status of a [gift card]($m/GiftCard) redemption. This status is relevant only for + * redemptions made from Square products (such as Square Point of Sale) because Square products use a + * two-state process. Gift cards redeemed using the Gift Card Activities API always have a `COMPLETED` status. + */ + status?: string; } export const giftCardActivityRedeemSchema: Schema = object( @@ -31,5 +36,6 @@ export const giftCardActivityRedeemSchema: Schema = obje amountMoney: ['amount_money', lazy(() => moneySchema)], paymentId: ['payment_id', optional(string())], referenceId: ['reference_id', optional(string())], + status: ['status', optional(string())], } ); diff --git a/src/models/giftCardActivityRefund.ts b/src/models/giftCardActivityRefund.ts index 661f85e2..5d649624 100644 --- a/src/models/giftCardActivityRefund.ts +++ b/src/models/giftCardActivityRefund.ts @@ -1,13 +1,17 @@ import { lazy, object, optional, Schema, string } from '../schema'; import { Money, moneySchema } from './money'; -/** Present only when `GiftCardActivityType` is REFUND. */ +/** Represents details about a `REFUND` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityRefund { /** - * The ID for the Redeem activity that needs to be refunded. Hence, the activity it - * refers to has to be of the REDEEM type. + * The ID of the refunded `REDEEM` gift card activity. Square populates this field if the + * `payment_id` in the corresponding [RefundPayment]($e/Refunds/RefundPayment) request + * represents a redemption made by the same gift card. + * Applications that use a custom payment processing system can use this field in a + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) + * request to link a refund with a `REDEEM` activity for the same gift card. */ - redeemActivityId: string; + redeemActivityId?: string; /** * 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 @@ -18,22 +22,23 @@ export interface GiftCardActivityRefund { */ amountMoney?: Money; /** - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Orders - * API is not being used. + * A client-specified ID that associates the gift card activity with an entity in another system. + * Applications that use a custom payment processing system can use this field to track information + * related to an order or payment. */ referenceId?: string; /** - * When the Square Payments API is used, Refund is not called on the Gift Cards API. - * However, when Square reads a Refund activity from the Gift Cards API, the developer needs to know the - * ID of the payment (made using this gift card) that is being refunded. + * The ID of the refunded payment. Square populates this field if the refund is for a + * payment processed by Square. The payment source can be the same gift card or a cross-tender payment from a + * credit card or a different gift card. Cross-tender payments can only be refunded from Square Point of Sale + * or other Square products. */ paymentId?: string; } export const giftCardActivityRefundSchema: Schema = object( { - redeemActivityId: ['redeem_activity_id', string()], + redeemActivityId: ['redeem_activity_id', optional(string())], amountMoney: ['amount_money', optional(lazy(() => moneySchema))], referenceId: ['reference_id', optional(string())], paymentId: ['payment_id', optional(string())], diff --git a/src/models/giftCardActivityUnblock.ts b/src/models/giftCardActivityUnblock.ts index 6869a3cb..89bb7b7d 100644 --- a/src/models/giftCardActivityUnblock.ts +++ b/src/models/giftCardActivityUnblock.ts @@ -1,7 +1,8 @@ import { object, Schema, string } from '../schema'; -/** Present only when `GiftCardActivityType` is UNBLOCK. */ +/** Represents details about an `UNBLOCK` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityUnblock { + /** Indicates the reason for unblocking a [gift card]($m/GiftCard). */ reason: string; } diff --git a/src/models/giftCardActivityUnlinkedActivityRefund.ts b/src/models/giftCardActivityUnlinkedActivityRefund.ts index 376c1411..c68e90bc 100644 --- a/src/models/giftCardActivityUnlinkedActivityRefund.ts +++ b/src/models/giftCardActivityUnlinkedActivityRefund.ts @@ -1,7 +1,7 @@ import { lazy, object, optional, Schema, string } from '../schema'; import { Money, moneySchema } from './money'; -/** Present only when `GiftCardActivityType` is UNLINKED_ACTIVITY_REFUND. */ +/** Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type]($m/GiftCardActivityType). */ export interface GiftCardActivityUnlinkedActivityRefund { /** * Represents an amount of money. `Money` fields can be signed or unsigned. @@ -12,16 +12,9 @@ export interface GiftCardActivityUnlinkedActivityRefund { * for more information. */ amountMoney: Money; - /** - * A client-specified ID to associate an entity, in another system, with this gift card - * activity. This can be used to track the order or payment related information when the Square Payments - * API is not being used. - */ + /** A client-specified ID that associates the gift card activity with an entity in another system. */ referenceId?: string; - /** - * When using the Square Payments API, the ID of the payment that was refunded to this gift - * card. - */ + /** The ID of the refunded payment. This field is not used starting in Square version 2022-06-16. */ paymentId?: string; } diff --git a/src/models/listCatalogRequest.ts b/src/models/listCatalogRequest.ts index 521716ab..5401f3c1 100644 --- a/src/models/listCatalogRequest.ts +++ b/src/models/listCatalogRequest.ts @@ -16,8 +16,8 @@ export interface ListCatalogRequest { * of the Square API used to make the request. Object types that are nested onto other object types * are not included in the defaults. * At the current API version the default object types are: - * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, + * PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. */ types?: string; diff --git a/src/models/payment.ts b/src/models/payment.ts index 4a724ec9..f8bd2fb4 100644 --- a/src/models/payment.ts +++ b/src/models/payment.ts @@ -113,9 +113,8 @@ export interface Payment { */ delayDuration?: string; /** - * The action to be applied to the payment when the `delay_duration` has elapsed. This field - * is read-only. - * Current values include `CANCEL`. + * The action to be applied to the payment when the `delay_duration` has elapsed. + * Current values include `CANCEL` and `COMPLETE`. */ delayAction?: string; /** @@ -208,6 +207,7 @@ export interface Payment { * - `EDIT_AMOUNT_DOWN` - The payment amount can be edited down. * - `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up. * - `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down. + * - `EDIT_DELAY_ACTION` - The delay_action can be edited. */ capabilities?: string[]; /** diff --git a/src/models/paymentOptions.ts b/src/models/paymentOptions.ts index bc3937e7..abfb679b 100644 --- a/src/models/paymentOptions.ts +++ b/src/models/paymentOptions.ts @@ -24,9 +24,11 @@ export interface PaymentOptions { * `amount_money` equal to less than what was requested. For example, a request for $20 when charging * a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose * to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card - * payment. This field cannot be `true` when `autocomplete = true`. + * payment. + * This field cannot be `true` when `autocomplete = true`. + * This field cannot be `true` when an `order_id` isn't specified. * For more information, see - * [Partial amount with Square Gift Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card). + * [Take Partial Payments](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/partial-payments-with-gift-cards). * Default: false */ acceptPartialAuthorization?: boolean; diff --git a/src/models/payout.ts b/src/models/payout.ts index 35e75378..0753dc25 100644 --- a/src/models/payout.ts +++ b/src/models/payout.ts @@ -49,7 +49,7 @@ export interface Payout { * and will show up as one of the payout entries in a future BATCH payout. */ type?: string; - /** A list of processing fees and any taxes on the fees assessed by Square for this payout. */ + /** A list of transfer fees and any taxes on the fees assessed by Square for this payout. */ payoutFee?: PayoutFee[]; /** The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination. */ arrivalDate?: string; diff --git a/src/models/searchCatalogObjectsRequest.ts b/src/models/searchCatalogObjectsRequest.ts index 0ab678f4..f0927081 100644 --- a/src/models/searchCatalogObjectsRequest.ts +++ b/src/models/searchCatalogObjectsRequest.ts @@ -22,8 +22,8 @@ export interface SearchCatalogObjectsRequest { * of the Square API used to make the request. Object types that are nested onto other object types * are not included in the defaults. * At the current API version the default object types are: - * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, DINING_OPTION, TAX_EXEMPTION, - * SERVICE_CHARGE, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, + * ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, + * PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, * SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. */ objectTypes?: string[]; diff --git a/src/models/subscriptionPhase.ts b/src/models/subscriptionPhase.ts index 4b1443bd..450e21d4 100644 --- a/src/models/subscriptionPhase.ts +++ b/src/models/subscriptionPhase.ts @@ -28,7 +28,7 @@ export interface SubscriptionPhase { * [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) * for more information. */ - recurringPriceMoney: Money; + recurringPriceMoney?: Money; /** The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a `SubscriptionPhase` is created. */ ordinal?: bigint; } @@ -37,6 +37,9 @@ export const subscriptionPhaseSchema: Schema = object({ uid: ['uid', optional(string())], cadence: ['cadence', string()], periods: ['periods', optional(number())], - recurringPriceMoney: ['recurring_price_money', lazy(() => moneySchema)], + recurringPriceMoney: [ + 'recurring_price_money', + optional(lazy(() => moneySchema)), + ], ordinal: ['ordinal', optional(bigint())], }); diff --git a/src/models/terminalAction.ts b/src/models/terminalAction.ts index e9dcbb04..8fe7dfef 100644 --- a/src/models/terminalAction.ts +++ b/src/models/terminalAction.ts @@ -1,6 +1,8 @@ import { lazy, object, optional, Schema, string } from '../schema'; +import { DeviceMetadata, deviceMetadataSchema } from './deviceMetadata'; import { SaveCardOptions, saveCardOptionsSchema } from './saveCardOptions'; +/** Represents an action processed by the Square Terminal. */ export interface TerminalAction { /** A unique ID for this `TerminalAction`. */ id?: string; @@ -33,6 +35,7 @@ export interface TerminalAction { type?: string; /** Describes save-card action fields. */ saveCardOptions?: SaveCardOptions; + deviceMetadata?: DeviceMetadata; } export const terminalActionSchema: Schema = object({ @@ -49,4 +52,8 @@ export const terminalActionSchema: Schema = object({ 'save_card_options', optional(lazy(() => saveCardOptionsSchema)), ], + deviceMetadata: [ + 'device_metadata', + optional(lazy(() => deviceMetadataSchema)), + ], });