diff --git a/.fernignore b/.fernignore new file mode 100644 index 00000000..2f400769 --- /dev/null +++ b/.fernignore @@ -0,0 +1,2 @@ +lib/square_legacy/ +lib/square_legacy.rb \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index a8c103f9..ce31cac6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,960 +1,1056 @@ # Change Log -For general API and SDK changelogs, see [Square APIs and SDKs Release Notes](https://developer.squareup.com/docs/changelog/connect). +For general API and SDK changelogs, see [Square APIs and SDKs Release Notes](https://developer.squareup.com/docs/changelog/connect). ## Version 20.0.0.20220512 (2022-05-12) + - Dropped support for Ruby versions less than 2.7 ## Version 19.0.0.202204020 (2022-04-20) + - Increased range of supported Faraday versions ## Version 17.0.0.20211215 (2021-12-15) + ### API updates -* **Invoices API:** - * The Invoices API now supports seller accounts in France. For more information, see [International availability and considerations.](https://developer.squareup.com/docs/invoices-api/overview#international-availability-invoices) - * France only: [`Invoice`](https://developer.squareup.com/reference/square_2021-12-15/objects/Invoice) object. Added a new `payment_conditions` field, which contains payment terms and conditions that are displayed on the invoice. This field is available only for sellers in France. For more information, see [Payment conditions.](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions) +- **Invoices API:** + + - The Invoices API now supports seller accounts in France. For more information, see [International availability and considerations.](https://developer.squareup.com/docs/invoices-api/overview#international-availability-invoices) + - France only: [`Invoice`](https://developer.squareup.com/reference/square_2021-12-15/objects/Invoice) object. Added a new `payment_conditions` field, which contains payment terms and conditions that are displayed on the invoice. This field is available only for sellers in France. For more information, see [Payment conditions.](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions) Square version 2021-12-15 or higher is required to set this field, but it is returned in `ListInvoices` and `RetrieveInvoice` requests for all Square versions. -* **Cards API** - * Added the `CARD_DECLINED_VERIFICATION_REQUIRED` error code to the list of error codes returned by [CreateCard](https://developer.squareup.com/reference/square_2021-12-15/cards-api/CreateCard). -* **Catalog API:** - * [CreateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/create-catalog-image) endpoint - * Updated to support attaching multiple images to a [Catalogbject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) instance. - * Added `is_primary` option to let the caller choose to attach an image as the primary image on the object for display with the Square Point of Sale and other first-party Square applications. For more information, see [Upload and Attach Images.](https://developer.squareup.com/docs/catalog-api/upload-and-attach-images) - * [CatalogObject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) object - * Retired the `image_id` field, used to hold a single image object attached to an image-supporting object of the `ITEM`, `ITEM_VARIATION`, `CATEGORY`, or `MODIFIER_LIST` type, in Square API version 2021-12-15 and later, which supports attachment of multiple images. The `image_id` field is still supported in Square API version prior to 2021-12-15. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview) - * [CatalogItem](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItem), [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItemVariation), [CatalogCategory](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogCategory) or [CatalogModifierList](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogModifierList) object - * Added `image_ids` list to hold attached image objects. The first element of `image_ids` list refers to the primary image attached to the catalog object. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview) - * [UpdateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/update-catalog-image) endpoint - * Added to support replacing the image file encapsulated by an existing [CatalogImage](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogImage) object. For more information, see [Replace image file on a CatalogImage object.](https://developer.squareup.com/docs/catalog-api/manage-images#replace-the-image-file-of-a-catalogimage-object) - - * [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule) object - * Added [minimum_order_subtotal_money](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule#definition__property-minimum_order_subtotal_money) field to require that the minimum order subtotal be reached before the pricing rule may be applied. +- **Cards API** + - Added the `CARD_DECLINED_VERIFICATION_REQUIRED` error code to the list of error codes returned by [CreateCard](https://developer.squareup.com/reference/square_2021-12-15/cards-api/CreateCard). +- **Catalog API:** + + - [CreateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/create-catalog-image) endpoint + - Updated to support attaching multiple images to a [Catalogbject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) instance. + - Added `is_primary` option to let the caller choose to attach an image as the primary image on the object for display with the Square Point of Sale and other first-party Square applications. For more information, see [Upload and Attach Images.](https://developer.squareup.com/docs/catalog-api/upload-and-attach-images) + - [CatalogObject](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogObject) object + - Retired the `image_id` field, used to hold a single image object attached to an image-supporting object of the `ITEM`, `ITEM_VARIATION`, `CATEGORY`, or `MODIFIER_LIST` type, in Square API version 2021-12-15 and later, which supports attachment of multiple images. The `image_id` field is still supported in Square API version prior to 2021-12-15. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview) + - [CatalogItem](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItem), [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogItemVariation), [CatalogCategory](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogCategory) or [CatalogModifierList](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogModifierList) object + - Added `image_ids` list to hold attached image objects. The first element of `image_ids` list refers to the primary image attached to the catalog object. For more information, see [Work with Images: Overview.](https://developer.squareup.com/docs/catalog-api/cookbook/create-catalog-image#overview) + - [UpdateCatalogImage](https://developer.squareup.com/reference/square_2021-12-15/catalog-api/update-catalog-image) endpoint + + - Added to support replacing the image file encapsulated by an existing [CatalogImage](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogImage) object. For more information, see [Replace image file on a CatalogImage object.](https://developer.squareup.com/docs/catalog-api/manage-images#replace-the-image-file-of-a-catalogimage-object) + + - [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule) object + - Added [minimum_order_subtotal_money](https://developer.squareup.com/reference/square_2021-12-15/objects/CatalogPricingRule#definition__property-minimum_order_subtotal_money) field to require that the minimum order subtotal be reached before the pricing rule may be applied. ### Documentation updates -* Added a new top-level node for Developer Tools. This node includes such features as Sandbox, API Logs, and Webhooks. -* Added [Webhook Event Logs (beta)](https://developer.squareup.com/docs/devtools/webhook-logs) documentation to the Developer Tools node. +- Added a new top-level node for Developer Tools. This node includes such features as Sandbox, API Logs, and Webhooks. +- Added [Webhook Event Logs (beta)](https://developer.squareup.com/docs/devtools/webhook-logs) documentation to the Developer Tools node. ## Version 16.0.1.20211117 (2021-11-29) + ## SDKs -* **Square Ruby SDK:** - * fix the issue to support Ruby `3.0.0`. + +- **Square Ruby SDK:** + - fix the issue to support Ruby `3.0.0`. ## Version 16.0.0.20211117 (2021-11-17) + ## API updates -* **Cards API.** The [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/card) object and webhook response body for all webhooks are updated updated with fields. - * Added the [Card.merchant_id](https://developer.squareup.com/reference/square_2021-11-17/objects/Card#definition__property-merchant_id) field to identify the Square seller that stored the payment card on file. - * Added a [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/Card) object to the response bodies of all [Cards API webhooks](https://developer.squareup.com/docs/webhooks/v2webhook-events-tech-ref#cards-api). The `Card` is added as a child of the `data.object` field in all webhook responses. +- **Cards API.** The [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/card) object and webhook response body for all webhooks are updated updated with fields. -* **Bookings API.** The new [ListBookings](https://developer.squareup.com/reference/square_2021-11-17/bookings-api/list-bookings) endpoint supports browsing a collection of bookings of a seller. For more information, see [Use the Bookings API: list bookings.](https://developer.squareup.com/docs/bookings-api/use-the-api#list-bookings) + - Added the [Card.merchant_id](https://developer.squareup.com/reference/square_2021-11-17/objects/Card#definition__property-merchant_id) field to identify the Square seller that stored the payment card on file. + - Added a [Card](https://developer.squareup.com/reference/square_2021-11-17/objects/Card) object to the response bodies of all [Cards API webhooks](https://developer.squareup.com/docs/webhooks/v2webhook-events-tech-ref#cards-api). The `Card` is added as a child of the `data.object` field in all webhook responses. -* **Subscriptions API.** Introduced the new [actions framework](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) representing scheduled, future changes to subscriptions. - * The new [PauseSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/pause-subscription) endpoint supports temporarily pausing a subscription. Calling this endpoint schedules a new `PAUSE` action. - * The new [SwapPlan](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/swap-plan) endpoint supports changing the subscription plan associated with a single customer. Calling this endpoint schedules a new `SWAP_PLAN` action. - * The new [DeleteSubscriptionAction](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/delete-subscription-action) endpoint supports deleting a scheduled action. - * The [ResumeSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/resume-subscription) endpoint has been updated to support resuming a paused subscription. Calling this endpoint schedules a new `RESUME` action. - * The [CancelSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/cancel-subscription) endpoint now schedules a new `CANCEL` action. - * Added an optional `include` body parameter to the [SearchSubscriptions](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/search-subscriptions) endpoint. Include `actions` in the request to return all [actions](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) associated with the subscriptions. +- **Bookings API.** The new [ListBookings](https://developer.squareup.com/reference/square_2021-11-17/bookings-api/list-bookings) endpoint supports browsing a collection of bookings of a seller. For more information, see [Use the Bookings API: list bookings.](https://developer.squareup.com/docs/bookings-api/use-the-api#list-bookings) + +- **Subscriptions API.** Introduced the new [actions framework](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) representing scheduled, future changes to subscriptions. + - The new [PauseSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/pause-subscription) endpoint supports temporarily pausing a subscription. Calling this endpoint schedules a new `PAUSE` action. + - The new [SwapPlan](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/swap-plan) endpoint supports changing the subscription plan associated with a single customer. Calling this endpoint schedules a new `SWAP_PLAN` action. + - The new [DeleteSubscriptionAction](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/delete-subscription-action) endpoint supports deleting a scheduled action. + - The [ResumeSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/resume-subscription) endpoint has been updated to support resuming a paused subscription. Calling this endpoint schedules a new `RESUME` action. + - The [CancelSubscription](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/cancel-subscription) endpoint now schedules a new `CANCEL` action. + - Added an optional `include` body parameter to the [SearchSubscriptions](https://developer.squareup.com/reference/square_2021-11-17/subscriptions-api/search-subscriptions) endpoint. Include `actions` in the request to return all [actions](https://developer.squareup.com/docs/subscriptions-api/overview#subscriptions-actions-overview) associated with the subscriptions. ## Documentation Update -* **Migration Guides.** - * [Migrate from the Connect V1 Refunds API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-refunds) The topic is updated to include information to migrate from the v1 ListRefunds endpoint to the appropriate Square API counterparts. - * [Migrate from the Connect V1 Payments API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-payments) The topic provides developers information to migrate from the Connect V1 Payments API to the appropriate Square API counterparts. +- **Migration Guides.** - Code that relies on these V1 API endpoints must be updated to avoid breaking when these APIs reach retirement. + - [Migrate from the Connect V1 Refunds API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-refunds) The topic is updated to include information to migrate from the v1 ListRefunds endpoint to the appropriate Square API counterparts. + - [Migrate from the Connect V1 Payments API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-payments) The topic provides developers information to migrate from the Connect V1 Payments API to the appropriate Square API counterparts. + Code that relies on these V1 API endpoints must be updated to avoid breaking when these APIs reach retirement. ## Version 15.0.0.20211020 (2021-10-20) + ## API updates -* **Transactions API.** Three previously deprecated endpoints (`ListRefunds`, `Charge`, and `CreateRefund`) in the [Transactions API](https://developer.squareup.com/reference/square_2021-10-20/transactions-api) are removed from Square API version 2021-10-20 and later. These endpoints will work if you are using Square API versions prior to 2021-10-20. However, these endpoints will eventually be retired from all Square versions. - * Instead of the Transactions API `Charge` endpoint, use the Payments API [CreatePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment) endpoint. - * Instead of the Transactions API `CreateRefund` endpoint, use the Refunds API [RefundPayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/refund-payment) endpoint. - * Instead of the Transactions API `ListRefunds` endpoint, use the Refunds API [ListPaymentRefund](https://developer.squareup.com/reference/square_2021-10-20/payments-api/list-payment-refunds) endpoint. +- **Transactions API.** Three previously deprecated endpoints (`ListRefunds`, `Charge`, and `CreateRefund`) in the [Transactions API](https://developer.squareup.com/reference/square_2021-10-20/transactions-api) are removed from Square API version 2021-10-20 and later. These endpoints will work if you are using Square API versions prior to 2021-10-20. However, these endpoints will eventually be retired from all Square versions. + + - Instead of the Transactions API `Charge` endpoint, use the Payments API [CreatePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment) endpoint. + - Instead of the Transactions API `CreateRefund` endpoint, use the Refunds API [RefundPayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/refund-payment) endpoint. + - Instead of the Transactions API `ListRefunds` endpoint, use the Refunds API [ListPaymentRefund](https://developer.squareup.com/reference/square_2021-10-20/payments-api/list-payment-refunds) endpoint. + +- **Payments API:** + + - [Payment](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment) object. + + - Added the [device_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-device_details) read-only field to view details of the device used to take a payment. This `Payment`-level field provides device information for all types of payments. Previously, device details were only available for card payments (`Payment.card_details.device_details`), which is now deprecated. + - Added the [team_member_id](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-team_member_id) that applications can use to view the ID of the [TeamMember](https://developer.squareup.com/reference/square_2021-10-20/objects/TeamMember) associated with the payment. Use this field instead of the `Payment.employee_id` field, which is now deprecated. + - Added the [application_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-application_details) read-only field to view details of the application that took the payment. + + - These `Payment` fields have moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle) (GA) state:[tip_money](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-tip_money), [delay_duration](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_duration), [statement_description_identifier](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-statement_description_identifier), [delay_duration](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_duration), [delay_action](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_action), [delayed_until](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delayed_until), and [statement_description_identifier](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-statement_description_identifier). + + - The [ACH Bank Transfer Payments](https://developer.squareup.com/docs/payments-api/take-payments/ach-payments) feature has moved to the GA state. Accordingly, the [bank_account_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-bank_account_details) field (and its [BankAccountPaymentDetails](https://developer.squareup.com/reference/square_2021-10-20/objects/BankAccountPaymentDetails) type) are moved to the GA state. -* **Payments API:** - * [Payment](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment) object. - * Added the [device_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-device_details) read-only field to view details of the device used to take a payment. This `Payment`-level field provides device information for all types of payments. Previously, device details were only available for card payments (`Payment.card_details.device_details`), which is now deprecated. - * Added the [team_member_id](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-team_member_id) that applications can use to view the ID of the [TeamMember](https://developer.squareup.com/reference/square_2021-10-20/objects/TeamMember) associated with the payment. Use this field instead of the `Payment.employee_id` field, which is now deprecated. - * Added the [application_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-application_details) read-only field to view details of the application that took the payment. + - [CreatePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment) endpoint. + - Added the [team_member_id](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment#request__property-team_member_id) request field to record the ID of the team member associated with the payment. + - The [accept_partial_authorization](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment#request__property-accept_partial_authorization) request field has moved to the GA state. + - [CompletePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/complete-payment) endpoint. Added the `version_token` request field to support optimistic concurrency. For more information, see [Delayed capture of a card payment.](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment) - * These `Payment` fields have moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle) (GA) state:[tip_money](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-tip_money), [delay_duration](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_duration), [statement_description_identifier](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-statement_description_identifier), [delay_duration](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_duration), [delay_action](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delay_action), [delayed_until](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-delayed_until), and [statement_description_identifier](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-statement_description_identifier). +- **Refunds API:** - * The [ACH Bank Transfer Payments](https://developer.squareup.com/docs/payments-api/take-payments/ach-payments) feature has moved to the GA state. Accordingly, the [bank_account_details](https://developer.squareup.com/reference/square_2021-10-20/objects/Payment#definition__property-bank_account_details) field (and its [BankAccountPaymentDetails](https://developer.squareup.com/reference/square_2021-10-20/objects/BankAccountPaymentDetails) type) are moved to the GA state. - * [CreatePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment) endpoint. - * Added the [team_member_id](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment#request__property-team_member_id) request field to record the ID of the team member associated with the payment. - * The [accept_partial_authorization](https://developer.squareup.com/reference/square_2021-10-20/payments-api/create-payment#request__property-accept_partial_authorization) request field has moved to the GA state. - * [CompletePayment](https://developer.squareup.com/reference/square_2021-10-20/payments-api/complete-payment) endpoint. Added the `version_token` request field to support optimistic concurrency. For more information, see [Delayed capture of a card payment.](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment) + - [RefundPayment](https://developer.squareup.com/reference/square_2021-10-20/refunds-api/refund-payment) endpoint. + - Added the `team_member_id` request field to record the ID of the team member associated with the refund. + - Added the `payment_version_token` request field to support optimistic concurrency. For more information, see [Refund Payment.](https://developer.squareup.com/docs/payments-api/refund-payments#optimistic-concurrency) -* **Refunds API:** - * [RefundPayment](https://developer.squareup.com/reference/square_2021-10-20/refunds-api/refund-payment) endpoint. - * Added the `team_member_id` request field to record the ID of the team member associated with the refund. - * Added the `payment_version_token` request field to support optimistic concurrency. For more information, see [Refund Payment.](https://developer.squareup.com/docs/payments-api/refund-payments#optimistic-concurrency) +- **Customers API:** -* **Customers API:** - * [Customer](https://developer.squareup.com/reference/square_2021-10-20/objects/Customer) object. Added a new `tax_ids` field of the [CustomerTaxIds](https://developer.squareup.com/reference/square_2021-10-20/objects/CustomerTaxIds) type, which can contain the EU VAT ID of the customer. This field is available only for customers of sellers in France, Ireland, or the United Kingdom. For more information, see [Customer tax IDs.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids) + - [Customer](https://developer.squareup.com/reference/square_2021-10-20/objects/Customer) object. Added a new `tax_ids` field of the [CustomerTaxIds](https://developer.squareup.com/reference/square_2021-10-20/objects/CustomerTaxIds) type, which can contain the EU VAT ID of the customer. This field is available only for customers of sellers in France, Ireland, or the United Kingdom. For more information, see [Customer tax IDs.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids) - * [UpdateCustomer](https://developer.squareup.com/reference/square_2021-10-20/customers-api/update-customer) endpoint. The Customers API now returns a `400 BAD_REQUEST` error if the request body does not contain any fields. For earlier Square versions, the Customers API will continue to return a `200 OK` response along with the customer profile. For more information, see [Migration notes.](https://developer.squareup.com/docs/customers-api/what-it-does#migration-notes) + - [UpdateCustomer](https://developer.squareup.com/reference/square_2021-10-20/customers-api/update-customer) endpoint. The Customers API now returns a `400 BAD_REQUEST` error if the request body does not contain any fields. For earlier Square versions, the Customers API will continue to return a `200 OK` response along with the customer profile. For more information, see [Migration notes.](https://developer.squareup.com/docs/customers-api/what-it-does#migration-notes) -* **Invoices API:** - * [InvoiceRecipient](https://developer.squareup.com/reference/square_2021-10-20/objects/InvoiceRecipient) object. Added a new, read-only `tax_ids` field of the [InvoiceRecipientTaxIds](https://developer.squareup.com/reference/square_2021-10-20/objects/InvoiceRecipientTaxIds) type, which can contain the EU VAT ID of the invoice recipient. This field is available only for customers of sellers in Ireland or the United Kingdom. If defined, `tax_ids` is returned for all Square API versions. For more information, see [Invoice recipient tax IDs.](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids) - * Square now sends emails for test invoices that are published in the Sandbox environment. +- **Invoices API:** -* **Catalog API:** - * [CatalogSubscriptionPlan.name](https://developer.squareup.com/reference/square_2021-10-20/objects/CatalogSubscriptionPlan#definition__property-name) can be updated after the subscription plan is created. The change is retroactively applicable to prior versions of the Square API. + - [InvoiceRecipient](https://developer.squareup.com/reference/square_2021-10-20/objects/InvoiceRecipient) object. Added a new, read-only `tax_ids` field of the [InvoiceRecipientTaxIds](https://developer.squareup.com/reference/square_2021-10-20/objects/InvoiceRecipientTaxIds) type, which can contain the EU VAT ID of the invoice recipient. This field is available only for customers of sellers in Ireland or the United Kingdom. If defined, `tax_ids` is returned for all Square API versions. For more information, see [Invoice recipient tax IDs.](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids) + - Square now sends emails for test invoices that are published in the Sandbox environment. -* **Subscriptions API:** - * The new [SubscriptionSource](https://developer.squareup.com/reference/square_2021-10-20/objects/SubscriptionSource) data type is introduced to encapsulate the source where a subscription is created. The new `SubscriptionSource.name` value is propagated to the `Order.source` attribute when an order is made on the subscription. The new feature is retroactively applicable to prior versions of the Square API. - * The new [Subscription.source](https://developer.squareup.com/reference/square_2021-10-20/objects/Subscription#definition__property-source) attribute is introduced to indicate the source where the subscription was created. This new feature is retroactively applicable to prior versions of the Square API. - * The new [SearchSubscriptionsFilter.source_names](https://developer.squareup.com/reference/square_2021-10-20/objects/SearchSubscriptionFilter#definition__property-source_names) query expression is introduced to enable search for subscriptions by the subscription source name. This new feature is retroactively applicable to prior versions of the Square API. - +- **Catalog API:** + + - [CatalogSubscriptionPlan.name](https://developer.squareup.com/reference/square_2021-10-20/objects/CatalogSubscriptionPlan#definition__property-name) can be updated after the subscription plan is created. The change is retroactively applicable to prior versions of the Square API. + +- **Subscriptions API:** + - The new [SubscriptionSource](https://developer.squareup.com/reference/square_2021-10-20/objects/SubscriptionSource) data type is introduced to encapsulate the source where a subscription is created. The new `SubscriptionSource.name` value is propagated to the `Order.source` attribute when an order is made on the subscription. The new feature is retroactively applicable to prior versions of the Square API. + - The new [Subscription.source](https://developer.squareup.com/reference/square_2021-10-20/objects/Subscription#definition__property-source) attribute is introduced to indicate the source where the subscription was created. This new feature is retroactively applicable to prior versions of the Square API. + - The new [SearchSubscriptionsFilter.source_names](https://developer.squareup.com/reference/square_2021-10-20/objects/SearchSubscriptionFilter#definition__property-source_names) query expression is introduced to enable search for subscriptions by the subscription source name. This new feature is retroactively applicable to prior versions of the Square API. ## Version 14.1.0.20210915 (2021-09-15) + ## API updates -* **Invoices API:** - * [Invoice](https://developer.squareup.com/reference/square_2021-09-15/objects/Invoice) object. Added a new, optional `sale_or_service_date` field used to specify the date of the sale or the date that the service is rendered. If specified, this date is displayed on the invoice. +- **Invoices API:** + + - [Invoice](https://developer.squareup.com/reference/square_2021-09-15/objects/Invoice) object. Added a new, optional `sale_or_service_date` field used to specify the date of the sale or the date that the service is rendered. If specified, this date is displayed on the invoice. + +- **Orders API:** -* **Orders API:** - * [CreateOrder](https://developer.squareup.com/reference/square_2021-09-15/orders-api/create-order). The endpoint now supports creating temporary, draft orders. For more information, see [Create a draft order.](https://developer.squareup.com/docs/orders-api/create-orders#create-a-draft-order) - * [CloneOrder](https://developer.squareup.com/reference/square_2021-09-15/orders-api/clone-order). The Orders API supports this new endpoint to clone an existing order. For more information, see [Clone an order.](https://developer.squareup.com/docs/orders-api/create-orders#clone-an-order) - * These fields have moved to the [general availability (GA)](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) state: [OrderLineItem.item_type](https://developer.squareup.com/reference/square_2021-09-15/objects/OrderLineItem#definition__property-item_type), [OrderServiceCharge.type](https://developer.squareup.com/reference/square_2021-09-15/objects/OrderServiceCharge#definition__property-type), and `catalog_version` field on every order type that contains this field. + - [CreateOrder](https://developer.squareup.com/reference/square_2021-09-15/orders-api/create-order). The endpoint now supports creating temporary, draft orders. For more information, see [Create a draft order.](https://developer.squareup.com/docs/orders-api/create-orders#create-a-draft-order) + - [CloneOrder](https://developer.squareup.com/reference/square_2021-09-15/orders-api/clone-order). The Orders API supports this new endpoint to clone an existing order. For more information, see [Clone an order.](https://developer.squareup.com/docs/orders-api/create-orders#clone-an-order) + - These fields have moved to the [general availability (GA)](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) state: [OrderLineItem.item_type](https://developer.squareup.com/reference/square_2021-09-15/objects/OrderLineItem#definition__property-item_type), [OrderServiceCharge.type](https://developer.squareup.com/reference/square_2021-09-15/objects/OrderServiceCharge#definition__property-type), and `catalog_version` field on every order type that contains this field. -* **Team API:** - * [SearchTeamMembersFilter](https://developer.squareup.com/reference/square_2021-09-15/objects/SearchTeamMembersFilter) object now has an `is_owner` field that when set, causes a team member search to return only the seller who owns a Square account. +- **Team API:** -* **Terminal API:** - * [TerminalCheckout](https://developer.squareup.com/reference/square_2021-09-15/objects/TerminalCheckout) object. The `customer_id` field is now GA. + - [SearchTeamMembersFilter](https://developer.squareup.com/reference/square_2021-09-15/objects/SearchTeamMembersFilter) object now has an `is_owner` field that when set, causes a team member search to return only the seller who owns a Square account. + +- **Terminal API:** + - [TerminalCheckout](https://developer.squareup.com/reference/square_2021-09-15/objects/TerminalCheckout) object. The `customer_id` field is now GA. ## Documentation updates -* **OAuth API:** - * Revised API descriptions for the ObtainToken and Authorize endpoints. Clarified that the Authorize endpoint is not a callable API but is used to direct the seller to the Square authorization page. For more information about the Authorize endpoint, see [Create the Redirect URL and Square Authorization Page URL.](https://developer.squareup.com/docs/oauth-api/create-urls-for-square-authorization) +- **OAuth API:** + - Revised API descriptions for the ObtainToken and Authorize endpoints. Clarified that the Authorize endpoint is not a callable API but is used to direct the seller to the Square authorization page. For more information about the Authorize endpoint, see [Create the Redirect URL and Square Authorization Page URL.](https://developer.squareup.com/docs/oauth-api/create-urls-for-square-authorization) ## Version 13.1.0.20210818 (2021-08-18) -## API updates -* **Customers API:** - * [Customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) object. The `version` field has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. This field represents the current version of the customer profile and enables optimistic concurrency control. For more information, see [Customer profile versions and optimistic concurrency support.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-profile-versions-and-optimistic-concurrency-support) - * [ListCustomers](https://developer.squareup.com/reference/square_2021-08-18/customers-api/list-customers) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response. +## API updates + +- **Customers API:** + + - [Customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) object. The `version` field has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. This field represents the current version of the customer profile and enables optimistic concurrency control. For more information, see [Customer profile versions and optimistic concurrency support.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-profile-versions-and-optimistic-concurrency-support) + - [ListCustomers](https://developer.squareup.com/reference/square_2021-08-18/customers-api/list-customers) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response. + +- **Customer Groups API:** -* **Customer Groups API:** - * [ListCustomerGroups](https://developer.squareup.com/reference/square_2021-08-18/customer-groups-api/list-customer-groups) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response. + - [ListCustomerGroups](https://developer.squareup.com/reference/square_2021-08-18/customer-groups-api/list-customer-groups) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response. -* **Customer Segments API:** - * [ListCustomerSegments](https://developer.squareup.com/reference/square_2021-08-18/customer-segments-api/list-customer-segments) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response. +- **Customer Segments API:** -* **Invoices API:** - * Square Invoices Plus is a monthly subscription plan that allows access to premium invoice features. After Invoices Plus is launched in September 2021, a subscription will be required to create invoices with custom fields and installment payments. For more information, including how to handle new errors, see [Premium features available with Invoices Plus.](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription) + - [ListCustomerSegments](https://developer.squareup.com/reference/square_2021-08-18/customer-segments-api/list-customer-segments) endpoint. The new, optional `limit` query parameter can be used to specify the maximum number of results in a paginated response. -* **Loyalty API:** - * [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccount) object. Added a new `expiring_point_deadlines` field that specifies when points in the account balance are scheduled to expire. This field contains a list of [LoyaltyAccountExpiringPointDeadline](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccountExpiringPointDeadline) objects. For more information, see [Expiring points.](https://developer.squareup.com/docs/loyalty-api/overview#expiring-points) +- **Invoices API:** + + - Square Invoices Plus is a monthly subscription plan that allows access to premium invoice features. After Invoices Plus is launched in September 2021, a subscription will be required to create invoices with custom fields and installment payments. For more information, including how to handle new errors, see [Premium features available with Invoices Plus.](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription) + +- **Loyalty API:** + - [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccount) object. Added a new `expiring_point_deadlines` field that specifies when points in the account balance are scheduled to expire. This field contains a list of [LoyaltyAccountExpiringPointDeadline](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyAccountExpiringPointDeadline) objects. For more information, see [Expiring points.](https://developer.squareup.com/docs/loyalty-api/overview#expiring-points) ## Documentation updates -* [App Marketplace.](https://developer.squareup.com/docs/app-marketplace) Added the following topics: - * [How to apply.](https://developer.squareup.com/docs/app-marketplace#how-to-apply) Documented the process to list an application on the Square App Marketplace. - * [App Marketplace API Usage Requirements.](https://developer.squareup.com/docs/app-marketplace/requirements) Added a topic that describes a set of API usage requirements and recommendations for partner applications. +- [App Marketplace.](https://developer.squareup.com/docs/app-marketplace) Added the following topics: -* [Automatic communications from Square about invoices.](https://developer.squareup.com/docs/invoices-api/overview#automatic-communication-from-square-to-customers) Documented the invoice-related communications sent from Square to customers and sellers. + - [How to apply.](https://developer.squareup.com/docs/app-marketplace#how-to-apply) Documented the process to list an application on the Square App Marketplace. + - [App Marketplace API Usage Requirements.](https://developer.squareup.com/docs/app-marketplace/requirements) Added a topic that describes a set of API usage requirements and recommendations for partner applications. -* [Snippets best practices.](https://developer.squareup.com/docs/snippets-api/overview#best-practices) Documented best practices and additional requirements for snippets and applications that integrate with the Snippets API. +- [Automatic communications from Square about invoices.](https://developer.squareup.com/docs/invoices-api/overview#automatic-communication-from-square-to-customers) Documented the invoice-related communications sent from Square to customers and sellers. +- [Snippets best practices.](https://developer.squareup.com/docs/snippets-api/overview#best-practices) Documented best practices and additional requirements for snippets and applications that integrate with the Snippets API. ## Version 13.0.0.20210721 (2021-07-21) + ## API updates -* **Orders API:** - * [OrderServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderServiceCharge) object. Added a new field, `type`. It identifies the service charge type. - - * [OrderQuantityUnit](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderQuantityUnit), - [OrderLineItem](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItem), - [OrderLineItemDiscount](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemDiscount), - [OrderLineItemModifier](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemModifier), - [OrderLineItemTax](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemTax), - [OrderServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderServiceCharge), - [OrderReturnLineItem](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnLineItem), - [OrderReturnLineItemModifier](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnLineItemModifier), - [OrderReturnServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnServiceCharge), - [OrderReturnTax](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnTax), and +- **Orders API:** + + - [OrderServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderServiceCharge) object. Added a new field, `type`. It identifies the service charge type. + + - [OrderQuantityUnit](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderQuantityUnit), + [OrderLineItem](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItem), + [OrderLineItemDiscount](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemDiscount), + [OrderLineItemModifier](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemModifier), + [OrderLineItemTax](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderLineItemTax), + [OrderServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderServiceCharge), + [OrderReturnLineItem](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnLineItem), + [OrderReturnLineItemModifier](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnLineItemModifier), + [OrderReturnServiceCharge](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnServiceCharge), + [OrderReturnTax](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnTax), and [OrderReturnDiscount](https://developer.squareup.com/reference/square_2021-07-21/objects/OrderReturnDiscount) objects. Added a new field, `catalog_version`. -* **Locations API:** - * [Location](https://developer.squareup.com/reference/square_2021-07-21/objects/Location) object. Added a new field `tax_ids` of type `TaxIds`. In the current implementation, sellers in Ireland and France can configure tax IDs during the onboarding process. They can also provide the information later by updating the location information in the Seller Dashboard. These tax IDs appear in this field. -* **Loyalty API:** - * As of July 15, 2021, the country in which the seller’s Square account is activated determines whether Square uses pretax or post-tax purchase amounts to calculate accrued points. This change supports consumption tax models, such as value-added tax (VAT). Previously, point accrual was based on pretax purchase amounts only. This change does not affect the existing point balance of loyalty accounts. For more information, see [Availability of Square Loyalty.](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-market-availability) +- **Locations API:** + + - [Location](https://developer.squareup.com/reference/square_2021-07-21/objects/Location) object. Added a new field `tax_ids` of type `TaxIds`. In the current implementation, sellers in Ireland and France can configure tax IDs during the onboarding process. They can also provide the information later by updating the location information in the Seller Dashboard. These tax IDs appear in this field. + +- **Loyalty API:** + + - As of July 15, 2021, the country in which the seller’s Square account is activated determines whether Square uses pretax or post-tax purchase amounts to calculate accrued points. This change supports consumption tax models, such as value-added tax (VAT). Previously, point accrual was based on pretax purchase amounts only. This change does not affect the existing point balance of loyalty accounts. For more information, see [Availability of Square Loyalty.](https://developer.squareup.com/docs/loyalty-api/overview#loyalty-market-availability) + +- **Payments API:** + + - [UpdatePayment](https://developer.squareup.com/reference/square_2021-07-21/payments-api/update-payment). The endpoint has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. Also, you can now update gift card payments (similar to card, cash, and external payments). -* **Payments API:** - * [UpdatePayment](https://developer.squareup.com/reference/square_2021-07-21/payments-api/update-payment). The endpoint has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. Also, you can now update gift card payments (similar to card, cash, and external payments). +- **Subscriptions API:** -* **Subscriptions API:** - * The [Subscriptions API](https://developer.squareup.com/docs/subscriptions-api/overview) has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. - * [CatalogSubscriptionPlan](https://developer.squareup.com/reference/square_2021-07-21/objects/CatalogSubscriptionPlan) object. The `name` and `price` are now write-once fields. You specify these values at the time of creating a plan. After the plan is created, these fields cannot be updated. This makes a subscription plan immutable. + - The [Subscriptions API](https://developer.squareup.com/docs/subscriptions-api/overview) has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. + - [CatalogSubscriptionPlan](https://developer.squareup.com/reference/square_2021-07-21/objects/CatalogSubscriptionPlan) object. The `name` and `price` are now write-once fields. You specify these values at the time of creating a plan. After the plan is created, these fields cannot be updated. This makes a subscription plan immutable. -* **Inventory API:** - * [RetrieveInventoryTransfer.](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Transfer) This new endpoint is introduced to support the retrieval of inventory transfer. - * [RetrieveInventoryChanges.](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Changes) This endpoint is deprecated. Its support ends when it is retired in about 12 months. - * The following endpoints have updated URLs to conform to the standard REST API convention. For more information about migrating deprecated URLs to updated URLs in your application, see [Inventory API: Migrate to Updated API Entities.](https://developer.squareup.com/docs/inventory-api/migrate-to-updated-api-entities) - * [RetrieveInventoryAdjustment](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Adjustment) - * [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Change-Inventory) - * [BatchRetrieveInventoryChanges](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Retrieve-Inventory-Changes) - * [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Retrieve-Inventory-Counts) - * [RetrieveInventoryPhysicalCount](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Physical-Count) +- **Inventory API:** + - [RetrieveInventoryTransfer.](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Transfer) This new endpoint is introduced to support the retrieval of inventory transfer. + - [RetrieveInventoryChanges.](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Changes) This endpoint is deprecated. Its support ends when it is retired in about 12 months. + - The following endpoints have updated URLs to conform to the standard REST API convention. For more information about migrating deprecated URLs to updated URLs in your application, see [Inventory API: Migrate to Updated API Entities.](https://developer.squareup.com/docs/inventory-api/migrate-to-updated-api-entities) + - [RetrieveInventoryAdjustment](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Adjustment) + - [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Change-Inventory) + - [BatchRetrieveInventoryChanges](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Retrieve-Inventory-Changes) + - [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Batch-Retrieve-Inventory-Counts) + - [RetrieveInventoryPhysicalCount](https://developer.squareup.com/reference/square_2021-07-21/inventory-api/Retrieve-Inventory-Physical-Count) ## Documentation updates -* **Webhooks.** Revised the steps and descriptions for creating and using webhooks. For more information, see [Webhooks Overview.](https://developer.squareup.com/docs/webhooks/overview) +- **Webhooks.** Revised the steps and descriptions for creating and using webhooks. For more information, see [Webhooks Overview.](https://developer.squareup.com/docs/webhooks/overview) ## Version 12.0.0.20210616 (2021-06-16) + ## New API releases -* **Gift Cards API and Gift Card Activities API.** Gift card support is integrated in the [Square Seller Dashboard](https://squareup.com/dashboard/) and the [Square Point of Sale](https://squareup.com/us/en/point-of-sale) application. Sellers can sell, redeem, track, and reload Square gift cards. Now developers can use the [Gift Cards API](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api) and the [Gift Card Activities API](https://developer.squareup.com/reference/square_2021-06-16/gift-card-activities-api) to integrate Square gift cards into third-party applications. For more information, see [Gift Cards API Overview.](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api) -* **Cards API.** The [Cards API](https://developer.squareup.com/reference/square_2021-06-16/cards-api) replaces the deprecated `CreateCustomerCard` and `DeleteCustomerCard` endpoints and lets an application save a customer payment card on file along with other card management operations. For more information, see [Cards API Overview.](https://developer.squareup.com/docs/cards-api/overview) +- **Gift Cards API and Gift Card Activities API.** Gift card support is integrated in the [Square Seller Dashboard](https://squareup.com/dashboard/) and the [Square Point of Sale](https://squareup.com/us/en/point-of-sale) application. Sellers can sell, redeem, track, and reload Square gift cards. Now developers can use the [Gift Cards API](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api) and the [Gift Card Activities API](https://developer.squareup.com/reference/square_2021-06-16/gift-card-activities-api) to integrate Square gift cards into third-party applications. For more information, see [Gift Cards API Overview.](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api) + +- **Cards API.** The [Cards API](https://developer.squareup.com/reference/square_2021-06-16/cards-api) replaces the deprecated `CreateCustomerCard` and `DeleteCustomerCard` endpoints and lets an application save a customer payment card on file along with other card management operations. For more information, see [Cards API Overview.](https://developer.squareup.com/docs/cards-api/overview) ## API updates -* **Catalog API:** - * [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogPricingRule). Support of the [customer group discount](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogPricingRule#definition__property-customer_group_ids_any) becomes GA. For more information, see [CreateCustomerGroupDiscounts.](https://developer.squareup.com/docs/catalog-api/configure-customer-group-discounts) - * [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogItemVariation). Offers Beta support of the [stockable](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogItemVariation#definition__property-stockable) and [stockable_conversion](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogItemVariation#definition__property-stockable_conversion) attributes to enable sales of a product in multiple measurement units. - * [UpsertCatalogObject](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/upsert-catalog-object) and [BatchUpsertCatalogObjects](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/batch-upsert-catalog-objects). Support creating an item with stockable and non-stockable variations with a specified stock conversion between the two. For more information, see [Enable Stock Conversion.](https://developer.squareup.com/docs/inventory-api/enable-stock-conversion) - * [UpsertCatalogObject](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/upsert-catalog-object) and [BatchUpsertCatalogObjects](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/batch-upsert-catalog-objects). Require that an item be created with at least one variation. Otherwise, an `INVALID_REQUEST` error is returned. - -* **Customers API:** - * Using the Customers API to manage cards on file is deprecated: - * The [CreateCustomerCard](https://developer.squareup.com/reference/square_2021-06-16/customers-api/create-customer-card) endpoint is deprecated and replaced by the [CreateCard](https://developer.squareup.com/reference/square_2021-06-16/cards-api/create-card) and [LinkCustomerToGiftCard](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api/link-customer-to-gift-card) endpoints. - * The [DeleteCustomerCard](https://developer.squareup.com/reference/square_2021-06-16/customers-api/delete-customer-card) endpoint is deprecated and replaced by the [DisableCard](https://developer.squareup.com/reference/square_2021-06-16/cards-api/disable-card) and [UnlinkCustomerFromGiftCard](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api/unlink-customer-from-gift-card) endpoints. - * The `cards` field in the [Customer](https://developer.squareup.com/reference/square_2021-06-16/objects/Customer) object is deprecated and replaced by the following endpoints: - * [ListCards](https://developer.squareup.com/reference/square_2021-06-16/cards-api/list-cards) to retrieve credit and debit cards on file. - * [ListGiftCards](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api/list-gift-cards) to retrieve gift cards on file. - - For more information, see [Migrate to the Cards API and Gift Cards API.](https://developer.squareup.com/docs/customers-api/use-the-api/integrate-with-other-services#migrate-customer-cards) - - * [Customer](https://developer.squareup.com/reference/square_2021-06-16/objects/Customer) object. In the `cards` field, the IDs for gift cards now have a `gftc:` prefix followed by the card number. This is a service-level change that applies to all Square API versions. - -* **Disputes API:** - * The Disputes API is now GA. - * `RemoveDisputeEvidence`. Renamed to [DeleteDisputeEvidence](https://developer.squareup.com/reference/square_2021-06-16/objects/DeleteDisputeEvidence). - * [CreateDisputeEvidenceFile.](https://developer.squareup.com/reference/square_2021-06-16/objects/CreateDisputeEvidenceFile) The URL is changed from `/v2/disputes/{dispute_id}/evidence_file` to `/v2/disputes/{dispute_id}/evidence-files`. - * [CreateDisputeEvidenceText.](https://developer.squareup.com/reference/square_2021-06-16/objects/CreateDisputeEvidenceText) The URL is changed from `/v2/disputes/{dispute_id}/evidence_text` to `/v2/disputes/{dispute_id}/evidence-text`. - * [ListDisputeEvidence.](https://developer.squareup.com/reference/square_2021-06-16/objects/ListDisputeEvidence) The endpoint now returns a pagination cursor and accepts a pagination cursor in requests. - * `DISPUTES_READ` and `DISPUTES_WRITE` permissions are required for all Disputes API endpoints instead of `PAYMENTS_READ` and `PAYMENTS_WRITE`. - * [DisputeEvidence.](https://developer.squareup.com/reference/square_2021-06-16/objects/DisputeEvidence) The `evidence_id` field is deprecated and replaced by the `id` field. - * The `dispute.state.changed` webhook is renamed to `dispute.state.updated`. - * [Dispute](https://developer.squareup.com/reference/square_2021-06-16/objects/Dispute) object. The following breaking changes are made: - * The `dispute_id` field is deprecated and replaced by the `id` field. - * The `reported_date` field is deprecated and replaced by the `reported_at` field. - * The `evidence_ids` field is deprecated with no replacement. - - For more information about the GA release of the Disputes API, see [Disputes Overview.](https://developer.squareup.com/docs/disputes-api/overview) - - -* **Inventory API:** - * [CatalogStockConversion](https://developer.squareup.com/docs/{SQUARE_TECH_REF}/objects/CatalogStockConversion) (Beta). Enables selling a product in multiple measurement units and lets Square sellers manage inventory counts of the product's stockable and a non-stockable variations in a self-consistent manner. For more information, see [Enable Stock Conversion.](https://developer.squareup.com/docs/inventory-api/enable-stock-conversion) - -* **Invoices API:** - * [CreateInvoice.](https://developer.squareup.com/reference/square_2021-06-16/invoices-api/create-invoice) The `location_id` field is now optional and defaults to the location ID of the associated order. If specified in the request, the value must match the location ID of the associated order. This is a service-level change that applies to all Square API versions. - -* **Loyalty API:** - * [LoyaltyProgramAccrualRule](https://developer.squareup.com/reference/square_2021-06-16/objects/LoyaltyProgramAccrualRule) object. New `excluded_category_ids` and `excluded_item_variation_ids` fields that represent any categories and items that are excluded from accruing points in spend-based loyalty programs. - -* **Subscriptions API:** - * [Subscription.](https://developer.squareup.com/reference/square_2021-06-16/objects/Subscription) The `paid_until_date` field is renamed to `charge_through_date`. - * [UpdateSubscription.](https://developer.squareup.com/reference/square_2021-06-16/subscriptions-api/update-subscription) The `version` field is now optional because it can update only the latest version of a subscription. - - * [CreateSubscription.](https://developer.squareup.com/reference/square_2021-06-16/subscriptions-api/create-subscription) The `idempotency_key` field is now optional in the request. If you do not provide it, each `CreateSubscription` assumes a unique (never used before) value and creates a subscription for each call. + +- **Catalog API:** + - [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogPricingRule). Support of the [customer group discount](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogPricingRule#definition__property-customer_group_ids_any) becomes GA. For more information, see [CreateCustomerGroupDiscounts.](https://developer.squareup.com/docs/catalog-api/configure-customer-group-discounts) + - [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogItemVariation). Offers Beta support of the [stockable](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogItemVariation#definition__property-stockable) and [stockable_conversion](https://developer.squareup.com/reference/square_2021-06-16/objects/CatalogItemVariation#definition__property-stockable_conversion) attributes to enable sales of a product in multiple measurement units. + - [UpsertCatalogObject](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/upsert-catalog-object) and [BatchUpsertCatalogObjects](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/batch-upsert-catalog-objects). Support creating an item with stockable and non-stockable variations with a specified stock conversion between the two. For more information, see [Enable Stock Conversion.](https://developer.squareup.com/docs/inventory-api/enable-stock-conversion) + - [UpsertCatalogObject](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/upsert-catalog-object) and [BatchUpsertCatalogObjects](https://developer.squareup.com/reference/square_2021-06-16/catalog-api/batch-upsert-catalog-objects). Require that an item be created with at least one variation. Otherwise, an `INVALID_REQUEST` error is returned. +- **Customers API:** + + - Using the Customers API to manage cards on file is deprecated: + + - The [CreateCustomerCard](https://developer.squareup.com/reference/square_2021-06-16/customers-api/create-customer-card) endpoint is deprecated and replaced by the [CreateCard](https://developer.squareup.com/reference/square_2021-06-16/cards-api/create-card) and [LinkCustomerToGiftCard](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api/link-customer-to-gift-card) endpoints. + - The [DeleteCustomerCard](https://developer.squareup.com/reference/square_2021-06-16/customers-api/delete-customer-card) endpoint is deprecated and replaced by the [DisableCard](https://developer.squareup.com/reference/square_2021-06-16/cards-api/disable-card) and [UnlinkCustomerFromGiftCard](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api/unlink-customer-from-gift-card) endpoints. + - The `cards` field in the [Customer](https://developer.squareup.com/reference/square_2021-06-16/objects/Customer) object is deprecated and replaced by the following endpoints: + + - [ListCards](https://developer.squareup.com/reference/square_2021-06-16/cards-api/list-cards) to retrieve credit and debit cards on file. + - [ListGiftCards](https://developer.squareup.com/reference/square_2021-06-16/gift-cards-api/list-gift-cards) to retrieve gift cards on file. + + For more information, see [Migrate to the Cards API and Gift Cards API.](https://developer.squareup.com/docs/customers-api/use-the-api/integrate-with-other-services#migrate-customer-cards) + + - [Customer](https://developer.squareup.com/reference/square_2021-06-16/objects/Customer) object. In the `cards` field, the IDs for gift cards now have a `gftc:` prefix followed by the card number. This is a service-level change that applies to all Square API versions. + +- **Disputes API:** + + - The Disputes API is now GA. + - `RemoveDisputeEvidence`. Renamed to [DeleteDisputeEvidence](https://developer.squareup.com/reference/square_2021-06-16/objects/DeleteDisputeEvidence). + - [CreateDisputeEvidenceFile.](https://developer.squareup.com/reference/square_2021-06-16/objects/CreateDisputeEvidenceFile) The URL is changed from `/v2/disputes/{dispute_id}/evidence_file` to `/v2/disputes/{dispute_id}/evidence-files`. + - [CreateDisputeEvidenceText.](https://developer.squareup.com/reference/square_2021-06-16/objects/CreateDisputeEvidenceText) The URL is changed from `/v2/disputes/{dispute_id}/evidence_text` to `/v2/disputes/{dispute_id}/evidence-text`. + - [ListDisputeEvidence.](https://developer.squareup.com/reference/square_2021-06-16/objects/ListDisputeEvidence) The endpoint now returns a pagination cursor and accepts a pagination cursor in requests. + - `DISPUTES_READ` and `DISPUTES_WRITE` permissions are required for all Disputes API endpoints instead of `PAYMENTS_READ` and `PAYMENTS_WRITE`. + - [DisputeEvidence.](https://developer.squareup.com/reference/square_2021-06-16/objects/DisputeEvidence) The `evidence_id` field is deprecated and replaced by the `id` field. + - The `dispute.state.changed` webhook is renamed to `dispute.state.updated`. + - [Dispute](https://developer.squareup.com/reference/square_2021-06-16/objects/Dispute) object. The following breaking changes are made: + - The `dispute_id` field is deprecated and replaced by the `id` field. + - The `reported_date` field is deprecated and replaced by the `reported_at` field. + - The `evidence_ids` field is deprecated with no replacement. + + For more information about the GA release of the Disputes API, see [Disputes Overview.](https://developer.squareup.com/docs/disputes-api/overview) + +- **Inventory API:** + + - [CatalogStockConversion](https://developer.squareup.com/docs/{SQUARE_TECH_REF}/objects/CatalogStockConversion) (Beta). Enables selling a product in multiple measurement units and lets Square sellers manage inventory counts of the product's stockable and a non-stockable variations in a self-consistent manner. For more information, see [Enable Stock Conversion.](https://developer.squareup.com/docs/inventory-api/enable-stock-conversion) + +- **Invoices API:** + + - [CreateInvoice.](https://developer.squareup.com/reference/square_2021-06-16/invoices-api/create-invoice) The `location_id` field is now optional and defaults to the location ID of the associated order. If specified in the request, the value must match the location ID of the associated order. This is a service-level change that applies to all Square API versions. + +- **Loyalty API:** + + - [LoyaltyProgramAccrualRule](https://developer.squareup.com/reference/square_2021-06-16/objects/LoyaltyProgramAccrualRule) object. New `excluded_category_ids` and `excluded_item_variation_ids` fields that represent any categories and items that are excluded from accruing points in spend-based loyalty programs. + +- **Subscriptions API:** + + - [Subscription.](https://developer.squareup.com/reference/square_2021-06-16/objects/Subscription) The `paid_until_date` field is renamed to `charge_through_date`. + - [UpdateSubscription.](https://developer.squareup.com/reference/square_2021-06-16/subscriptions-api/update-subscription) The `version` field is now optional because it can update only the latest version of a subscription. + + - [CreateSubscription.](https://developer.squareup.com/reference/square_2021-06-16/subscriptions-api/create-subscription) The `idempotency_key` field is now optional in the request. If you do not provide it, each `CreateSubscription` assumes a unique (never used before) value and creates a subscription for each call. ## Documentation updates -* [Order fee structure.](https://developer.squareup.com/docs/payments-pricing#orders-api-fee-structure) Documented the transaction fee related to using the Orders API with a non-Square payments provider. +- [Order fee structure.](https://developer.squareup.com/docs/payments-pricing#orders-api-fee-structure) Documented the transaction fee related to using the Orders API with a non-Square payments provider. ## Version 11.0.0.20210513 (2021-05-13) -## New API releases -* **Sites API.** The [Sites API](https://developer.squareup.com/reference/square_2021-05-13/sites-api) lets you retrieve basic details about the Square Online sites that belong to a Square seller. For more information, see [Sites API Overview.](https://developer.squareup.com/docs/sites-api/overview) +## New API releases +- **Sites API.** The [Sites API](https://developer.squareup.com/reference/square_2021-05-13/sites-api) lets you retrieve basic details about the Square Online sites that belong to a Square seller. For more information, see [Sites API Overview.](https://developer.squareup.com/docs/sites-api/overview) -* **Snippets API.** The [Snippets API](https://developer.squareup.com/reference/square_2021-05-13/snippets-api) lets you manage snippets that provide custom functionality on Square Online sites. A snippet is a script that is injected into all pages on a site, except for checkout pages. For more information, see [Snippets API Overview.](https://developer.squareup.com/docs/snippets-api/overview) +- **Snippets API.** The [Snippets API](https://developer.squareup.com/reference/square_2021-05-13/snippets-api) lets you manage snippets that provide custom functionality on Square Online sites. A snippet is a script that is injected into all pages on a site, except for checkout pages. For more information, see [Snippets API Overview.](https://developer.squareup.com/docs/snippets-api/overview) The Sites API and Snippets API are publicly available to all developers as part of an early access program (EAP). For more information, see [Early access program for Square Online APIs.](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis) ## API updates -* **Payments API.** - * [CreatePayment.](https://developer.squareup.com/reference/square_2021-05-13/payments-api/create-payment) The endpoint now supports ACH bank transfer payments. For more information, see [ACH Payment](https://developer.squareup.com/docs/payments-api/take-payments/ach-payments). - -* **Loyalty API:** - * The [Loyalty API](https://developer.squareup.com/docs/loyalty-api/overview) has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. - - * The [ListLoyaltyPrograms](https://developer.squareup.com/reference/square_2021-05-13/loyalty-api/list-loyalty-programs) endpoint is deprecated and replaced by the [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2021-05-13/loyalty-api/retrieve-loyalty-program) endpoint when used with the `main` keyword. - - * [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-05-13/objects/LoyaltyAccount)  object. The `mappings` field is retired and replaced by `mapping`. - - * [LoyaltyAccountMapping](https://developer.squareup.com/reference/square_2021-05-13/objects/LoyaltyAccountMapping) object. The `type` and `value` fields are retired and replaced by `phone_number`. - - Starting in Square version 2021-05-13: - * `mappings` is not accepted in `CreateLoyaltyAccount` requests or returned in responses. - * `type` and `value` are not accepted in `CreateLoyaltyAccount` or `SearchLoyaltyAccounts` requests or returned in responses. - +- **Payments API.** + + - [CreatePayment.](https://developer.squareup.com/reference/square_2021-05-13/payments-api/create-payment) The endpoint now supports ACH bank transfer payments. For more information, see [ACH Payment](https://developer.squareup.com/docs/payments-api/take-payments/ach-payments). + +- **Loyalty API:** + + - The [Loyalty API](https://developer.squareup.com/docs/loyalty-api/overview) has moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. + + - The [ListLoyaltyPrograms](https://developer.squareup.com/reference/square_2021-05-13/loyalty-api/list-loyalty-programs) endpoint is deprecated and replaced by the [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2021-05-13/loyalty-api/retrieve-loyalty-program) endpoint when used with the `main` keyword. + + - [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-05-13/objects/LoyaltyAccount)  object. The `mappings` field is retired and replaced by `mapping`. + + - [LoyaltyAccountMapping](https://developer.squareup.com/reference/square_2021-05-13/objects/LoyaltyAccountMapping) object. The `type` and `value` fields are retired and replaced by `phone_number`. + + Starting in Square version 2021-05-13: + + - `mappings` is not accepted in `CreateLoyaltyAccount` requests or returned in responses. + - `type` and `value` are not accepted in `CreateLoyaltyAccount` or `SearchLoyaltyAccounts` requests or returned in responses. + For more information, see [Migration notes.](https://developer.squareup.com/docs/loyalty-api/overview#migration-notes) - + ## Documentation updates -* **Getting Started** Added step that shows how to use the API Logs to examine a transaction. +- **Getting Started** Added step that shows how to use the API Logs to examine a transaction. ## Version 10.0.0.20210421 (2021-04-21) + ## New API releases ## Existing API updates -* **Subscriptions API:** - * [ResumeSubscription.](https://developer.squareup.com/reference/square_2021-04-21/subscriptions-api/resume-subscription) This new endpoint enables applications to resume [deactivated subscriptions.](https://developer.squareup.com/docs/subscriptions-api/overview#deactivated-subscriptions) After a subscription is created, there are events that can make a subscription non-billable, causing Square to deactivate the subscription. A seller can also resume deactivated subscriptions in the Seller Dashboard. Applications can call [ListSubscriptionEvents](https://developer.squareup.com/reference/square_2021-04-21/subscriptions-api/list-subscription-events) to determine why Square deactivated a subscription. - -* **Customers API:** +- **Subscriptions API:** + + - [ResumeSubscription.](https://developer.squareup.com/reference/square_2021-04-21/subscriptions-api/resume-subscription) This new endpoint enables applications to resume [deactivated subscriptions.](https://developer.squareup.com/docs/subscriptions-api/overview#deactivated-subscriptions) After a subscription is created, there are events that can make a subscription non-billable, causing Square to deactivate the subscription. A seller can also resume deactivated subscriptions in the Seller Dashboard. Applications can call [ListSubscriptionEvents](https://developer.squareup.com/reference/square_2021-04-21/subscriptions-api/list-subscription-events) to determine why Square deactivated a subscription. + +- **Customers API:** - * [Customer](https://developer.squareup.com/reference/square_2021-04-21/objects/Customer) object: - * New `version` field (beta). This field represents the current version of the customer profile. You can include it in your `UpdateCustomer` and `DeleteCustomer` requests to enable optimistic concurrency. For more information, see [Customer profile versions and optimistic concurrency support.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-profile-versions-and-optimistic-concurrency-support) - * The `groups` field and corresponding `CustomerGroupInfo` object are retired. - - * [Customer webhooks](https://developer.squareup.com/docs/customers-api/use-the-api/customer-webhooks) have moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. Event notifications now include the `version` field (beta). - -* **Invoices API:** + - [Customer](https://developer.squareup.com/reference/square_2021-04-21/objects/Customer) object: + - New `version` field (beta). This field represents the current version of the customer profile. You can include it in your `UpdateCustomer` and `DeleteCustomer` requests to enable optimistic concurrency. For more information, see [Customer profile versions and optimistic concurrency support.](https://developer.squareup.com/docs/customers-api/what-it-does#customer-profile-versions-and-optimistic-concurrency-support) + - The `groups` field and corresponding `CustomerGroupInfo` object are retired. + - [Customer webhooks](https://developer.squareup.com/docs/customers-api/use-the-api/customer-webhooks) have moved to the [general availability](https://developer.squareup.com/docs/build-basics/api-lifecycle#general-availability) (GA) state. Event notifications now include the `version` field (beta). - * The [Invoices API](https://developer.squareup.com/docs/invoices-api/overview) has moved to the GA state. +- **Invoices API:** - * [Invoice](https://developer.squareup.com/reference/square_2021-04-21/objects/Invoice) object: - * A new required `accepted_payment_methods` field that defines the methods of payment that customers can use to pay an invoice on the Square-hosted invoice page. Valid values are defined in the new [InvoiceAcceptedPaymentMethods](https://developer.squareup.com/reference/square_2021-04-21/objects/InvoiceAcceptedPaymentMethods) enum. For more information, see the [migration notes.](https://developer.squareup.com/docs/invoices-api/overview#migration-notes) - * A new `subscription_id` field, which is included in invoices created for subscription billing. + - The [Invoices API](https://developer.squareup.com/docs/invoices-api/overview) has moved to the GA state. -* **Loyalty API:** (beta) - - * [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2021-04-21/loyalty-api/retrieve-loyalty-program) endpoint. This new endpoint accepts a program ID or the `main` keyword and returns the loyalty program in a seller's account. For more information, see [Retrieve a loyalty program.](https://developer.squareup.com/docs/loyalty-api/overview#retrieve-loyalty-program) This endpoint is preferred over the `ListLoyaltyPrograms` endpoint. + - [Invoice](https://developer.squareup.com/reference/square_2021-04-21/objects/Invoice) object: + - A new required `accepted_payment_methods` field that defines the methods of payment that customers can use to pay an invoice on the Square-hosted invoice page. Valid values are defined in the new [InvoiceAcceptedPaymentMethods](https://developer.squareup.com/reference/square_2021-04-21/objects/InvoiceAcceptedPaymentMethods) enum. For more information, see the [migration notes.](https://developer.squareup.com/docs/invoices-api/overview#migration-notes) + - A new `subscription_id` field, which is included in invoices created for subscription billing. - * Introduced a new mapping implementation for loyalty accounts: - * [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-04-21/objects/LoyaltyAccount) object. Added the `mapping` field (of type `LoyaltyAccountMapping`), which is used to associate the loyalty account with a buyer. This field is recommended over the `mappings` field. - * [LoyaltyAccountMapping](https://developer.squareup.com/reference/square_2021-04-21/objects/LoyaltyAccountMapping) object. Added the `phone_number` field to represent a phone number mapping. This field is recommended over the `type` and `value` fields. +- **Loyalty API:** (beta) - * A new [loyalty.program.created](https://developer.squareup.com/reference/square_2021-04-21/webhooks/loyalty.program.created) webhook. Square now publishes an event notification when a loyalty program is created in the Square Seller Dashboard. + - [RetrieveLoyaltyProgram](https://developer.squareup.com/reference/square_2021-04-21/loyalty-api/retrieve-loyalty-program) endpoint. This new endpoint accepts a program ID or the `main` keyword and returns the loyalty program in a seller's account. For more information, see [Retrieve a loyalty program.](https://developer.squareup.com/docs/loyalty-api/overview#retrieve-loyalty-program) This endpoint is preferred over the `ListLoyaltyPrograms` endpoint. -* **Inventory API:** - * [InventoryChange](https://developer.squareup.com/reference/square_2021-04-21/objects/InventoryChange) can now have its own measurement unit. + - Introduced a new mapping implementation for loyalty accounts: -* **Catalog API:** - * [CatalogItem](https://developer.squareup.com/reference/square_2021-04-21/objects/CatalogItem) introduces the `sort_name` attribute that can take Japanese writing scripts to sort items by. When it is unspecified, the regular `name` attribute is used for sorting. - * [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-04-21/objects/CatalogCatalogPricingRule) has the new `customer_group_ids_any` attribute included to support automatic application of discounts to specified product set purchased by members of any of the customer groups identified by the `customer_group_ids_any` attribute values. -* **Team API** - * New [Team webhooks](https://developer.squareup.com/reference/square_2021-04-21/team-api/webhooks): `team_member.created`, `team_member.updated`, `team_member.wage_setting.updated` to notify on created and updated team members and wage settings. + - [LoyaltyAccount](https://developer.squareup.com/reference/square_2021-04-21/objects/LoyaltyAccount) object. Added the `mapping` field (of type `LoyaltyAccountMapping`), which is used to associate the loyalty account with a buyer. This field is recommended over the `mappings` field. + - [LoyaltyAccountMapping](https://developer.squareup.com/reference/square_2021-04-21/objects/LoyaltyAccountMapping) object. Added the `phone_number` field to represent a phone number mapping. This field is recommended over the `type` and `value` fields. + - A new [loyalty.program.created](https://developer.squareup.com/reference/square_2021-04-21/webhooks/loyalty.program.created) webhook. Square now publishes an event notification when a loyalty program is created in the Square Seller Dashboard. +- **Inventory API:** + - [InventoryChange](https://developer.squareup.com/reference/square_2021-04-21/objects/InventoryChange) can now have its own measurement unit. + +- **Catalog API:** + - [CatalogItem](https://developer.squareup.com/reference/square_2021-04-21/objects/CatalogItem) introduces the `sort_name` attribute that can take Japanese writing scripts to sort items by. When it is unspecified, the regular `name` attribute is used for sorting. + - [CatalogPricingRule](https://developer.squareup.com/reference/square_2021-04-21/objects/CatalogCatalogPricingRule) has the new `customer_group_ids_any` attribute included to support automatic application of discounts to specified product set purchased by members of any of the customer groups identified by the `customer_group_ids_any` attribute values. +- **Team API** + - New [Team webhooks](https://developer.squareup.com/reference/square_2021-04-21/team-api/webhooks): `team_member.created`, `team_member.updated`, `team_member.wage_setting.updated` to notify on created and updated team members and wage settings. ## Version 9.1.1.20210317 (2021-04-01) ## SDKs -* **Square Ruby SDK:** - * Added support for Ruby 3.0.0. +- **Square Ruby SDK:** + - Added support for Ruby 3.0.0. ## Version 9.1.0.20210317 (2021-03-17) ## Existing API updates -* **Payments API:** - * [CreatePayment](https://developer.squareup.com/reference/square_2021-03-17/payments-api/create-payment). Until now, the `CreatePayment` endpoint supported only taking card payments. In this release, the API now supports cash and external payments. For more information, see [Take Payments.](https://developer.squareup.com/docs/payments-api/take-payments) - * [UpdatePayment](https://developer.squareup.com/reference/square_2021-03-17/payments-api/update-payment). This new endpoint enables developers to change the payment amount and tip amount after a payment is created. For more information, see [Update Payments.](https://developer.squareup.com/docs/payments-api/update-payments) - -* **Invoices API:** - * [InvoiceDeliveryMethod](https://developer.squareup.com/reference/square_2021-03-17/enums/InvoiceDeliveryMethod) enum. Added the read-only `SMS` value. - * [InvoiceRequestMethod](https://developer.squareup.com/reference/square_2021-03-17/enums/InvoiceRequestMethod) enum (deprecated). Added the read-only `SMS`, `SMS_CHARGE_CARD_ON_FILE`, and `SMS_CHARGE_BANK_ON_FILE` values for backward compatibility. - - These values direct Square to send invoices and receipts to customers using SMS (text message). SMS settings can be configured from first-party Square applications only; they cannot be configured from the Invoices API. Square does not send invoice reminders when using SMS to communicate with customers. +- **Payments API:** + + - [CreatePayment](https://developer.squareup.com/reference/square_2021-03-17/payments-api/create-payment). Until now, the `CreatePayment` endpoint supported only taking card payments. In this release, the API now supports cash and external payments. For more information, see [Take Payments.](https://developer.squareup.com/docs/payments-api/take-payments) + - [UpdatePayment](https://developer.squareup.com/reference/square_2021-03-17/payments-api/update-payment). This new endpoint enables developers to change the payment amount and tip amount after a payment is created. For more information, see [Update Payments.](https://developer.squareup.com/docs/payments-api/update-payments) +- **Invoices API:** -* **Terminal API:** - * [TerminalCheckout](https://developer.squareup.com/reference/square_2021-03-17/objects/TerminalCheckout). Previously, `TerminalCheckout` only supported tapped, dipped, or swiped credit cards. It now supports manual card entry and e-money. Added the `payment_type` field to denote a request for a manually entered payment card or an e-money payment. - * [TerminalCheckoutPaymentType.](https://developer.squareup.com/reference/square_2021-03-17enums/TerminalCheckoutPaymentType) A new enum for the Terminal checkout payment types that can be requested. - * [E-money support](https://developer.squareup.com/docs/terminal-api/e-money-payments) is now available for Terminal checkout requests in Japan. + - [InvoiceDeliveryMethod](https://developer.squareup.com/reference/square_2021-03-17/enums/InvoiceDeliveryMethod) enum. Added the read-only `SMS` value. + - [InvoiceRequestMethod](https://developer.squareup.com/reference/square_2021-03-17/enums/InvoiceRequestMethod) enum (deprecated). Added the read-only `SMS`, `SMS_CHARGE_CARD_ON_FILE`, and `SMS_CHARGE_BANK_ON_FILE` values for backward compatibility. + + These values direct Square to send invoices and receipts to customers using SMS (text message). SMS settings can be configured from first-party Square applications only; they cannot be configured from the Invoices API. Square does not send invoice reminders when using SMS to communicate with customers. +- **Terminal API:** + - [TerminalCheckout](https://developer.squareup.com/reference/square_2021-03-17/objects/TerminalCheckout). Previously, `TerminalCheckout` only supported tapped, dipped, or swiped credit cards. It now supports manual card entry and e-money. Added the `payment_type` field to denote a request for a manually entered payment card or an e-money payment. + - [TerminalCheckoutPaymentType.](https://developer.squareup.com/reference/square_2021-03-17enums/TerminalCheckoutPaymentType) A new enum for the Terminal checkout payment types that can be requested. + - [E-money support](https://developer.squareup.com/docs/terminal-api/e-money-payments) is now available for Terminal checkout requests in Japan. ## SDKs -* **Square Java SDK:** - * Updated the OkHttp dependency to version 4.9.0. - * Fixed a `NullPointerException` when passing an empty order ID to the `UpdateOrder` method. -## Documentation updates +- **Square Java SDK:** + - Updated the OkHttp dependency to version 4.9.0. + - Fixed a `NullPointerException` when passing an empty order ID to the `UpdateOrder` method. -* **Multi-language code examples.** Previously, various topics showed only cURL examples for the REST API operations. These topics now show examples in multiple languages. You can use the language drop-down list to choose a language. - -* [When to Use Connect V1.](https://developer.squareup.com/docs/build-basics/using-connect-v1) Content is revised to reflect the most current information about when to use the Connect V1 API. +## Documentation updates +- **Multi-language code examples.** Previously, various topics showed only cURL examples for the REST API operations. These topics now show examples in multiple languages. You can use the language drop-down list to choose a language. +- [When to Use Connect V1.](https://developer.squareup.com/docs/build-basics/using-connect-v1) Content is revised to reflect the most current information about when to use the Connect V1 API. ## Version 9.0.0.20210226 (2021-02-26) + ## Existing API updates -* **Customers API:** - - * [New webhooks](https://developer.squareup.com/docs/customers-api/use-the-api/customer-webhooks) (beta). Square now sends notifications for the following events: - * [customer.created](https://developer.squareup.com/reference/square_2021-02-26/webhooks/customer.created) - * [customer.deleted](https://developer.squareup.com/reference/square_2021-02-26/webhooks/customer.deleted) - * [customer.updated](https://developer.squareup.com/reference/square_2021-02-26/webhooks/customer.updated) - -* **Orders API:** - * [CreateOrder](https://developer.squareup.com/reference/square_2021-02-26/orders-api/create-order). Removed the `location_id` field from the request. It was an unused field. - -* **Payments API:** - * [Payment](https://developer.squareup.com/reference/square_2021-02-26/objects/Payment). This type now returns the `card_payment_timeline` [(CardPaymentTimeline](https://developer.squareup.com/reference/square_2021-02-26/objects/CardPaymentTimeline)) as part of the `card_details` field. - -* **v1 Items API:** - * The following endpoints are [retired:](https://developer.squareup.com/docs/build-basics/api-lifecycle) - * `AdjustInventory`: Use the Square Inventory API [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-change-inventory) endpoint. - * `ListInventory`: Use the Square Inventory API [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-retrieve-inventory-counts) endpoint. - -* **v1 Employees.Timecards:** - * The following endpoints are retired: - * `CreateTimecard`: Use the Square Labor API [CreateShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/create-shift) endpoint. - * `DeleteTimecard`: Use the Square Labor API [DeleteShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/delete-shift) endpoint. - * `ListTimecards`: Use the Square Labor API [SearchShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/search-shift) endpoint. - * `RetrieveTimecards`: Use the Square Labor API [GetShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/get-shift) endpoint. - * `UpdateTimecard`: Use the Square Labor API [UpdateShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/update-shift) endpoint. - * `ListTimecardEvents`: No direct replacement. To learn about replacing the v1 functionality, see the [migration guide.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-timecards#endpoints) - -* **v1 Employees.CashDrawers:** - * The following endpoints are retired: - * `ListCashDrawerShifts`: Use the Square CashDrawerShifts API [ListCashDrawerShifts](https://developer.squareup.com/reference/square_2021-02-26/cash-drawers-api/list-cash-drawer-shifts) endpoint. - * `RetrieveCashDrawerShift`: Use the Square CashDrawerShifts API [RetrieveCashDrawerShift](https://developer.squareup.com/reference/square_2021-02-26/cash-drawers-api/retrieve-cash-drawer-shift) endpoint. -* **v1 Transactions.BankAccounts:** - * The following endpoints are retired: - * `ListBankAccounts`: Use the Square Bank Accounts API [ListBankAccounts](https://developer.squareup.com/reference/square_2021-02-26/bank-accounts-api/list-bank-accounts) endpoint. - * `RetrieveBankAccount`: Use the Square Bank Accounts API [GetBankAccount](https://developer.squareup.com/reference/square_2021-02-26/bank-accounts-api/get-bank-account) endpoint. +- **Customers API:** -## SDKs + - [New webhooks](https://developer.squareup.com/docs/customers-api/use-the-api/customer-webhooks) (beta). Square now sends notifications for the following events: + - [customer.created](https://developer.squareup.com/reference/square_2021-02-26/webhooks/customer.created) + - [customer.deleted](https://developer.squareup.com/reference/square_2021-02-26/webhooks/customer.deleted) + - [customer.updated](https://developer.squareup.com/reference/square_2021-02-26/webhooks/customer.updated) + +- **Orders API:** + + - [CreateOrder](https://developer.squareup.com/reference/square_2021-02-26/orders-api/create-order). Removed the `location_id` field from the request. It was an unused field. + +- **Payments API:** + + - [Payment](https://developer.squareup.com/reference/square_2021-02-26/objects/Payment). This type now returns the `card_payment_timeline` [(CardPaymentTimeline](https://developer.squareup.com/reference/square_2021-02-26/objects/CardPaymentTimeline)) as part of the `card_details` field. + +- **v1 Items API:** + + - The following endpoints are [retired:](https://developer.squareup.com/docs/build-basics/api-lifecycle) + - `AdjustInventory`: Use the Square Inventory API [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-change-inventory) endpoint. + - `ListInventory`: Use the Square Inventory API [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-retrieve-inventory-counts) endpoint. -* **All Square SDKs:** +- **v1 Employees.Timecards:** - By default, all SDKs send requests to Square's production (https://connect.squareup.com) or sandbox (https://connect.squareupsandbox.com) hosts based on the client's `environment` parameter. + - The following endpoints are retired: + - `CreateTimecard`: Use the Square Labor API [CreateShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/create-shift) endpoint. + - `DeleteTimecard`: Use the Square Labor API [DeleteShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/delete-shift) endpoint. + - `ListTimecards`: Use the Square Labor API [SearchShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/search-shift) endpoint. + - `RetrieveTimecards`: Use the Square Labor API [GetShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/get-shift) endpoint. + - `UpdateTimecard`: Use the Square Labor API [UpdateShift](https://developer.squareup.com/reference/square_2021-02-26/labor-api/update-shift) endpoint. + - `ListTimecardEvents`: No direct replacement. To learn about replacing the v1 functionality, see the [migration guide.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-timecards#endpoints) - You now have the option to use a custom URL instead. To use a custom URL, follow the example for your language to set the `environment` parameter to `custom` and the `customUrl` parameter to your URL: +- **v1 Employees.CashDrawers:** + - The following endpoints are retired: + - `ListCashDrawerShifts`: Use the Square CashDrawerShifts API [ListCashDrawerShifts](https://developer.squareup.com/reference/square_2021-02-26/cash-drawers-api/list-cash-drawer-shifts) endpoint. + - `RetrieveCashDrawerShift`: Use the Square CashDrawerShifts API [RetrieveCashDrawerShift](https://developer.squareup.com/reference/square_2021-02-26/cash-drawers-api/retrieve-cash-drawer-shift) endpoint. +- **v1 Transactions.BankAccounts:** + - The following endpoints are retired: + - `ListBankAccounts`: Use the Square Bank Accounts API [ListBankAccounts](https://developer.squareup.com/reference/square_2021-02-26/bank-accounts-api/list-bank-accounts) endpoint. + - `RetrieveBankAccount`: Use the Square Bank Accounts API [GetBankAccount](https://developer.squareup.com/reference/square_2021-02-26/bank-accounts-api/get-bank-account) endpoint. - - Java +## SDKs + +- **All Square SDKs:** + + By default, all SDKs send requests to Square's production (https://connect.squareup.com) or sandbox (https://connect.squareupsandbox.com) hosts based on the client's `environment` parameter. - ```java - new SquareClient.Builder() - .environment(Environment.CUSTOM) - .customUrl("https://example.com") - ``` + You now have the option to use a custom URL instead. To use a custom URL, follow the example for your language to set the `environment` parameter to `custom` and the `customUrl` parameter to your URL: - - .NET + - Java - ```csharp - new Square.SquareClient.Builder() - .Environment(Environment.Custom) - .CustomUrl("https://example.com") - ``` + ```java + new SquareClient.Builder() + .environment(Environment.CUSTOM) + .customUrl("https://example.com") + ``` - - Node.js + - .NET - ```javascript - new Client({ - environment: Environment.Custom, - customUrl: 'https://example.com' - }); - ``` + ```csharp + new Square.SquareClient.Builder() + .Environment(Environment.Custom) + .CustomUrl("https://example.com") + ``` - - PHP + - Node.js - ```php - new Square\SquareClient([ - 'environment' => Environment::CUSTOM, - 'customUrl' => 'https://example.com', - ]); - ``` + ```javascript + new Client({ + environment: Environment.Custom, + customUrl: "https://example.com", + }); + ``` - - Python + - PHP - ```python - Client( - environment = 'custom', - custom_url = 'https://example.com',) - ``` + ```php + new Square\SquareClient([ + 'environment' => Environment::CUSTOM, + 'customUrl' => 'https://example.com', + ]); + ``` - - Ruby + - Python - ```ruby - Square::Client.new( - environment: 'custom', - custom_url: 'https://example.com' - }); - ``` + ```python + Client( + environment = 'custom', + custom_url = 'https://example.com',) + ``` + - Ruby -* **Square .NET SDK:** + ```ruby + SquareLegacy::Client.new( + environment: 'custom', + custom_url: 'https://example.com' + }); + ``` + +- **Square .NET SDK:** Square has overridden the `Equals` and `GetHashCode` methods for models: - * In the `Equals` override, Square has implemented a field-level comparison. - * The Square `GetHashCode` override now ensures that hashes are deterministic and unique for each object. + - In the `Equals` override, Square has implemented a field-level comparison. + - The Square `GetHashCode` override now ensures that hashes are deterministic and unique for each object. -* **Square Node.js SDK:** +- **Square Node.js SDK:** Endpoints that return 64-bit integers now return a `BigInt` object instead of a `Number` object. - -* **Connect Node.js SDK:** (deprecated) +- **Connect Node.js SDK:** (deprecated) The deprecated Connect Node.js SDK is in the security [maintenance state.](https://developer.squareup.com/docs/build-basics/api-lifecycle#maintenance) It does not receive any bug fixes or API updates from the Square version 2021-02-26 release. However, the SDK will receive support and security patches until it is retired (end of life) in the second quarter of 2021. For more information, including steps for migrating to the [Square Node.js SDK,](https://github.com/square/square-nodejs-sdk) see the [Connect SDK README.](https://github.com/square/connect-nodejs-sdk/blob/master/README.md) ## Documentation updates -* **Catalog API:** - * [Update Catalog Objects.](https://developer.squareup.com/docs/catalog-api/update-catalog-objects) Provides programming guidance to update catalog objects. -* **Inventory API:** - * [List or retrieve inventory.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-items#list-or-retrieve-inventory) Migrate the retired v1 endpoint of `ListInventory` to the v2 endpoint of `BatchRetrieveInventoryCounts`. Compare and contrast the programming patterns between the v1 endpoint of `ListInventory` and its v2 counterparts of [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-retrieve-inventory-counts) or [RetrieveInventoryCount](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/retrieve-inventory-count). - * [Adjust or change inventory.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-items#adjust-or-change-inventory) Migrate the retired v1 endpoint of `AdjustInventory` to the v2 endpoint of `BatchChangeInventory`. Compare and contrast the programming patterns between the v1 endpoint of `AdjustInventory` and its v2 counterparts of [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-change-inventory). +- **Catalog API:** -* **Get Started topic.** Revised the [Get Started](https://developer.squareup.com/docs/get-started) experience. In addition to clarifications, it now includes the use of the Square Sandbox and API Explorer. These are the tools and environments developers use to explore Square APIs. + - [Update Catalog Objects.](https://developer.squareup.com/docs/catalog-api/update-catalog-objects) Provides programming guidance to update catalog objects. +- **Inventory API:** + + - [List or retrieve inventory.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-items#list-or-retrieve-inventory) Migrate the retired v1 endpoint of `ListInventory` to the v2 endpoint of `BatchRetrieveInventoryCounts`. Compare and contrast the programming patterns between the v1 endpoint of `ListInventory` and its v2 counterparts of [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-retrieve-inventory-counts) or [RetrieveInventoryCount](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/retrieve-inventory-count). + - [Adjust or change inventory.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-items#adjust-or-change-inventory) Migrate the retired v1 endpoint of `AdjustInventory` to the v2 endpoint of `BatchChangeInventory`. Compare and contrast the programming patterns between the v1 endpoint of `AdjustInventory` and its v2 counterparts of [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-02-26/inventory-api/batch-change-inventory). + +- **Get Started topic.** Revised the [Get Started](https://developer.squareup.com/docs/get-started) experience. In addition to clarifications, it now includes the use of the Square Sandbox and API Explorer. These are the tools and environments developers use to explore Square APIs. ## Version 8.1.0.20210121 (2021-01-21T00:00) + ## Existing API updates -* **Invoices API:** (beta) +- **Invoices API:** (beta) The `InvoicePaymentRequest.request_method` field is deprecated, and its current options are separated into two new fields that better represent their scope: - * `Invoice.delivery_method` specifies how Square should send invoices, reminders, and receipts to the customer. - * `InvoicePaymentRequest.automatic_payment_source` specifies the payment method for an automatic payment. + + - `Invoice.delivery_method` specifies how Square should send invoices, reminders, and receipts to the customer. + - `InvoicePaymentRequest.automatic_payment_source` specifies the payment method for an automatic payment. As part of this change, the [InvoiceDeliveryMethod](https://developer.squareup.com/reference/square_2021-01-21/enums/InvoiceDeliveryMethod) and [InvoiceAutomaticPaymentSource](https://developer.squareup.com/reference/square_2021-01-21/enums/InvoiceAutomaticPaymentSource) enums are added and the `InvoiceRequestMethod` enum is deprecated. The Invoices API will continue to accept `request_method` in create and update requests until the field is retired, but starting in this version, `request_method` is not included in returned `Invoice` objects. For more information, see the [migration notes.](https://developer.squareup.com/docs/invoices-api/overview#migrate-InvoicePaymentRequest.request_method) - -* **Locations API:** - * The [Locations.MCC](https://developer.squareup.com/reference/square_2021-01-21/objects/Location#definition__property-mcc) field is now updatable (beta). You can use the `UpdateLocation` endpoint to update the merchant category code (MCC) associated with a seller location. For more information, see [Initialize a merchant category code.](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) - - - +- **Locations API:** + - The [Locations.MCC](https://developer.squareup.com/reference/square_2021-01-21/objects/Location#definition__property-mcc) field is now updatable (beta). You can use the `UpdateLocation` endpoint to update the merchant category code (MCC) associated with a seller location. For more information, see [Initialize a merchant category code.](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) ## SDKs -* **Connect Node.js SDK:** (deprecated) + +- **Connect Node.js SDK:** (deprecated) The deprecated Connect Node.js SDK is in the security [maintenance state.](https://developer.squareup.com/docs/build-basics/api-lifecycle#maintenance) It will not receive any bug fixes or API updates from the Square version 2021-01-21 release. However, the SDK will receive support and security patches until it is retired (EOL) in Q2, 2021. For more information, including steps for migrating to the [Square Node.js SDK,](https://github.com/square/square-nodejs-sdk) see the [Connect SDK README.](https://github.com/square/connect-nodejs-sdk/blob/master/README.md) ## Documentation updates -* **Catalog API:** - * The [Use Item Options to Manage Item Variations](https://developer.squareup.com/docs/catalog-api/item-options-migration) topic is added. It demonstrates how item variations are usually used and how item options can be used to enable random access to item variations. -* **Inventory API:** - * The [Inventory API](inventory-api/what-it-does) content is updated. It provides clearer guidance about how to use the API, with a task-oriented TOC and improved code examples. +- **Catalog API:** + - The [Use Item Options to Manage Item Variations](https://developer.squareup.com/docs/catalog-api/item-options-migration) topic is added. It demonstrates how item variations are usually used and how item options can be used to enable random access to item variations. +- **Inventory API:** + - The [Inventory API](inventory-api/what-it-does) content is updated. It provides clearer guidance about how to use the API, with a task-oriented TOC and improved code examples. ## Version 8.0.0.20201216 (2020-12-16T00:00) + ## Existing API updates -* **Orders API:** - * [OrderLineItemPricingBlocklists.](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderLineItemPricingBlocklists) You can explicitly specify taxes and discounts in an order or automatically apply preconfigured taxes and discounts to an order. In addition, you can now block applying these taxes and discounts to a specific [OrderLineItem](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderLineItem) in an [order](https://developer.squareup.com/reference/square_2020-12-16/objects/Order). You add the `pricing_blocklists` attribute to individual line items and specify the `blocked_discounts` and `blocked_taxes` that you do not want to apply. For more information, see [Apply Taxes and Discounts.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts) For example walkthroughs, see [Automatically Apply Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-discounts) and [Automatically Apply Taxes.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes) - * [OrderPricingOptions](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderPricingOptions). Previously, the `pricing_options` field in an [order](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderPricingOptions) supported only `auto_apply_discounts` to enable the automatic application of preconfigured discounts. Now it also supports `auto_apply_taxes` to enable the automatic application of preconfigured taxes. For more information, see [Automatically apply preconfigured catalog taxes or discounts.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts#automatically-apply-preconfigured-catalog-taxes-or-discounts) +- **Orders API:** - * [OrderLineItemTax](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderLineItemTax). It now includes the new `auto_applied` field. It indicates whether the tax was automatically applied using a preconfigured [CatalogTax](https://developer.squareup.com/reference/square_2020-12-16/objects/CatalogTax). + - [OrderLineItemPricingBlocklists.](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderLineItemPricingBlocklists) You can explicitly specify taxes and discounts in an order or automatically apply preconfigured taxes and discounts to an order. In addition, you can now block applying these taxes and discounts to a specific [OrderLineItem](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderLineItem) in an [order](https://developer.squareup.com/reference/square_2020-12-16/objects/Order). You add the `pricing_blocklists` attribute to individual line items and specify the `blocked_discounts` and `blocked_taxes` that you do not want to apply. For more information, see [Apply Taxes and Discounts.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts) For example walkthroughs, see [Automatically Apply Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-discounts) and [Automatically Apply Taxes.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes) + - [OrderPricingOptions](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderPricingOptions). Previously, the `pricing_options` field in an [order](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderPricingOptions) supported only `auto_apply_discounts` to enable the automatic application of preconfigured discounts. Now it also supports `auto_apply_taxes` to enable the automatic application of preconfigured taxes. For more information, see [Automatically apply preconfigured catalog taxes or discounts.](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts#automatically-apply-preconfigured-catalog-taxes-or-discounts) + - [OrderLineItemTax](https://developer.squareup.com/reference/square_2020-12-16/objects/OrderLineItemTax). It now includes the new `auto_applied` field. It indicates whether the tax was automatically applied using a preconfigured [CatalogTax](https://developer.squareup.com/reference/square_2020-12-16/objects/CatalogTax). -* **Bookings API:** - * The [CancelBooking](https://developer.squareup.com/reference/square_2020-12-16/bookings-api/cancel-booking) endpoint supports canceling an accepted or pending booking. - * The [booking.created](https://developer.squareup.com/reference/square_2020-12-16/webhooks/booking.created) webhook event notifies when a new booking is created by calling the [CreateBooking](https://developer.squareup.com/reference/square_2020-12-16/bookings-api/cancel-booking) endpoint. - * The [booking.updated](https://developer.squareup.com/reference/square_2020-12-16/webhooks/booking.updated) webhook event notifies when an existing booking is updated. +- **Bookings API:** -* **Catalog API:** - * [ListCatalog](https://developer.squareup.com/reference/square_2020-12-16/catalog-api/list-catalog), [RetrieveCatalogObject](https://developer.squareup.com/reference/square_2020-12-16/catalog-api/retrieve-catalog-object), and [BatchRetrieveCatalogObjects](https://developer.squareup.com/reference/square_2020-12-16/catalog-api/batch-retrieve-catalog-objects) now support the `catalog_version` filter to return catalog objects of the specified version. + - The [CancelBooking](https://developer.squareup.com/reference/square_2020-12-16/bookings-api/cancel-booking) endpoint supports canceling an accepted or pending booking. + - The [booking.created](https://developer.squareup.com/reference/square_2020-12-16/webhooks/booking.created) webhook event notifies when a new booking is created by calling the [CreateBooking](https://developer.squareup.com/reference/square_2020-12-16/bookings-api/cancel-booking) endpoint. + - The [booking.updated](https://developer.squareup.com/reference/square_2020-12-16/webhooks/booking.updated) webhook event notifies when an existing booking is updated. -* **Customers API:** - * [SearchCustomers](https://developer.squareup.com/reference/square_2020-12-16/customers-api/search-customers) endpoint. The `email_address`, `group_ids`, `phone_number`, and `reference_id` query filters are now generally available (GA). - * The [Customer Groups](https://developer.squareup.com/reference/square_2020-12-16/customer-groups-api) API is now GA. - * The [Customer Segments](https://developer.squareup.com/reference/square_2020-12-16/customer-segments-api) API is now GA. +- **Catalog API:** + - [ListCatalog](https://developer.squareup.com/reference/square_2020-12-16/catalog-api/list-catalog), [RetrieveCatalogObject](https://developer.squareup.com/reference/square_2020-12-16/catalog-api/retrieve-catalog-object), and [BatchRetrieveCatalogObjects](https://developer.squareup.com/reference/square_2020-12-16/catalog-api/batch-retrieve-catalog-objects) now support the `catalog_version` filter to return catalog objects of the specified version. -* **Invoices API:** (beta) - * [Invoice](https://developer.squareup.com/reference/square_2020-12-16/objects/Invoice) object. Added the `custom_fields` field, which contains up to two customer-facing, seller-defined fields to display on the invoice. For more information, see [Custom fields.](https://developer.squareup.com/docs/invoices-api/overview#custom-fields) - As part of this change, the following objects are added: - * [InvoiceCustomField](https://developer.squareup.com/reference/square_2020-12-16/objects/InvoiceCustomField) object - * [InvoiceCustomFieldPlacement](https://developer.squareup.com/reference/square_2020-12-16/enums/InvoiceCustomFieldPlacement) enum - * [InvoiceRequestMethod](https://developer.squareup.com/reference/square_2020-12-16/enums/InvoiceRequestMethod) enum. Added the read-only CHARGE_BANK_ON_FILE value, which represents a bank transfer automatic payment method for a recurring invoice. +- **Customers API:** + + - [SearchCustomers](https://developer.squareup.com/reference/square_2020-12-16/customers-api/search-customers) endpoint. The `email_address`, `group_ids`, `phone_number`, and `reference_id` query filters are now generally available (GA). + - The [Customer Groups](https://developer.squareup.com/reference/square_2020-12-16/customer-groups-api) API is now GA. + - The [Customer Segments](https://developer.squareup.com/reference/square_2020-12-16/customer-segments-api) API is now GA. +- **Invoices API:** (beta) -* **Loyalty API:** (beta) - * [LoyaltyProgramRewardTier](https://developer.squareup.com/reference/square_2020-12-16/objects/LoyaltyProgramRewardTier) object. The `definition` field in this type is deprecated and replaced by the new `pricing_rule_reference` field. You can use `pricing_rule_reference` fields to retrieve catalog objects that define the discount details for the reward tier. For more information, see [Get discount details for a reward tier.](https://developer.squareup.com/docs/loyalty-api/overview#get-discount-details-for-a-reward-tier) + - [Invoice](https://developer.squareup.com/reference/square_2020-12-16/objects/Invoice) object. Added the `custom_fields` field, which contains up to two customer-facing, seller-defined fields to display on the invoice. For more information, see [Custom fields.](https://developer.squareup.com/docs/invoices-api/overview#custom-fields) + As part of this change, the following objects are added: + - [InvoiceCustomField](https://developer.squareup.com/reference/square_2020-12-16/objects/InvoiceCustomField) object + - [InvoiceCustomFieldPlacement](https://developer.squareup.com/reference/square_2020-12-16/enums/InvoiceCustomFieldPlacement) enum + - [InvoiceRequestMethod](https://developer.squareup.com/reference/square_2020-12-16/enums/InvoiceRequestMethod) enum. Added the read-only CHARGE_BANK_ON_FILE value, which represents a bank transfer automatic payment method for a recurring invoice. + +- **Loyalty API:** (beta) + - [LoyaltyProgramRewardTier](https://developer.squareup.com/reference/square_2020-12-16/objects/LoyaltyProgramRewardTier) object. The `definition` field in this type is deprecated and replaced by the new `pricing_rule_reference` field. You can use `pricing_rule_reference` fields to retrieve catalog objects that define the discount details for the reward tier. For more information, see [Get discount details for a reward tier.](https://developer.squareup.com/docs/loyalty-api/overview#get-discount-details-for-a-reward-tier) As part of this change, the following APIs are deprecated: - * [LoyaltyProgramRewardDefinition](https://developer.squareup.com/reference/square_2020-12-16/objects/LoyaltyProgramRewardDefinition) object - * [LoyaltyProgramRewardDefinitionScope](https://developer.squareup.com/reference/square_2020-12-16/enums/LoyaltyProgramRewardDefinitionScope) enum - * [LoyaltyProgramRewardDefinitionType](https://developer.squareup.com/reference/square_2020-12-16/enums/LoyaltyProgramRewardDefinitionType) enum + - [LoyaltyProgramRewardDefinition](https://developer.squareup.com/reference/square_2020-12-16/objects/LoyaltyProgramRewardDefinition) object + - [LoyaltyProgramRewardDefinitionScope](https://developer.squareup.com/reference/square_2020-12-16/enums/LoyaltyProgramRewardDefinitionScope) enum + - [LoyaltyProgramRewardDefinitionType](https://developer.squareup.com/reference/square_2020-12-16/enums/LoyaltyProgramRewardDefinitionType) enum ## New SDK release -* **Square Node.js SDK:** - The new [Square Node.js SDK](https://github.com/square/square-nodejs-sdk) is now GA and replaces the deprecated Connect Node.js SDK. For migration information, see the [Connect SDK README.](https://github.com/square/connect-nodejs-sdk/blob/master/README.md) +- **Square Node.js SDK:** + The new [Square Node.js SDK](https://github.com/square/square-nodejs-sdk) is now GA and replaces the deprecated Connect Node.js SDK. For migration information, see the [Connect SDK README.](https://github.com/square/connect-nodejs-sdk/blob/master/README.md) ## Documentation updates -* [Get Right-Sized Permissions with Down-Scoped OAuth Tokens.](https://developer.squareup.com/docs/oauth-api/cookbook/downscoped-access) This new OAuth API topic shows how to get an additional reduced-scope OAuth token with a 24-hour expiration by using the refresh token from the Square account authorization OAuth flow. - +- [Get Right-Sized Permissions with Down-Scoped OAuth Tokens.](https://developer.squareup.com/docs/oauth-api/cookbook/downscoped-access) This new OAuth API topic shows how to get an additional reduced-scope OAuth token with a 24-hour expiration by using the refresh token from the Square account authorization OAuth flow. ## Version 7.0.0.20201118 (2020-11-18T00:00) + ## New API releases -* **Bookings API** (beta). This API enables you, as an application developer, to create applications to set up and manage bookings for appointments of fixed duration in which selected staff members of a Square seller provide specified services in supported locations for particular customers. - * For an overview, see [Manage Bookings for Square Sellers](https://developer.squareup.com/docs/bookings-api/what-it-is). - * For technical reference, see [Bookings API](https://developer.squareup.com/reference/square_2020-11-18/bookings-api). +- **Bookings API** (beta). This API enables you, as an application developer, to create applications to set up and manage bookings for appointments of fixed duration in which selected staff members of a Square seller provide specified services in supported locations for particular customers. + - For an overview, see [Manage Bookings for Square Sellers](https://developer.squareup.com/docs/bookings-api/what-it-is). + - For technical reference, see [Bookings API](https://developer.squareup.com/reference/square_2020-11-18/bookings-api). ## Existing API updates -* **Payments API:** - * [Payment.](https://developer.squareup.com/reference/square_2020-11-18/objects/Payment) The object now includes the `risk_evaluation` field to identify the Square-assigned risk level associated with the payment. Sellers can use this information to provide the goods and services or refund the payment. +- **Payments API:** + - [Payment.](https://developer.squareup.com/reference/square_2020-11-18/objects/Payment) The object now includes the `risk_evaluation` field to identify the Square-assigned risk level associated with the payment. Sellers can use this information to provide the goods and services or refund the payment. ## New SDK release -* **New Square Node.js SDK (beta)** + +- **New Square Node.js SDK (beta)** The new [Square Node.js SDK](https://github.com/square/square-nodejs-sdk) is available in beta and will eventually replace the deprecated Connect Node.js SDK. For migration information, see the [Connect SDK README.](https://github.com/square/connect-nodejs-sdk/blob/master/README.md) The following topics are updated to use the new SDK: - * [Walkthrough: Integrate Square Payments in a Website](https://developer.squareup.com/docs/payment-form/payment-form-walkthrough) - * [Verify the Buyer When Using a Nonce for an Online Payment](https://developer.squareup.com/docs/payment-form/cookbook/verify-buyer-on-card-charge) - * [Create a Gift Card Payment Endpoint](https://developer.squareup.com/docs/payment-form/gift-cards/part-2) + - [Walkthrough: Integrate Square Payments in a Website](https://developer.squareup.com/docs/payment-form/payment-form-walkthrough) + - [Verify the Buyer When Using a Nonce for an Online Payment](https://developer.squareup.com/docs/payment-form/cookbook/verify-buyer-on-card-charge) + - [Create a Gift Card Payment Endpoint](https://developer.squareup.com/docs/payment-form/gift-cards/part-2) ## Documentation Updates -* The **Testing** topics are moved from the end of the table of contents to the top, in the **Home** section under [Testing your App](https://developer.squareup.com/docs/testing-your-app). -* [Pay for orders.]](https://developer.squareup.com/docs/orders-api/pay-for-order) Topic revised to add clarity when to use Payments API and Orders API to pay for an order. The [Orders Integration]](https://developer.squareup.com/docs/payments-api/take-payments?preview=true#orders-integration) topic in Payments API simplified accordingly. - +- The **Testing** topics are moved from the end of the table of contents to the top, in the **Home** section under [Testing your App](https://developer.squareup.com/docs/testing-your-app). +- [Pay for orders.]](https://developer.squareup.com/docs/orders-api/pay-for-order) Topic revised to add clarity when to use Payments API and Orders API to pay for an order. The [Orders Integration]](https://developer.squareup.com/docs/payments-api/take-payments?preview=true#orders-integration) topic in Payments API simplified accordingly. ## Version 6.5.0.20201028 (2020-10-28T00:00) ## Existing API updates -* **Terminal API.** New endpoints to enable sellers in Canada refund Interac payments. - * New endpoints: +- **Terminal API.** New endpoints to enable sellers in Canada refund Interac payments. + + - New endpoints: + + - [CreateTerminalRefund](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/create-terminal-refund) + - [GetTerminalRefund](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/get-terminal-refund) + - [CancelTerminalRefund](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/cancel-terminal-refund) + - [SearchTerminalRefunds](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/search-terminal-refunds) + + - New webhooks: + + - `terminal.refund.created`. Notification of a new Terminal refund request. + - `terminal.refund.updated`. Notification that a Terminal refund request state is changed. + + - New topic [Refund Interac Payments.](https://developer.squareup.com/docs/terminal-api/square-terminal-refunds). Describes how to refund Interac payments. - * [CreateTerminalRefund](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/create-terminal-refund) - * [GetTerminalRefund](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/get-terminal-refund) - * [CancelTerminalRefund](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/cancel-terminal-refund) - * [SearchTerminalRefunds](https://developer.squareup.com/reference/square_2020-10-28/terminal-api/search-terminal-refunds) +- **Loyalty API (beta):** - * New webhooks: - * `terminal.refund.created`. Notification of a new Terminal refund request. - * `terminal.refund.updated`. Notification that a Terminal refund request state is changed. + - [SearchLoyaltyAccounts.](https://developer.squareup.com/reference/square_2020-10-28/loyalty-api/search-loyalty-accounts) The endpoint supports a new query parameter to search by customer ID. - * New topic [Refund Interac Payments.](https://developer.squareup.com/docs/terminal-api/square-terminal-refunds). Describes how to refund Interac payments. +- **Locations API:** -* **Loyalty API (beta):** - * [SearchLoyaltyAccounts.](https://developer.squareup.com/reference/square_2020-10-28/loyalty-api/search-loyalty-accounts) The endpoint supports a new query parameter to search by customer ID. + - [Location](https://developer.squareup.com/reference/square_2020-10-28/objects/Location) object. Has a new read-only field,[full_format_logo_url](https://developer.squareup.com/reference/square_2020-10-28/objects/Location#definition__property-full_format_logo_url), which provides URL of a full-format logo image for the location. + - [Webhooks](https://developer.squareup.com/docs/webhooks-api/subscribe-to-events#locations) The Locations API now supports notifications for when a location is created and when a location is updated. -* **Locations API:** - * [Location](https://developer.squareup.com/reference/square_2020-10-28/objects/Location) object. Has a new read-only field,[full_format_logo_url](https://developer.squareup.com/reference/square_2020-10-28/objects/Location#definition__property-full_format_logo_url), which provides URL of a full-format logo image for the location. - * [Webhooks](https://developer.squareup.com/docs/webhooks-api/subscribe-to-events#locations) The Locations API now supports notifications for when a location is created and when a location is updated. +- **Orders API:** -* **Orders API:** - * [RetrieveOrder](https://developer.squareup.com/reference/square_2020-10-28/orders-api/retrieve-order), new endpoint. For more information, see the [Retrieve Orders](https://developer.squareup.com/docs/orders-api/manage-orders#retrieve-orders) overview. + - [RetrieveOrder](https://developer.squareup.com/reference/square_2020-10-28/orders-api/retrieve-order), new endpoint. For more information, see the [Retrieve Orders](https://developer.squareup.com/docs/orders-api/manage-orders#retrieve-orders) overview. -* **Invoices API (beta):** - * [Invoice](https://developer.squareup.com/reference/square_2020-10-28/objects/Invoice) object. The [payment_requests](https://developer.squareup.com/reference/square_2020-10-28/objects/Invoice#definition__property-payment_requests) field can now contain up to 13 payment requests, with a maximum of 12 `INSTALLMENT` request types. This is a service-level change that applies to all Square API versions. For more information, see [Payment requests.](https://developer.squareup.com/docs/invoices-api/overview#payment-requests) +- **Invoices API (beta):** + - [Invoice](https://developer.squareup.com/reference/square_2020-10-28/objects/Invoice) object. The [payment_requests](https://developer.squareup.com/reference/square_2020-10-28/objects/Invoice#definition__property-payment_requests) field can now contain up to 13 payment requests, with a maximum of 12 `INSTALLMENT` request types. This is a service-level change that applies to all Square API versions. For more information, see [Payment requests.](https://developer.squareup.com/docs/invoices-api/overview#payment-requests) ## Version 6.4.0.20200923 (2020-09-23) + ## Existing API updates -* Invoices API (beta) - * [InvoiceStatus](https://developer.squareup.com/reference/square_2020-09-23/enums/InvoiceStatus) enum. Added the `PAYMENT_PENDING` value. Previously, the Invoices API returned a `PAID` or `PARTIALLY_PAID` status for invoices in a payment pending state. Now, the Invoices API returns a `PAYMENT_PENDING` status for all invoices in a payment pending state, including those previously returned as `PAID` or `PARTIALLY_PAID`. -* Payments API - * [ListPayment](https://developer.squareup.com/reference/square_2020-09-23/payments-api/list-payments). The endpoint now supports the `limit` parameter. -* Refunds API - * [ListPaymentRefunds](https://developer.squareup.com/reference/square_2020-09-23/refunds-api/list-payment-refunds). The endpoint now supports the `limit` parameter. -* [DeviceDetails](https://developer.squareup.com/reference/square_2020-09-23/objects/DeviceDetails#definition__property-device_installation_id). The object now includes the `device_installation_id` field. + +- Invoices API (beta) + - [InvoiceStatus](https://developer.squareup.com/reference/square_2020-09-23/enums/InvoiceStatus) enum. Added the `PAYMENT_PENDING` value. Previously, the Invoices API returned a `PAID` or `PARTIALLY_PAID` status for invoices in a payment pending state. Now, the Invoices API returns a `PAYMENT_PENDING` status for all invoices in a payment pending state, including those previously returned as `PAID` or `PARTIALLY_PAID`. +- Payments API + - [ListPayment](https://developer.squareup.com/reference/square_2020-09-23/payments-api/list-payments). The endpoint now supports the `limit` parameter. +- Refunds API + - [ListPaymentRefunds](https://developer.squareup.com/reference/square_2020-09-23/refunds-api/list-payment-refunds). The endpoint now supports the `limit` parameter. +- [DeviceDetails](https://developer.squareup.com/reference/square_2020-09-23/objects/DeviceDetails#definition__property-device_installation_id). The object now includes the `device_installation_id` field. + ## Documentation updates -* [Payment status.](https://developer.squareup.com/docs/payments-api/take-payments#payment-status) Added details about the `Payment.status` changes and how the status relates to the seller receiving the funds. -* [Refund status.](https://developer.squareup.com/docs/payments-api/refund-payments#refund-status) Added details about the `PaymentRefund.status` changes and how the status relates to the cardholder receiving the funds. -* [CreateRefund errors.](https://developer.squareup.com/docs/payments-api/error-codes#createrefund-errors) Added documentation for the `REFUND_DECLINED` error code. + +- [Payment status.](https://developer.squareup.com/docs/payments-api/take-payments#payment-status) Added details about the `Payment.status` changes and how the status relates to the seller receiving the funds. +- [Refund status.](https://developer.squareup.com/docs/payments-api/refund-payments#refund-status) Added details about the `PaymentRefund.status` changes and how the status relates to the cardholder receiving the funds. +- [CreateRefund errors.](https://developer.squareup.com/docs/payments-api/error-codes#createrefund-errors) Added documentation for the `REFUND_DECLINED` error code. ## Version 6.3.0.20200826 (2020-08-26) + ## Existing API updates -* Orders API - * [Order](https://developer.squareup.com/reference/square_2020-08-26/objects/Order) object. The `total_tip_money` field is now GA. - * [CreateOrder](https://developer.squareup.com/reference/square_2020-08-26/orders-api/create-order), [UpdateOrder](https://developer.squareup.com/reference/square_2020-08-26/orders-api/update-order), and [BatchRetrieveOrders](https://developer.squareup.com/reference/square_2020-08-26/orders-api/batch-retrieve-orders). These APIs now support merchant-scoped endpoints (for example, the `CreateOrder` endpoint `POST /v2/orders`). The location-scoped variants of these endpoints (for example, the `CreateOrder` endpoint `POST /v2/locations/{location_id}/orders`) continue to work, but these endpoints are now deprecated. You should use the merchant-scoped endpoints (you provide the location information in the request body). -* Labor API - * [Migrate from Employees to Team Members.](https://developer.squareup.com/docs/labor-api/migrate-to-teams) The Employees API is now deprecated in this release. Accordingly, update references to the `Shift.employee_id` field to the `Shift.team_member_id` field of the Labor API. -* v2 Employees API (deprecated) - * [Migrate from the Square Employees API.](https://developer.squareup.com/docs/team/migrate-from-v2-employees) The v2 Employees API is now deprecated. This topic provides information to migrate to the Team API. -* v1 Employees API (deprecated) - * [Migrate from the v1 Employees API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-employees) The v1 Employees API is now deprecated. This topic provides information to migrate to the Team API. + +- Orders API + - [Order](https://developer.squareup.com/reference/square_2020-08-26/objects/Order) object. The `total_tip_money` field is now GA. + - [CreateOrder](https://developer.squareup.com/reference/square_2020-08-26/orders-api/create-order), [UpdateOrder](https://developer.squareup.com/reference/square_2020-08-26/orders-api/update-order), and [BatchRetrieveOrders](https://developer.squareup.com/reference/square_2020-08-26/orders-api/batch-retrieve-orders). These APIs now support merchant-scoped endpoints (for example, the `CreateOrder` endpoint `POST /v2/orders`). The location-scoped variants of these endpoints (for example, the `CreateOrder` endpoint `POST /v2/locations/{location_id}/orders`) continue to work, but these endpoints are now deprecated. You should use the merchant-scoped endpoints (you provide the location information in the request body). +- Labor API + - [Migrate from Employees to Team Members.](https://developer.squareup.com/docs/labor-api/migrate-to-teams) The Employees API is now deprecated in this release. Accordingly, update references to the `Shift.employee_id` field to the `Shift.team_member_id` field of the Labor API. +- v2 Employees API (deprecated) + - [Migrate from the Square Employees API.](https://developer.squareup.com/docs/team/migrate-from-v2-employees) The v2 Employees API is now deprecated. This topic provides information to migrate to the Team API. +- v1 Employees API (deprecated) + - [Migrate from the v1 Employees API.](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-employees) The v1 Employees API is now deprecated. This topic provides information to migrate to the Team API. ## Documentation updates -* Point of Sale API - * [Build on iOS.](https://developer.squareup.com/docs/pos-api/build-on-ios) Corrected the Swift example code in step 7. -* Team API - * [Team API Overview.](https://developer.squareup.com/docs/team/overview) Documented the limitation related to creating a team member in the Square Sandbox. + +- Point of Sale API + - [Build on iOS.](https://developer.squareup.com/docs/pos-api/build-on-ios) Corrected the Swift example code in step 7. +- Team API + - [Team API Overview.](https://developer.squareup.com/docs/team/overview) Documented the limitation related to creating a team member in the Square Sandbox. ## All SDKs SDK technical reference documentation: -* Nulls in SDK documentation example code are replaced with example values. +- Nulls in SDK documentation example code are replaced with example values. ## .NET SDK Bug fixes: -* The `APIException.Errors` property was not set on instantiation. Behavior is now corrected to instantiate the class with an empty `Errors` list. +- The `APIException.Errors` property was not set on instantiation. Behavior is now corrected to instantiate the class with an empty `Errors` list. ## Version 6.2.0.20200812 (2020-08-12) + ## API releases -* Subscriptions API (beta): - * For an overview, see [Square Subscriptions.](https://developer.squareup.com/docs/subscriptions/overview) - * For technical reference, see [Subscriptions API.](https://developer.squareup.com/reference/square_2020-08-12/subscriptions-api) + +- Subscriptions API (beta): + - For an overview, see [Square Subscriptions.](https://developer.squareup.com/docs/subscriptions/overview) + - For technical reference, see [Subscriptions API.](https://developer.squareup.com/reference/square_2020-08-12/subscriptions-api) ## Existing API updates -* Catalog API - * [CatalogSubscriptionPlan](https://developer.squareup.com/reference/square_2020-08-12/objects/CatalogSubscriptionPlan) (beta). This catalog type is added in support of the Subscriptions API. Subscription plans are stored as catalog object of the `SUBSCRIPTION_PLAN` type. For more information, see [Set Up and Manage a Subscription Plan.](https://developer.squareup.com/docs/subscriptions-api/setup-plan) + +- Catalog API + - [CatalogSubscriptionPlan](https://developer.squareup.com/reference/square_2020-08-12/objects/CatalogSubscriptionPlan) (beta). This catalog type is added in support of the Subscriptions API. Subscription plans are stored as catalog object of the `SUBSCRIPTION_PLAN` type. For more information, see [Set Up and Manage a Subscription Plan.](https://developer.squareup.com/docs/subscriptions-api/setup-plan) ## SqPaymentForm SDK updates -* [SqPaymentForm.masterpassImageURL.](https://developer.squareup.com/docs/api/paymentform#masterpassimageurl) This function is updated to return a Secure Remote Commerce background image URL. + +- [SqPaymentForm.masterpassImageURL.](https://developer.squareup.com/docs/api/paymentform#masterpassimageurl) This function is updated to return a Secure Remote Commerce background image URL. ## Documentation updates -* Locations API - * [About the main location.](https://developer.squareup.com/docs/locations-api#about-the-main-location) Added clarifying information about the main location concept. -* OAuth API - * [Migrate to the Square API OAuth Flow.](https://developer.squareup.com/docs/oauth-api/migrate-to-square-oauth-flow) Added a new topic to document migration from a v1 location-scoped OAuth access token to the Square seller-scoped OAuth access token. -* Payment Form SDK - * Renamed the Add a Masterpass Button topic to [Add a Secure Remote Commerce Button.](https://developer.squareup.com/docs/payment-form/add-digital-wallets/masterpass) Updated the instructions to add a Secure Remote Commerce button to replace a legacy Masterpass button. - * [Payment form technical reference.](https://developer.squareup.com/docs/api/paymentform) Updated the reference to show code examples for adding a Secure Remote Commerce button. + +- Locations API + - [About the main location.](https://developer.squareup.com/docs/locations-api#about-the-main-location) Added clarifying information about the main location concept. +- OAuth API + - [Migrate to the Square API OAuth Flow.](https://developer.squareup.com/docs/oauth-api/migrate-to-square-oauth-flow) Added a new topic to document migration from a v1 location-scoped OAuth access token to the Square seller-scoped OAuth access token. +- Payment Form SDK + - Renamed the Add a Masterpass Button topic to [Add a Secure Remote Commerce Button.](https://developer.squareup.com/docs/payment-form/add-digital-wallets/masterpass) Updated the instructions to add a Secure Remote Commerce button to replace a legacy Masterpass button. + - [Payment form technical reference.](https://developer.squareup.com/docs/api/paymentform) Updated the reference to show code examples for adding a Secure Remote Commerce button. ## Version 6.1.0.20200722 (2020-07-22) + ## API releases -* Invoices API (beta): - * For an overview, see [Manage Invoices Using the Invoices API](https://developer.squareup.com/docs/invoices-api/overview). - * For technical reference, see [Invoices API](https://developer.squareup.com/reference/square_2020-07-22/invoices-api). +- Invoices API (beta): + - For an overview, see [Manage Invoices Using the Invoices API](https://developer.squareup.com/docs/invoices-api/overview). + - For technical reference, see [Invoices API](https://developer.squareup.com/reference/square_2020-07-22/invoices-api). ## Existing API updates -* Catalog API - * [SearchCatalogItems](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-items). You can now call the new search endpoint to [search for catalog items or item variations](https://developer.squareup.com/docs/catalog-api/search-catalog-items), with simplified programming experiences, using one or more of the supported query filters, including the custom attribute value filter. -* Locations API - * [Locations API Overview](https://developer.squareup.com/docs/locations-api). Introduced the "main" location concept. - * [RetrieveLocation](https://developer.squareup.com/reference/square_2020-07-22/locations-api/retrieve-location). You can now specify "main" as the location ID to retrieve the main location information. +- Catalog API + - [SearchCatalogItems](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-items). You can now call the new search endpoint to [search for catalog items or item variations](https://developer.squareup.com/docs/catalog-api/search-catalog-items), with simplified programming experiences, using one or more of the supported query filters, including the custom attribute value filter. +- Locations API + + - [Locations API Overview](https://developer.squareup.com/docs/locations-api). Introduced the "main" location concept. + - [RetrieveLocation](https://developer.squareup.com/reference/square_2020-07-22/locations-api/retrieve-location). You can now specify "main" as the location ID to retrieve the main location information. + +- Merchants API -* Merchants API - * [RetrieveMerchant](https://developer.squareup.com/reference/square_2020-07-22/merchants-api/retrieve-merchant) and [ListMerchants](https://developer.squareup.com/reference/square_2020-07-22/merchants-api/retrieve-merchant). These endpoints now return a new field, `main_location_id`. + - [RetrieveMerchant](https://developer.squareup.com/reference/square_2020-07-22/merchants-api/retrieve-merchant) and [ListMerchants](https://developer.squareup.com/reference/square_2020-07-22/merchants-api/retrieve-merchant). These endpoints now return a new field, `main_location_id`. -* Orders API - * [PricingOptions](https://developer.squareup.com/reference/square_2020-07-22/objects/Order#definition__property-pricing_options). You can now enable the `auto_apply_discounts` of the options to have rule-based discounts automatically applied to an [Order](https://developer.squareup.com/reference/square_2020-07-22/objects/Order) that is pre-configured with a [pricing rule](https://developer.squareup.com/reference/square_2020-07-22/objects/CatalogPricingRule). +- Orders API -* [Inventory API](https://developer.squareup.com/reference/square_2020-07-22/inventory-api) - * Replaced 500 error on max string length exceeded with a max length error message. Max length attribute added to string type fields. + - [PricingOptions](https://developer.squareup.com/reference/square_2020-07-22/objects/Order#definition__property-pricing_options). You can now enable the `auto_apply_discounts` of the options to have rule-based discounts automatically applied to an [Order](https://developer.squareup.com/reference/square_2020-07-22/objects/Order) that is pre-configured with a [pricing rule](https://developer.squareup.com/reference/square_2020-07-22/objects/CatalogPricingRule). -* Terminal API (beta) - * [TerminalCheckout](https://developer.squareup.com/reference/square_2020-07-22/objects/TerminalCheckout) object. The `TerminalCheckoutCancelReason` field is renamed to `ActionCancelReason`. +- [Inventory API](https://developer.squareup.com/reference/square_2020-07-22/inventory-api) + + - Replaced 500 error on max string length exceeded with a max length error message. Max length attribute added to string type fields. + +- Terminal API (beta) + - [TerminalCheckout](https://developer.squareup.com/reference/square_2020-07-22/objects/TerminalCheckout) object. The `TerminalCheckoutCancelReason` field is renamed to `ActionCancelReason`. ## Documentation updates -* Catalog API - * [Search a catalog](https://developer.squareup.com/docs/catalog-api/search-catalog). New topics added to provide actionable guides to using the existing [SearchCatalogObjects](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-objects) endpoint, in addition to the [SearchCatalogItems](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-items) endpoints. +- Catalog API -* Orders API - * [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders). Updated existing content with the new pricing option for the automatic application of rule-based discounts. + - [Search a catalog](https://developer.squareup.com/docs/catalog-api/search-catalog). New topics added to provide actionable guides to using the existing [SearchCatalogObjects](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-objects) endpoint, in addition to the [SearchCatalogItems](https://developer.squareup.com/reference/square_2020-07-22/catalog-api/search-catalog-items) endpoints. +- Orders API + - [Create Orders](https://developer.squareup.com/docs/orders-api/create-orders). Updated existing content with the new pricing option for the automatic application of rule-based discounts. ## Version 6.0.0.20200625 (2020-06-25) ## New API release -* Team API generally available (GA) - * For an overview, see [Team API Overview](https://developer.squareup.com/docs/team/overview). - * For technical reference, see [Team API](https://developer.squareup.com/reference/square_2020-06-25/team-api). + +- Team API generally available (GA) + - For an overview, see [Team API Overview](https://developer.squareup.com/docs/team/overview). + - For technical reference, see [Team API](https://developer.squareup.com/reference/square_2020-06-25/team-api). ## Existing API updates -* Catalog API - * [Pricing](https://developer.squareup.com/reference/square_2020-06-25/objects/CatalogPricingRule) is now GA. It allows an application to configure catalog item pricing rules for the specified discounts to apply automatically. -* Payments API - * The [CardPaymentDetails](https://developer.squareup.com/reference/square_2020-06-25/objects/CardPaymentDetails) type now supports a new field, [refund_requires_card_presence](https://developer.squareup.com/reference/square_2020-06-25/objects/CardPaymentDetails#definition__property-refund_requires_card_presence). When set to true, the payment card must be physically present to refund a payment. + +- Catalog API + - [Pricing](https://developer.squareup.com/reference/square_2020-06-25/objects/CatalogPricingRule) is now GA. It allows an application to configure catalog item pricing rules for the specified discounts to apply automatically. +- Payments API + - The [CardPaymentDetails](https://developer.squareup.com/reference/square_2020-06-25/objects/CardPaymentDetails) type now supports a new field, [refund_requires_card_presence](https://developer.squareup.com/reference/square_2020-06-25/objects/CardPaymentDetails#definition__property-refund_requires_card_presence). When set to true, the payment card must be physically present to refund a payment. ## Version 5.3.0.20200528 (2020-05-28) ## API releases -* Loyalty API (beta): - * For an overview, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview?train=2020-05-28). - * For technical reference, see [Loyalty API](https://developer.squareup.com/reference/square/loyalty-api). +- Loyalty API (beta): + - For an overview, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview?train=2020-05-28). + - For technical reference, see [Loyalty API](https://developer.squareup.com/reference/square/loyalty-api). ## Existing API updates -* Orders API - * [CalculateOrder (beta)](https://developer.squareup.com/reference/square/orders-api/calculate-order) endpoint. Use the endpoint to calculate adjustments (for example, taxes and discounts) to an order for preview purposes. In response, the endpoint returns the order showing the calculated totals. You can use this endpoint with an existing order or an order that has not been created. +- Orders API + + - [CalculateOrder (beta)](https://developer.squareup.com/reference/square/orders-api/calculate-order) endpoint. Use the endpoint to calculate adjustments (for example, taxes and discounts) to an order for preview purposes. In response, the endpoint returns the order showing the calculated totals. You can use this endpoint with an existing order or an order that has not been created. The endpoint does not update an existing order. It only returns a calculated view of the order that you provided in the request. To create or update an order, use the [CreateOrder](https://developer.squareup.com/reference/square/orders-api/create-order) and [UpdateOrder](https://developer.squareup.com/reference/square/orders-api/update-order) endpoints, respectively. - * [Order](https://developer.squareup.com/reference/square_2020-05-28/objects/Order?train=2020-05-28) type. Two fields are added in support of the Loyalty API integration. For more information, see [Deferred reward creation](https://developer.squareup.com/docs/loyalty-api/overview?train=2020-05-28#deferred-reward-creation). For an example, see [Redeem Points](https://developer.squareup.com/docs/loyalty-api/walkthrough1/redeem-points?train=2020-05-28). - * `Order.rewards` represents rewards added to an order by calling the [CreateLoyaltyReward](https://developer.squareup.com/reference/square/loyalty-api/create-loyalty-reward) endpoint. - * `Order.discount.reward_ids` indicates that a discount is the result of the specified rewards that were added to an order using the `CreateLoyaltyReward` endpoint. -* Customers API + - [Order](https://developer.squareup.com/reference/square_2020-05-28/objects/Order?train=2020-05-28) type. Two fields are added in support of the Loyalty API integration. For more information, see [Deferred reward creation](https://developer.squareup.com/docs/loyalty-api/overview?train=2020-05-28#deferred-reward-creation). For an example, see [Redeem Points](https://developer.squareup.com/docs/loyalty-api/walkthrough1/redeem-points?train=2020-05-28). + - `Order.rewards` represents rewards added to an order by calling the [CreateLoyaltyReward](https://developer.squareup.com/reference/square/loyalty-api/create-loyalty-reward) endpoint. + - `Order.discount.reward_ids` indicates that a discount is the result of the specified rewards that were added to an order using the `CreateLoyaltyReward` endpoint. - * The [Search Customers](https://developer.squareup.com/reference/square/customers-api/search-customers) endpoint supports search by email address, phone number, and reference ID with the following additional query filters: +- Customers API - * The [`email_address` query filter](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#search-by-email-address) (beta) supports an [exact](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#exact-search-by-email-address) or [fuzzy](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#fuzzy-search-by-email-address) search for customer profiles by their email addresses. + - The [Search Customers](https://developer.squareup.com/reference/square/customers-api/search-customers) endpoint supports search by email address, phone number, and reference ID with the following additional query filters: - * The [`phone_number` query filter](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#search-by-phone-number) (beta) supports an [exact](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#exact-search-by-phone-number) or [fuzzy](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#fuzzy-search-by-phone-number) search for customer profiles by their phone numbers. + - The [`email_address` query filter](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#search-by-email-address) (beta) supports an [exact](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#exact-search-by-email-address) or [fuzzy](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#fuzzy-search-by-email-address) search for customer profiles by their email addresses. - * The [`reference_id` query filter](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#search-by-reference-id) (beta) supports an [exact](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#exact-search-by-reference-id) or [fuzzy](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#fuzzy-search-by-reference-id) search for customer profiles by their reference IDs. + - The [`phone_number` query filter](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#search-by-phone-number) (beta) supports an [exact](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#exact-search-by-phone-number) or [fuzzy](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#fuzzy-search-by-phone-number) search for customer profiles by their phone numbers. - * The [`created_at`](https://developer.squareup.com/reference/square/objects/Customer#definition__property-created_at), [`updated_at`](https://developer.squareup.com/reference/square/objects/Customer#definition__property-updated_at), and [`id`](https://developer.squareup.com/reference/square/objects/Customer#definition__property-id) attributes on the [Customer](https://developer.squareup.com/docs/S%7BSQUARE_TECH_REF%7D/objects/customers?train=2020-05-28) resource are updated to be optional. As a result, they no longer are required input parameters when you call the Square SDKs to create a `Customer` object. You might need to update the dependent SDKs to the latest version to mediate breaking your existing code. + - The [`reference_id` query filter](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#search-by-reference-id) (beta) supports an [exact](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#exact-search-by-reference-id) or [fuzzy](https://developer.squareup.com/docs/customers-api/cookbook/search-customers?train=2020-05-28#fuzzy-search-by-reference-id) search for customer profiles by their reference IDs. + + - The [`created_at`](https://developer.squareup.com/reference/square/objects/Customer#definition__property-created_at), [`updated_at`](https://developer.squareup.com/reference/square/objects/Customer#definition__property-updated_at), and [`id`](https://developer.squareup.com/reference/square/objects/Customer#definition__property-id) attributes on the [Customer](https://developer.squareup.com/docs/S%7BSQUARE_TECH_REF%7D/objects/customers?train=2020-05-28) resource are updated to be optional. As a result, they no longer are required input parameters when you call the Square SDKs to create a `Customer` object. You might need to update the dependent SDKs to the latest version to mediate breaking your existing code. ## Square Webhooks -* [Square Webhooks](https://developer.squareup.com/reference/square/webhooks) (formerly v2 Webhooks). The status is changed from beta to general availability (GA). +- [Square Webhooks](https://developer.squareup.com/reference/square/webhooks) (formerly v2 Webhooks). The status is changed from beta to general availability (GA). -* [v1 Webhooks](https://developer.squareup.com/docs/webhooks-api/v1-tech-ref?train=2020-05-28). The v1 Inventory and Timecards webooks are now deprecated and replaced by [inventory.count.updated](https://developer.squareup.com/reference/square/webhooks/inventory.count.updated) and [labor.shift.updated](https://developer.squareup.com/reference/square/webhooks/inventory.count.updated). +- [v1 Webhooks](https://developer.squareup.com/docs/webhooks-api/v1-tech-ref?train=2020-05-28). The v1 Inventory and Timecards webooks are now deprecated and replaced by [inventory.count.updated](https://developer.squareup.com/reference/square/webhooks/inventory.count.updated) and [labor.shift.updated](https://developer.squareup.com/reference/square/webhooks/inventory.count.updated). ## Version 5.2.2.20200422 (2020-04-25) + ## Existing API updates -* **OAuth API** - * [Obtain Token](https://developer.squareup.com/reference/square/oauth-api/revoke-token) endpoint: Removed the `scopes` property from the request body. +- **OAuth API** + - [Obtain Token](https://developer.squareup.com/reference/square/oauth-api/revoke-token) endpoint: Removed the `scopes` property from the request body. ## Version 5.2.1.20200422 (2020-04-22) + ## API releases -* **Customer Segments API (beta).** `limit` field removed from **ListCustomerSegments** endpoint. +- **Customer Segments API (beta).** `limit` field removed from **ListCustomerSegments** endpoint. **Note:** This release fixes a bug introduced on the [April 22, 2020](changelog/connect-logs/2020-04-22) release of the Square API. ## Version 5.2.0.20200422 (2020-04-22) + ## API releases -* **Terminal API.** The new Terminal API lets a custom third-party POS app integrate with the Square Terminal to send terminal checkout requests to collect payments. - * For an overview, see [Overview](https://developer.squareup.com/docs/terminal-api/overview). - * For technical reference, see [Terminal API](https://developer.squareup.com/reference/square/terminal-api). -* **Devices API.** The new Devices API lets a custom third-party POS app generate a code used to sign in to a Square Terminal to create a pairing that lets the POS app send terminal checkout requests. For technical reference, see [Devices API](https://developer.squareup.com/reference/square/devices-api). +- **Terminal API.** The new Terminal API lets a custom third-party POS app integrate with the Square Terminal to send terminal checkout requests to collect payments. + + - For an overview, see [Overview](https://developer.squareup.com/docs/terminal-api/overview). + - For technical reference, see [Terminal API](https://developer.squareup.com/reference/square/terminal-api). -* **Customer Groups API (beta).** The new Customer Groups API (Beta) enables full CRUD management of customer groups, including the ability to list, retrieve, create, update, and delete customer groups. Previously, this functionality was only available through the Square dashboard and point-of-sale product interfaces. - * For an overview, see [Overview](https://developer.squareup.com/docs/customer-groups-api/what-it-does) - * For technical reference, see [Customer Groups](https://developer.squareup.com/reference/square/customer-groups-api). +- **Devices API.** The new Devices API lets a custom third-party POS app generate a code used to sign in to a Square Terminal to create a pairing that lets the POS app send terminal checkout requests. For technical reference, see [Devices API](https://developer.squareup.com/reference/square/devices-api). -* **Customer Segments API (beta).** The new Customer Segments API (Beta) lets you list and retrieve customer segment (also called smart groups) information. Coupled with the new `segment_ids` field on the customer resource, this API lets you better understand and track the customer segments to which a customer belongs. - * For an overview, see [Overview](https://developer.squareup.com/docs/customer-segmentss-api/what-it-does) - * For technical reference, see [Customer Segments]( https://developer.squareup.com/reference/square/customer-segments-api). +- **Customer Groups API (beta).** The new Customer Groups API (Beta) enables full CRUD management of customer groups, including the ability to list, retrieve, create, update, and delete customer groups. Previously, this functionality was only available through the Square dashboard and point-of-sale product interfaces. + - For an overview, see [Overview](https://developer.squareup.com/docs/customer-groups-api/what-it-does) + - For technical reference, see [Customer Groups](https://developer.squareup.com/reference/square/customer-groups-api). -* **New webhooks** v2 Webhooks (beta) now supports webhooks for the following APIs: - * Orders API. `order.created`, `order.updated`, and `order.fulfillment.updated` - * Terminal API. `terminal.checkout.created` and `terminal.checkout.updated` - * Devices API. `device.code.paired` +- **Customer Segments API (beta).** The new Customer Segments API (Beta) lets you list and retrieve customer segment (also called smart groups) information. Coupled with the new `segment_ids` field on the customer resource, this API lets you better understand and track the customer segments to which a customer belongs. + + - For an overview, see [Overview](https://developer.squareup.com/docs/customer-segmentss-api/what-it-does) + - For technical reference, see [Customer Segments](https://developer.squareup.com/reference/square/customer-segments-api). + +- **New webhooks** v2 Webhooks (beta) now supports webhooks for the following APIs: + + - Orders API. `order.created`, `order.updated`, and `order.fulfillment.updated` + - Terminal API. `terminal.checkout.created` and `terminal.checkout.updated` + - Devices API. `device.code.paired` For more information, see [Subscribe to Events](webhooks-api/subscribe-to-events). ## Existing API updates -* **Customers API** - * [AddGroupToCustomer](https://developer.squareup.com/reference/square/customers-api/add-group-to-customer) endpoint. Added to add customer memberships to a customer group. - * [RemoveGroupFromCustomer](https://developer.squareup.com/reference/square/customers-api/remove-group-from-customer) endpoint. Added to remove customer memberships from a customer group. - * [Customer](https://developer.squareup.com/reference/square/obects/Customer) object. Updated as follows: - * [`group_ids`](https://developer.squareup.com/reference/square/obects/Customer#definition__property-group_ids) field. Added to designate groups the customer is in. - * [`segment_ids`](https://developer.squareup.com/reference/square/obects/Customer#definition__property-segment_ids) field. Added to designate segments the customer is in. - * [`groups`](https://developer.squareup.com/reference/square/obects/Customer#definition__property-groups) field. Deprecated to be replaced by `group_ids` and `segment_ids`. It remains supported for one year from this release. - * [CustomerQuery](https://developer.squareup.com/reference/square/objects/CustomerQuery) object's `filter` parameter. Updated as follows: - * `group_ids` filter. Added to search for customers based on whether they belong to any, all, or none of the specified groups. +- **Customers API** + + - [AddGroupToCustomer](https://developer.squareup.com/reference/square/customers-api/add-group-to-customer) endpoint. Added to add customer memberships to a customer group. + - [RemoveGroupFromCustomer](https://developer.squareup.com/reference/square/customers-api/remove-group-from-customer) endpoint. Added to remove customer memberships from a customer group. + - [Customer](https://developer.squareup.com/reference/square/obects/Customer) object. Updated as follows: + - [`group_ids`](https://developer.squareup.com/reference/square/obects/Customer#definition__property-group_ids) field. Added to designate groups the customer is in. + - [`segment_ids`](https://developer.squareup.com/reference/square/obects/Customer#definition__property-segment_ids) field. Added to designate segments the customer is in. + - [`groups`](https://developer.squareup.com/reference/square/obects/Customer#definition__property-groups) field. Deprecated to be replaced by `group_ids` and `segment_ids`. It remains supported for one year from this release. + - [CustomerQuery](https://developer.squareup.com/reference/square/objects/CustomerQuery) object's `filter` parameter. Updated as follows: + - `group_ids` filter. Added to search for customers based on whether they belong to any, all, or none of the specified groups. + +- **Orders API** -* **Orders API** - * [OrderFulfillmentPickupDetails](https://developer.squareup.com/reference/square/objects/OrderFulfillmentPickupDetails) type updated to support curbside pickup: - * `is_curbside_pickup`. This Boolean field indicates curbside pickup. - * `CurbsidePickupDetails`. This type provides supporting information for curbside pickup, including a buyer description (for example, "buyer is in a red car") and a timestamp when the buyer arrived for the pickup. + - [OrderFulfillmentPickupDetails](https://developer.squareup.com/reference/square/objects/OrderFulfillmentPickupDetails) type updated to support curbside pickup: + - `is_curbside_pickup`. This Boolean field indicates curbside pickup. + - `CurbsidePickupDetails`. This type provides supporting information for curbside pickup, including a buyer description (for example, "buyer is in a red car") and a timestamp when the buyer arrived for the pickup. +- **OAuth API** -* **OAuth API** - * [RevokeToken](https://developer.squareup.com/reference/square/oauth-api/revoke-token) endpoint. Added a new field called [revoke_only_access_token](https://developer.squareup.com/reference/square/oauth-api/revoke-token#request__property-revoke_only_access_token). This field allows a client to revoke an access token but leave the parent authorization active. - * [ObtainToken](https://developer.squareup.com/reference/square/oauth-api/obtain-token) endpoint. Added a new field called [scopes](https://developer.squareup.com/reference/square/oauth-api/obtain-token#request__property-scopes). This field lets a client change the set of permissions for an access token when making a request to refresh the token. + - [RevokeToken](https://developer.squareup.com/reference/square/oauth-api/revoke-token) endpoint. Added a new field called [revoke_only_access_token](https://developer.squareup.com/reference/square/oauth-api/revoke-token#request__property-revoke_only_access_token). This field allows a client to revoke an access token but leave the parent authorization active. + - [ObtainToken](https://developer.squareup.com/reference/square/oauth-api/obtain-token) endpoint. Added a new field called [scopes](https://developer.squareup.com/reference/square/oauth-api/obtain-token#request__property-scopes). This field lets a client change the set of permissions for an access token when making a request to refresh the token. +- **Catalog API** -* **Catalog API** - * [CatalogQuickAmountsSettings](https://developer.squareup.com/reference/square/objects/CatalogQuickAmountsSettings) type. Added to support predefined custom payment amounts in the Square Register checkout dialog box. - * ENUM`CatalogItemProductType`. The ENUM value `GIFT_CARD` is now deprecated. + - [CatalogQuickAmountsSettings](https://developer.squareup.com/reference/square/objects/CatalogQuickAmountsSettings) type. Added to support predefined custom payment amounts in the Square Register checkout dialog box. + - ENUM`CatalogItemProductType`. The ENUM value `GIFT_CARD` is now deprecated. -* **Payments API.** See [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees) for updated information about permission requirements, Square reporting of the application fee collected by an app, and how to collect fees internationally. +- **Payments API.** See [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees) for updated information about permission requirements, Square reporting of the application fee collected by an app, and how to collect fees internationally. ## Version 5.1.0.20200325 (2020-03-25) + ## Existing API updates -* **[Payments API](https://developer.squareup.com/reference/square/payments-api).** In support of the existing [Delayed capture]](https://developer.squareup.com/docs/payments-api/take-payments) for payments, the following fields are added to the [Payment](https://developer.squareup.com/reference/square/objects/Payment) type: - * `delay_duration`. In a [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment) request, you can set `autocomplete` to false to get payment approval but not charge the payment source. You can now add this field to specify a time period to complete (or cancel) the payment. For more information, see [Delay capture]](https://developer.squareup.com/docs/payments-api/take-payments). - * `delay_action`. Defines the action that Square takes on the payment when the `delay_duration` elapses. In this release, the API supports only the cancel payment action. - * `delayed_until`. Provides the date and time on Square servers when Square applies `delay_action` on the payment. + +- **[Payments API](https://developer.squareup.com/reference/square/payments-api).** In support of the existing [Delayed capture]](https://developer.squareup.com/docs/payments-api/take-payments) for payments, the following fields are added to the [Payment](https://developer.squareup.com/reference/square/objects/Payment) type: + - `delay_duration`. In a [CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment) request, you can set `autocomplete` to false to get payment approval but not charge the payment source. You can now add this field to specify a time period to complete (or cancel) the payment. For more information, see [Delay capture]](https://developer.squareup.com/docs/payments-api/take-payments). + - `delay_action`. Defines the action that Square takes on the payment when the `delay_duration` elapses. In this release, the API supports only the cancel payment action. + - `delayed_until`. Provides the date and time on Square servers when Square applies `delay_action` on the payment. ## Version 5.0.0.20200226 (2020-02-26) + ## API releases -* **GA release**: All SDKs have been updated to support the new Bank Accounts and CashDrawerShifts APIs. -* **Beta release**: All SDKs have been updated to support the new Disputes API. +- **GA release**: All SDKs have been updated to support the new Bank Accounts and CashDrawerShifts APIs. +- **Beta release**: All SDKs have been updated to support the new Disputes API. ## Existing API updates All SDKs have been updated to support the following changes: -* **Catalog API** - * Batch upsert catalog objects endpoint — The `batches` field is now required and the array must have at least one element. - * CatalogModifier — Two fields added: - * `ordinal` to support custom ordering in a modifier list - * `modifier_list_id` to reference the parent modifier list - * CatalogModifierList — New field added: `ordinal` to support custom ordering in a list of **CatalogModifierList** objects. +- **Catalog API** + + - Batch upsert catalog objects endpoint — The `batches` field is now required and the array must have at least one element. + - CatalogModifier — Two fields added: + - `ordinal` to support custom ordering in a modifier list + - `modifier_list_id` to reference the parent modifier list + - CatalogModifierList — New field added: `ordinal` to support custom ordering in a list of **CatalogModifierList** objects. + +- **Customers API changes** -* **Customers API changes** - * SearchCustomers endpoint — `limit` size reduced from 1000 to 100 to improve the endpoint performance. + - SearchCustomers endpoint — `limit` size reduced from 1000 to 100 to improve the endpoint performance. -* **Orders API changes** - * CreateOrderRequest — Previously these request fields were deprecated: `line_items`, `taxes`, `discounts`. These fields are no longer available. Instead you now use the `Order` object in the request. For example, `Order.line_items`, `Order.taxes`, and `Order.discounts`. - * OrderLineItem type — There are two changes: - * The `taxes` field that was previously deprecated is no longer available. Instead, you now use the `OrderLineItem.applied_taxes` field. This also now requires that you set the `OrderLineItemTax.scope` field. - * The `discounts` field that was previously deprecated is no longer available. Instead, you now use the `OrderLineItem.applied_discounts` field. This also now requires that you set the `OrderLineItemDiscount.scope` field. +- **Orders API changes** -* **Shared object updates** - * **Card object** — New fields added: `card_type`, `prepaid_type`. Currently, only the Payments API responses populate these fields. + - CreateOrderRequest — Previously these request fields were deprecated: `line_items`, `taxes`, `discounts`. These fields are no longer available. Instead you now use the `Order` object in the request. For example, `Order.line_items`, `Order.taxes`, and `Order.discounts`. + - OrderLineItem type — There are two changes: + - The `taxes` field that was previously deprecated is no longer available. Instead, you now use the `OrderLineItem.applied_taxes` field. This also now requires that you set the `OrderLineItemTax.scope` field. + - The `discounts` field that was previously deprecated is no longer available. Instead, you now use the `OrderLineItem.applied_discounts` field. This also now requires that you set the `OrderLineItemDiscount.scope` field. + +- **Shared object updates** + - **Card object** — New fields added: `card_type`, `prepaid_type`. Currently, only the Payments API responses populate these fields. ## Version 4.1.0.20200122 (2020-01-22) -* New field: The **Employee** object now has an `is_owner` field. -* New enumeration: The **CardBrand** enumeration has a new `SQUARE_CAPITAL_CARD` enum value to support a Square one-time Installments payment. +- New field: The **Employee** object now has an `is_owner` field. +- New enumeration: The **CardBrand** enumeration has a new `SQUARE_CAPITAL_CARD` enum value to support a Square one-time Installments payment. -* New request body field constraint: The __Refund__ Payment request now requires a payment_id. +- New request body field constraint: The **Refund** Payment request now requires a payment_id. ## Version 4.0.0-20191217 (2019-12-17) + !!!important Square is excited to announce the public release of customized SDKs for [Java](https://github.com/square/square-java-sdk) and [.NET](https://github.com/square/square-dotnet-sdk). For more information, see [Square SDKs](https://developer.squareup.com/docs/sdks). !!! -* __GA release:__ SDKs updated to support new `receipt_url` and `receipt_number` fields added to the [Payment](https://developer.squareup.com/reference/square/objects/Payment) type. +- **GA release:** SDKs updated to support new `receipt_url` and `receipt_number` fields added to the [Payment](https://developer.squareup.com/reference/square/objects/Payment) type. -* __Beta release:__ SDKs updated to support the new [CashDrawerShifts](cashdrawershift-api/reporting) API. +- **Beta release:** SDKs updated to support the new [CashDrawerShifts](cashdrawershift-api/reporting) API. -* Square now follows the semantic versioning scheme for all SDKs except PHP and Node.js. This versioning scheme uses three numbers to delineate MAJOR, MINOR, and PATCH versions of our SDK. In addition, the SDK version also includes the API version so you know what Square API version the SDK is related to. For more information, see [Versioning and SDKs](https://developer.squareup.com/docs/build-basics/versioning-overview#versioning-and-sdks). -* Java, .Net, Python, and Ruby SDKs are now version 4.0.0. Java and .Net SDKs have breaking changes in version 4.0.0. Ruby and Python do not have breaking changes. +- Square now follows the semantic versioning scheme for all SDKs except PHP and Node.js. This versioning scheme uses three numbers to delineate MAJOR, MINOR, and PATCH versions of our SDK. In addition, the SDK version also includes the API version so you know what Square API version the SDK is related to. For more information, see [Versioning and SDKs](https://developer.squareup.com/docs/build-basics/versioning-overview#versioning-and-sdks). +- Java, .Net, Python, and Ruby SDKs are now version 4.0.0. Java and .Net SDKs have breaking changes in version 4.0.0. Ruby and Python do not have breaking changes. ## Version 3.20191120.0 (2019-11-20) + !!!important Square has begun the retirement process for Connect v1 APIs. See the [Connect v1 Retirement](https://developer.squareup.com/docs/migrate-from-v1) information page for details. !!! -* __GA releases:__ SDKs now support the new `modify_tax_basis` field to Discounts and v2 Sandbox -* __BETA releases:__ SDKs now support the Shifts API webhooks for Labor shift created, updated, deleted, CreateLocation endpoint, and the ability to customize statement description in Payments API. -* **Deprecated**: Support for v1Items API and v1Locations API is fully deprecated. +- **GA releases:** SDKs now support the new `modify_tax_basis` field to Discounts and v2 Sandbox +- **BETA releases:** SDKs now support the Shifts API webhooks for Labor shift created, updated, deleted, CreateLocation endpoint, and the ability to customize statement description in Payments API. +- **Deprecated**: Support for v1Items API and v1Locations API is fully deprecated. ## 3.20191023.0 (2019-10-23) -* **GA release**: Merchants.ListMerchant is GA for all SDKs. -* **Beta release**: All SDKs support exclusion strategies for pricing rules. + +- **GA release**: Merchants.ListMerchant is GA for all SDKs. +- **Beta release**: All SDKs support exclusion strategies for pricing rules. ## 3.20190925.0 (2019-09-25) -* **GA release**: All SDKs have been updated to support the new Merchants API. +- **GA release**: All SDKs have been updated to support the new Merchants API. -* **Beta release**: All SDKs have been updated to support the new endpoints (RetrieveLocation, UpdateLocation) added to the Locations API. +- **Beta release**: All SDKs have been updated to support the new endpoints (RetrieveLocation, UpdateLocation) added to the Locations API. -* **Beta release**: All SDKs have been updated to support the new field (`mcc`) added to the `Location` type. +- **Beta release**: All SDKs have been updated to support the new field (`mcc`) added to the `Location` type. -* **GA release**: All SDKs have been updated to support the new field (`bin`) added to the `Card` type. +- **GA release**: All SDKs have been updated to support the new field (`bin`) added to the `Card` type. -* **GA release**: All SDKs have been updated to support the new `CardPaymentDetails` fields (`verification_results`, `statement_description`, and `verification_method`). +- **GA release**: All SDKs have been updated to support the new `CardPaymentDetails` fields (`verification_results`, `statement_description`, and `verification_method`). -* **GA release**: All SDKs have been updated to support the new `Payment` field, (`employee_id`). +- **GA release**: All SDKs have been updated to support the new `Payment` field, (`employee_id`). diff --git a/doc/auth/oauth-2-bearer-token.md b/doc/auth/oauth-2-bearer-token.md index 24bfe546..c8a9472c 100644 --- a/doc/auth/oauth-2-bearer-token.md +++ b/doc/auth/oauth-2-bearer-token.md @@ -1,18 +1,13 @@ - # OAuth 2 Bearer token - - Documentation for accessing and setting credentials for global. ## Auth Credentials -| Name | Type | Description | Getter | -| --- | --- | --- | --- | +| Name | Type | Description | Getter | +| ----------- | -------- | --------------------------------------------------- | -------------- | | AccessToken | `String` | The OAuth 2.0 Access Token to use for API requests. | `access_token` | - - **Note:** Auth credentials can be set using named parameter for any of the above credentials (e.g. `access_token`) in the client initialization. ## Usage Example @@ -22,11 +17,9 @@ Documentation for accessing and setting credentials for global. You must provide credentials in the client as shown in the following code snippet. ```ruby -client = Square::Client.new( +client = SquareLegacy::Client.new( bearer_auth_credentials: BearerAuthCredentials.new( access_token: 'AccessToken' ) ) ``` - - diff --git a/doc/client.md b/doc/client.md index eedfb2c1..b946b908 100644 --- a/doc/client.md +++ b/doc/client.md @@ -1,30 +1,29 @@ - # Client Class Documentation The following parameters are configurable for the API Client: -| Parameter | Type | Description | -| --- | --- | --- | -| `square_version` | `String` | Square Connect API versions
*Default*: `'2025-07-16'` | -| `custom_url` | `String` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
*Default*: `'https://connect.squareup.com'` | -| `environment` | `string` | The API environment.
**Default: `production`** | -| `connection` | `Faraday::Connection` | The Faraday connection object passed by the SDK user for making requests | -| `adapter` | `Faraday::Adapter` | The Faraday adapter object passed by the SDK user for performing http requests | -| `timeout` | `Float` | The value to use for connection timeout.
**Default: 60** | -| `max_retries` | `Integer` | The number of times to retry an endpoint call if it fails.
**Default: 0** | -| `retry_interval` | `Float` | Pause in seconds between retries.
**Default: 1** | -| `backoff_factor` | `Float` | The amount to multiply each successive retry's interval amount by in order to provide backoff.
**Default: 2** | -| `retry_statuses` | `Array` | A list of HTTP statuses to retry.
**Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]** | -| `retry_methods` | `Array` | A list of HTTP methods to retry.
**Default: %i[get put]** | -| `http_callback` | `HttpCallBack` | The Http CallBack allows defining callables for pre and post API calls. | -| `user_agent_detail` | `string` | User agent detail, to be appended with user-agent header. | -| `additional_headers` | `String` | Additional headers to add to each API request | -| `bearer_auth_credentials` | [`BearerAuthCredentials`](auth/oauth-2-bearer-token.md) | The credential object for OAuth 2 Bearer token | +| Parameter | Type | Description | +| ------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `square_version` | `String` | Square Connect API versions
_Default_: `'2025-07-16'` | +| `custom_url` | `String` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
_Default_: `'https://connect.squareup.com'` | +| `environment` | `string` | The API environment.
**Default: `production`** | +| `connection` | `Faraday::Connection` | The Faraday connection object passed by the SDK user for making requests | +| `adapter` | `Faraday::Adapter` | The Faraday adapter object passed by the SDK user for performing http requests | +| `timeout` | `Float` | The value to use for connection timeout.
**Default: 60** | +| `max_retries` | `Integer` | The number of times to retry an endpoint call if it fails.
**Default: 0** | +| `retry_interval` | `Float` | Pause in seconds between retries.
**Default: 1** | +| `backoff_factor` | `Float` | The amount to multiply each successive retry's interval amount by in order to provide backoff.
**Default: 2** | +| `retry_statuses` | `Array` | A list of HTTP statuses to retry.
**Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]** | +| `retry_methods` | `Array` | A list of HTTP methods to retry.
**Default: %i[get put]** | +| `http_callback` | `HttpCallBack` | The Http CallBack allows defining callables for pre and post API calls. | +| `user_agent_detail` | `string` | User agent detail, to be appended with user-agent header. | +| `additional_headers` | `String` | Additional headers to add to each API request | +| `bearer_auth_credentials` | [`BearerAuthCredentials`](auth/oauth-2-bearer-token.md) | The credential object for OAuth 2 Bearer token | The API client can be initialized as follows: ```ruby -client = Square::Client.new( +client = SquareLegacy::Client.new( square_version: '2025-06-18', bearer_auth_credentials: BearerAuthCredentials.new( access_token: 'AccessToken' @@ -36,25 +35,25 @@ client = Square::Client.new( API calls return an `ApiResponse` object that includes the following fields: -| Field | Description | -| --- | --- | -| `status_code` | Status code of the HTTP response | -| `reason_phrase` | Reason phrase of the HTTP response | -| `headers` | Headers of the HTTP response as a Hash | -| `raw_body` | The body of the HTTP response as a String | -| `request` | HTTP request info | -| `errors` | Errors, if they exist | -| `cursor` | Cursor, if it exists | -| `body` | The deserialized body of the HTTP response | -| `data` | Data portion of returned body | +| Field | Description | +| --------------- | ------------------------------------------ | +| `status_code` | Status code of the HTTP response | +| `reason_phrase` | Reason phrase of the HTTP response | +| `headers` | Headers of the HTTP response as a Hash | +| `raw_body` | The body of the HTTP response as a String | +| `request` | HTTP request info | +| `errors` | Errors, if they exist | +| `cursor` | Cursor, if it exists | +| `body` | The deserialized body of the HTTP response | +| `data` | Data portion of returned body | ## Make Calls with the API Client ```ruby -require 'square' +require 'square_legacy' include Square -client = Square::Client.new( +client = SquareLegacy::Client.new( square_version: '2025-06-18', bearer_auth_credentials: BearerAuthCredentials.new( access_token: 'AccessToken' @@ -78,48 +77,47 @@ The gateway for the SDK. This class acts as a factory for the Apis and also hold ## API -| Name | Description | -| --- | --- | -| mobile_authorization | Gets MobileAuthorizationApi | -| o_auth | Gets OAuthApi | -| v1_transactions | Gets V1TransactionsApi | -| apple_pay | Gets ApplePayApi | -| bank_accounts | Gets BankAccountsApi | -| bookings | Gets BookingsApi | -| booking_custom_attributes | Gets BookingCustomAttributesApi | -| cards | Gets CardsApi | -| cash_drawers | Gets CashDrawersApi | -| catalog | Gets CatalogApi | -| customers | Gets CustomersApi | +| Name | Description | +| -------------------------- | -------------------------------- | +| mobile_authorization | Gets MobileAuthorizationApi | +| o_auth | Gets OAuthApi | +| v1_transactions | Gets V1TransactionsApi | +| apple_pay | Gets ApplePayApi | +| bank_accounts | Gets BankAccountsApi | +| bookings | Gets BookingsApi | +| booking_custom_attributes | Gets BookingCustomAttributesApi | +| cards | Gets CardsApi | +| cash_drawers | Gets CashDrawersApi | +| catalog | Gets CatalogApi | +| customers | Gets CustomersApi | | customer_custom_attributes | Gets CustomerCustomAttributesApi | -| customer_groups | Gets CustomerGroupsApi | -| customer_segments | Gets CustomerSegmentsApi | -| devices | Gets DevicesApi | -| disputes | Gets DisputesApi | -| employees | Gets EmployeesApi | -| events | Gets EventsApi | -| gift_cards | Gets GiftCardsApi | -| gift_card_activities | Gets GiftCardActivitiesApi | -| inventory | Gets InventoryApi | -| invoices | Gets InvoicesApi | -| labor | Gets LaborApi | -| locations | Gets LocationsApi | +| customer_groups | Gets CustomerGroupsApi | +| customer_segments | Gets CustomerSegmentsApi | +| devices | Gets DevicesApi | +| disputes | Gets DisputesApi | +| employees | Gets EmployeesApi | +| events | Gets EventsApi | +| gift_cards | Gets GiftCardsApi | +| gift_card_activities | Gets GiftCardActivitiesApi | +| inventory | Gets InventoryApi | +| invoices | Gets InvoicesApi | +| labor | Gets LaborApi | +| locations | Gets LocationsApi | | location_custom_attributes | Gets LocationCustomAttributesApi | -| checkout | Gets CheckoutApi | -| transactions | Gets TransactionsApi | -| loyalty | Gets LoyaltyApi | -| merchants | Gets MerchantsApi | +| checkout | Gets CheckoutApi | +| transactions | Gets TransactionsApi | +| loyalty | Gets LoyaltyApi | +| merchants | Gets MerchantsApi | | merchant_custom_attributes | Gets MerchantCustomAttributesApi | -| orders | Gets OrdersApi | -| order_custom_attributes | Gets OrderCustomAttributesApi | -| payments | Gets PaymentsApi | -| payouts | Gets PayoutsApi | -| refunds | Gets RefundsApi | -| sites | Gets SitesApi | -| snippets | Gets SnippetsApi | -| subscriptions | Gets SubscriptionsApi | -| team | Gets TeamApi | -| terminal | Gets TerminalApi | -| vendors | Gets VendorsApi | -| webhook_subscriptions | Gets WebhookSubscriptionsApi | - +| orders | Gets OrdersApi | +| order_custom_attributes | Gets OrderCustomAttributesApi | +| payments | Gets PaymentsApi | +| payouts | Gets PayoutsApi | +| refunds | Gets RefundsApi | +| sites | Gets SitesApi | +| snippets | Gets SnippetsApi | +| subscriptions | Gets SubscriptionsApi | +| team | Gets TeamApi | +| terminal | Gets TerminalApi | +| vendors | Gets VendorsApi | +| webhook_subscriptions | Gets WebhookSubscriptionsApi | diff --git a/examples/customers.rb b/examples/customers.rb index 9366ba37..986f1fac 100644 --- a/examples/customers.rb +++ b/examples/customers.rb @@ -1,7 +1,7 @@ -require 'square' +require 'square_legacy' # Initialize Square Client -square = Square::Client.new( +square = SquareLegacy::Client.new( access_token: 'ACCESS_TOKEN' ) diff --git a/lib/square.rb b/lib/square.rb deleted file mode 100644 index 73352f3c..00000000 --- a/lib/square.rb +++ /dev/null @@ -1,76 +0,0 @@ -require 'date' -require 'json' - -require 'apimatic_core_interfaces' -require 'apimatic_core' -require 'apimatic_faraday_client_adapter' - -require_relative 'square/api_helper' -require_relative 'square/client' - -# Utilities -require_relative 'square/utilities/file_wrapper' -require_relative 'square/utilities/date_time_helper' - -# Http -require_relative 'square/http/api_response' -require_relative 'square/http/http_call_back' -require_relative 'square/http/http_method_enum' -require_relative 'square/http/http_request' -require_relative 'square/http/http_response' - -# Logger -require_relative 'square/http/auth/o_auth2' - -# Models - -# Exceptions -require_relative 'square/exceptions/api_exception' - -require_relative 'square/configuration' - -# Controllers -require_relative 'square/api/base_api' -require_relative 'square/api/mobile_authorization_api' -require_relative 'square/api/o_auth_api' -require_relative 'square/api/v1_transactions_api' -require_relative 'square/api/apple_pay_api' -require_relative 'square/api/bank_accounts_api' -require_relative 'square/api/bookings_api' -require_relative 'square/api/booking_custom_attributes_api' -require_relative 'square/api/cards_api' -require_relative 'square/api/cash_drawers_api' -require_relative 'square/api/catalog_api' -require_relative 'square/api/customers_api' -require_relative 'square/api/customer_custom_attributes_api' -require_relative 'square/api/customer_groups_api' -require_relative 'square/api/customer_segments_api' -require_relative 'square/api/devices_api' -require_relative 'square/api/disputes_api' -require_relative 'square/api/employees_api' -require_relative 'square/api/events_api' -require_relative 'square/api/gift_cards_api' -require_relative 'square/api/gift_card_activities_api' -require_relative 'square/api/inventory_api' -require_relative 'square/api/invoices_api' -require_relative 'square/api/labor_api' -require_relative 'square/api/locations_api' -require_relative 'square/api/location_custom_attributes_api' -require_relative 'square/api/checkout_api' -require_relative 'square/api/transactions_api' -require_relative 'square/api/loyalty_api' -require_relative 'square/api/merchants_api' -require_relative 'square/api/merchant_custom_attributes_api' -require_relative 'square/api/orders_api' -require_relative 'square/api/order_custom_attributes_api' -require_relative 'square/api/payments_api' -require_relative 'square/api/payouts_api' -require_relative 'square/api/refunds_api' -require_relative 'square/api/sites_api' -require_relative 'square/api/snippets_api' -require_relative 'square/api/subscriptions_api' -require_relative 'square/api/team_api' -require_relative 'square/api/terminal_api' -require_relative 'square/api/vendors_api' -require_relative 'square/api/webhook_subscriptions_api' -require_relative 'square/utilities/webhooks_helper' diff --git a/lib/square_legacy.rb b/lib/square_legacy.rb new file mode 100644 index 00000000..cf9c72ee --- /dev/null +++ b/lib/square_legacy.rb @@ -0,0 +1,76 @@ +require 'date' +require 'json' + +require 'apimatic_core_interfaces' +require 'apimatic_core' +require 'apimatic_faraday_client_adapter' + +require_relative 'square_legacy/api_helper' +require_relative 'square_legacy/client' + +# Utilities +require_relative 'square_legacy/utilities/file_wrapper' +require_relative 'square_legacy/utilities/date_time_helper' + +# Http +require_relative 'square_legacy/http/api_response' +require_relative 'square_legacy/http/http_call_back' +require_relative 'square_legacy/http/http_method_enum' +require_relative 'square_legacy/http/http_request' +require_relative 'square_legacy/http/http_response' + +# Logger +require_relative 'square_legacy/http/auth/o_auth2' + +# Models + +# Exceptions +require_relative 'square_legacy/exceptions/api_exception' + +require_relative 'square_legacy/configuration' + +# Controllers +require_relative 'square_legacy/api/base_api' +require_relative 'square_legacy/api/mobile_authorization_api' +require_relative 'square_legacy/api/o_auth_api' +require_relative 'square_legacy/api/v1_transactions_api' +require_relative 'square_legacy/api/apple_pay_api' +require_relative 'square_legacy/api/bank_accounts_api' +require_relative 'square_legacy/api/bookings_api' +require_relative 'square_legacy/api/booking_custom_attributes_api' +require_relative 'square_legacy/api/cards_api' +require_relative 'square_legacy/api/cash_drawers_api' +require_relative 'square_legacy/api/catalog_api' +require_relative 'square_legacy/api/customers_api' +require_relative 'square_legacy/api/customer_custom_attributes_api' +require_relative 'square_legacy/api/customer_groups_api' +require_relative 'square_legacy/api/customer_segments_api' +require_relative 'square_legacy/api/devices_api' +require_relative 'square_legacy/api/disputes_api' +require_relative 'square_legacy/api/employees_api' +require_relative 'square_legacy/api/events_api' +require_relative 'square_legacy/api/gift_cards_api' +require_relative 'square_legacy/api/gift_card_activities_api' +require_relative 'square_legacy/api/inventory_api' +require_relative 'square_legacy/api/invoices_api' +require_relative 'square_legacy/api/labor_api' +require_relative 'square_legacy/api/locations_api' +require_relative 'square_legacy/api/location_custom_attributes_api' +require_relative 'square_legacy/api/checkout_api' +require_relative 'square_legacy/api/transactions_api' +require_relative 'square_legacy/api/loyalty_api' +require_relative 'square_legacy/api/merchants_api' +require_relative 'square_legacy/api/merchant_custom_attributes_api' +require_relative 'square_legacy/api/orders_api' +require_relative 'square_legacy/api/order_custom_attributes_api' +require_relative 'square_legacy/api/payments_api' +require_relative 'square_legacy/api/payouts_api' +require_relative 'square_legacy/api/refunds_api' +require_relative 'square_legacy/api/sites_api' +require_relative 'square_legacy/api/snippets_api' +require_relative 'square_legacy/api/subscriptions_api' +require_relative 'square_legacy/api/team_api' +require_relative 'square_legacy/api/terminal_api' +require_relative 'square_legacy/api/vendors_api' +require_relative 'square_legacy/api/webhook_subscriptions_api' +require_relative 'square_legacy/utilities/webhooks_helper' diff --git a/lib/square/api/apple_pay_api.rb b/lib/square_legacy/api/apple_pay_api.rb similarity index 99% rename from lib/square/api/apple_pay_api.rb rename to lib/square_legacy/api/apple_pay_api.rb index a7322bb6..8b21c7bf 100644 --- a/lib/square/api/apple_pay_api.rb +++ b/lib/square_legacy/api/apple_pay_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # ApplePayApi class ApplePayApi < BaseApi # Activates a domain for use with Apple Pay on the Web and Square. A diff --git a/lib/square/api/bank_accounts_api.rb b/lib/square_legacy/api/bank_accounts_api.rb similarity index 99% rename from lib/square/api/bank_accounts_api.rb rename to lib/square_legacy/api/bank_accounts_api.rb index 46277918..4a171a0a 100644 --- a/lib/square/api/bank_accounts_api.rb +++ b/lib/square_legacy/api/bank_accounts_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # BankAccountsApi class BankAccountsApi < BaseApi # Returns a list of [BankAccount]($m/BankAccount) objects linked to a Square diff --git a/lib/square/api/base_api.rb b/lib/square_legacy/api/base_api.rb similarity index 99% rename from lib/square/api/base_api.rb rename to lib/square_legacy/api/base_api.rb index 557b3eec..18bce917 100644 --- a/lib/square/api/base_api.rb +++ b/lib/square_legacy/api/base_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # BaseApi. class BaseApi include CoreLibrary diff --git a/lib/square/api/booking_custom_attributes_api.rb b/lib/square_legacy/api/booking_custom_attributes_api.rb similarity index 99% rename from lib/square/api/booking_custom_attributes_api.rb rename to lib/square_legacy/api/booking_custom_attributes_api.rb index 123f8d40..db264872 100644 --- a/lib/square/api/booking_custom_attributes_api.rb +++ b/lib/square_legacy/api/booking_custom_attributes_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # BookingCustomAttributesApi class BookingCustomAttributesApi < BaseApi # Get all bookings custom attribute definitions. diff --git a/lib/square/api/bookings_api.rb b/lib/square_legacy/api/bookings_api.rb similarity index 99% rename from lib/square/api/bookings_api.rb rename to lib/square_legacy/api/bookings_api.rb index 4cfa560b..867f6580 100644 --- a/lib/square/api/bookings_api.rb +++ b/lib/square_legacy/api/bookings_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # BookingsApi class BookingsApi < BaseApi # Retrieve a collection of bookings. diff --git a/lib/square/api/cards_api.rb b/lib/square_legacy/api/cards_api.rb similarity index 99% rename from lib/square/api/cards_api.rb rename to lib/square_legacy/api/cards_api.rb index 2a9bc339..9ca623a7 100644 --- a/lib/square/api/cards_api.rb +++ b/lib/square_legacy/api/cards_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CardsApi class CardsApi < BaseApi # Retrieves a list of cards owned by the account making the request. diff --git a/lib/square/api/cash_drawers_api.rb b/lib/square_legacy/api/cash_drawers_api.rb similarity index 99% rename from lib/square/api/cash_drawers_api.rb rename to lib/square_legacy/api/cash_drawers_api.rb index 3962360c..be2b4439 100644 --- a/lib/square/api/cash_drawers_api.rb +++ b/lib/square_legacy/api/cash_drawers_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CashDrawersApi class CashDrawersApi < BaseApi # Provides the details for all of the cash drawer shifts for a location diff --git a/lib/square/api/catalog_api.rb b/lib/square_legacy/api/catalog_api.rb similarity index 99% rename from lib/square/api/catalog_api.rb rename to lib/square_legacy/api/catalog_api.rb index 7714528b..6d6c363c 100644 --- a/lib/square/api/catalog_api.rb +++ b/lib/square_legacy/api/catalog_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CatalogApi class CatalogApi < BaseApi # Deletes a set of [CatalogItem]($m/CatalogItem)s based on the diff --git a/lib/square/api/checkout_api.rb b/lib/square_legacy/api/checkout_api.rb similarity index 99% rename from lib/square/api/checkout_api.rb rename to lib/square_legacy/api/checkout_api.rb index c259df0f..64fae68f 100644 --- a/lib/square/api/checkout_api.rb +++ b/lib/square_legacy/api/checkout_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CheckoutApi class CheckoutApi < BaseApi # Links a `checkoutId` to a `checkout_page_url` that customers are diff --git a/lib/square/api/customer_custom_attributes_api.rb b/lib/square_legacy/api/customer_custom_attributes_api.rb similarity index 99% rename from lib/square/api/customer_custom_attributes_api.rb rename to lib/square_legacy/api/customer_custom_attributes_api.rb index 9a7ad0fe..74b30f85 100644 --- a/lib/square/api/customer_custom_attributes_api.rb +++ b/lib/square_legacy/api/customer_custom_attributes_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CustomerCustomAttributesApi class CustomerCustomAttributesApi < BaseApi # Lists the customer-related [custom attribute diff --git a/lib/square/api/customer_groups_api.rb b/lib/square_legacy/api/customer_groups_api.rb similarity index 99% rename from lib/square/api/customer_groups_api.rb rename to lib/square_legacy/api/customer_groups_api.rb index 109e1cd6..262cf1a2 100644 --- a/lib/square/api/customer_groups_api.rb +++ b/lib/square_legacy/api/customer_groups_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CustomerGroupsApi class CustomerGroupsApi < BaseApi # Retrieves the list of customer groups of a business. diff --git a/lib/square/api/customer_segments_api.rb b/lib/square_legacy/api/customer_segments_api.rb similarity index 99% rename from lib/square/api/customer_segments_api.rb rename to lib/square_legacy/api/customer_segments_api.rb index a00b9937..86e7707b 100644 --- a/lib/square/api/customer_segments_api.rb +++ b/lib/square_legacy/api/customer_segments_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CustomerSegmentsApi class CustomerSegmentsApi < BaseApi # Retrieves the list of customer segments of a business. diff --git a/lib/square/api/customers_api.rb b/lib/square_legacy/api/customers_api.rb similarity index 99% rename from lib/square/api/customers_api.rb rename to lib/square_legacy/api/customers_api.rb index 5f77aca2..952f5213 100644 --- a/lib/square/api/customers_api.rb +++ b/lib/square_legacy/api/customers_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # CustomersApi class CustomersApi < BaseApi # Lists customer profiles associated with a Square account. diff --git a/lib/square/api/devices_api.rb b/lib/square_legacy/api/devices_api.rb similarity index 99% rename from lib/square/api/devices_api.rb rename to lib/square_legacy/api/devices_api.rb index 508301ec..80201da9 100644 --- a/lib/square/api/devices_api.rb +++ b/lib/square_legacy/api/devices_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # DevicesApi class DevicesApi < BaseApi # List devices associated with the merchant. Currently, only Terminal API diff --git a/lib/square/api/disputes_api.rb b/lib/square_legacy/api/disputes_api.rb similarity index 99% rename from lib/square/api/disputes_api.rb rename to lib/square_legacy/api/disputes_api.rb index edede405..2cf1b0df 100644 --- a/lib/square/api/disputes_api.rb +++ b/lib/square_legacy/api/disputes_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # DisputesApi class DisputesApi < BaseApi # Returns a list of disputes associated with a particular account. diff --git a/lib/square/api/employees_api.rb b/lib/square_legacy/api/employees_api.rb similarity index 99% rename from lib/square/api/employees_api.rb rename to lib/square_legacy/api/employees_api.rb index be18b277..df7bf171 100644 --- a/lib/square/api/employees_api.rb +++ b/lib/square_legacy/api/employees_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # EmployeesApi class EmployeesApi < BaseApi # TODO: type endpoint description here diff --git a/lib/square/api/events_api.rb b/lib/square_legacy/api/events_api.rb similarity index 99% rename from lib/square/api/events_api.rb rename to lib/square_legacy/api/events_api.rb index 84c75a5c..885ae260 100644 --- a/lib/square/api/events_api.rb +++ b/lib/square_legacy/api/events_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # EventsApi class EventsApi < BaseApi # Search for Square API events that occur within a 28-day timeframe. diff --git a/lib/square/api/gift_card_activities_api.rb b/lib/square_legacy/api/gift_card_activities_api.rb similarity index 99% rename from lib/square/api/gift_card_activities_api.rb rename to lib/square_legacy/api/gift_card_activities_api.rb index b1cddd7d..1c5800ce 100644 --- a/lib/square/api/gift_card_activities_api.rb +++ b/lib/square_legacy/api/gift_card_activities_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # GiftCardActivitiesApi class GiftCardActivitiesApi < BaseApi # Lists gift card activities. By default, you get gift card activities for diff --git a/lib/square/api/gift_cards_api.rb b/lib/square_legacy/api/gift_cards_api.rb similarity index 99% rename from lib/square/api/gift_cards_api.rb rename to lib/square_legacy/api/gift_cards_api.rb index de20dc31..821afb99 100644 --- a/lib/square/api/gift_cards_api.rb +++ b/lib/square_legacy/api/gift_cards_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # GiftCardsApi class GiftCardsApi < BaseApi # Lists all gift cards. You can specify optional filters to retrieve diff --git a/lib/square/api/inventory_api.rb b/lib/square_legacy/api/inventory_api.rb similarity index 99% rename from lib/square/api/inventory_api.rb rename to lib/square_legacy/api/inventory_api.rb index 94209d22..d16a445d 100644 --- a/lib/square/api/inventory_api.rb +++ b/lib/square_legacy/api/inventory_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # InventoryApi class InventoryApi < BaseApi # Deprecated version of diff --git a/lib/square/api/invoices_api.rb b/lib/square_legacy/api/invoices_api.rb similarity index 99% rename from lib/square/api/invoices_api.rb rename to lib/square_legacy/api/invoices_api.rb index 99625792..7ec44704 100644 --- a/lib/square/api/invoices_api.rb +++ b/lib/square_legacy/api/invoices_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # InvoicesApi class InvoicesApi < BaseApi # Returns a list of invoices for a given location. The response diff --git a/lib/square/api/labor_api.rb b/lib/square_legacy/api/labor_api.rb similarity index 99% rename from lib/square/api/labor_api.rb rename to lib/square_legacy/api/labor_api.rb index dde48f81..3154b64e 100644 --- a/lib/square/api/labor_api.rb +++ b/lib/square_legacy/api/labor_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # LaborApi class LaborApi < BaseApi # Returns a paginated list of `BreakType` instances for a business. diff --git a/lib/square/api/location_custom_attributes_api.rb b/lib/square_legacy/api/location_custom_attributes_api.rb similarity index 99% rename from lib/square/api/location_custom_attributes_api.rb rename to lib/square_legacy/api/location_custom_attributes_api.rb index 83dcde57..5b8bc0e6 100644 --- a/lib/square/api/location_custom_attributes_api.rb +++ b/lib/square_legacy/api/location_custom_attributes_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # LocationCustomAttributesApi class LocationCustomAttributesApi < BaseApi # Lists the location-related [custom attribute diff --git a/lib/square/api/locations_api.rb b/lib/square_legacy/api/locations_api.rb similarity index 99% rename from lib/square/api/locations_api.rb rename to lib/square_legacy/api/locations_api.rb index 0a14c137..768164e5 100644 --- a/lib/square/api/locations_api.rb +++ b/lib/square_legacy/api/locations_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # LocationsApi class LocationsApi < BaseApi # Provides details about all of the seller's diff --git a/lib/square/api/loyalty_api.rb b/lib/square_legacy/api/loyalty_api.rb similarity index 99% rename from lib/square/api/loyalty_api.rb rename to lib/square_legacy/api/loyalty_api.rb index 6680d73a..b130f257 100644 --- a/lib/square/api/loyalty_api.rb +++ b/lib/square_legacy/api/loyalty_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # LoyaltyApi class LoyaltyApi < BaseApi # Creates a loyalty account. To create a loyalty account, you must provide diff --git a/lib/square/api/merchant_custom_attributes_api.rb b/lib/square_legacy/api/merchant_custom_attributes_api.rb similarity index 99% rename from lib/square/api/merchant_custom_attributes_api.rb rename to lib/square_legacy/api/merchant_custom_attributes_api.rb index ac687ab0..7dbcc2ed 100644 --- a/lib/square/api/merchant_custom_attributes_api.rb +++ b/lib/square_legacy/api/merchant_custom_attributes_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # MerchantCustomAttributesApi class MerchantCustomAttributesApi < BaseApi # Lists the merchant-related [custom attribute diff --git a/lib/square/api/merchants_api.rb b/lib/square_legacy/api/merchants_api.rb similarity index 99% rename from lib/square/api/merchants_api.rb rename to lib/square_legacy/api/merchants_api.rb index fd3b7b40..ae71660d 100644 --- a/lib/square/api/merchants_api.rb +++ b/lib/square_legacy/api/merchants_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # MerchantsApi class MerchantsApi < BaseApi # Provides details about the merchant associated with a given access token. diff --git a/lib/square/api/mobile_authorization_api.rb b/lib/square_legacy/api/mobile_authorization_api.rb similarity index 98% rename from lib/square/api/mobile_authorization_api.rb rename to lib/square_legacy/api/mobile_authorization_api.rb index bb8f2f51..09747b3c 100644 --- a/lib/square/api/mobile_authorization_api.rb +++ b/lib/square_legacy/api/mobile_authorization_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # MobileAuthorizationApi class MobileAuthorizationApi < BaseApi # Generates code to authorize a mobile application to connect to a Square diff --git a/lib/square/api/o_auth_api.rb b/lib/square_legacy/api/o_auth_api.rb similarity index 99% rename from lib/square/api/o_auth_api.rb rename to lib/square_legacy/api/o_auth_api.rb index 5af1becd..555d4757 100644 --- a/lib/square/api/o_auth_api.rb +++ b/lib/square_legacy/api/o_auth_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # OAuthApi class OAuthApi < BaseApi # Revokes an access token generated with the OAuth flow. diff --git a/lib/square/api/order_custom_attributes_api.rb b/lib/square_legacy/api/order_custom_attributes_api.rb similarity index 99% rename from lib/square/api/order_custom_attributes_api.rb rename to lib/square_legacy/api/order_custom_attributes_api.rb index c79aa40b..43f023b5 100644 --- a/lib/square/api/order_custom_attributes_api.rb +++ b/lib/square_legacy/api/order_custom_attributes_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # OrderCustomAttributesApi class OrderCustomAttributesApi < BaseApi # Lists the order-related [custom attribute diff --git a/lib/square/api/orders_api.rb b/lib/square_legacy/api/orders_api.rb similarity index 99% rename from lib/square/api/orders_api.rb rename to lib/square_legacy/api/orders_api.rb index f3ffe7fd..75e23f46 100644 --- a/lib/square/api/orders_api.rb +++ b/lib/square_legacy/api/orders_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # OrdersApi class OrdersApi < BaseApi # Creates a new [order]($m/Order) that can include information about diff --git a/lib/square/api/payments_api.rb b/lib/square_legacy/api/payments_api.rb similarity index 99% rename from lib/square/api/payments_api.rb rename to lib/square_legacy/api/payments_api.rb index ab6a1cb2..b97bb4fc 100644 --- a/lib/square/api/payments_api.rb +++ b/lib/square_legacy/api/payments_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # PaymentsApi class PaymentsApi < BaseApi # Retrieves a list of payments taken by the account making the request. diff --git a/lib/square/api/payouts_api.rb b/lib/square_legacy/api/payouts_api.rb similarity index 99% rename from lib/square/api/payouts_api.rb rename to lib/square_legacy/api/payouts_api.rb index fa1dd2b7..5080025c 100644 --- a/lib/square/api/payouts_api.rb +++ b/lib/square_legacy/api/payouts_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # PayoutsApi class PayoutsApi < BaseApi # Retrieves a list of all payouts for the default location. diff --git a/lib/square/api/refunds_api.rb b/lib/square_legacy/api/refunds_api.rb similarity index 99% rename from lib/square/api/refunds_api.rb rename to lib/square_legacy/api/refunds_api.rb index 29fc55a6..32841c86 100644 --- a/lib/square/api/refunds_api.rb +++ b/lib/square_legacy/api/refunds_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # RefundsApi class RefundsApi < BaseApi # Retrieves a list of refunds for the account making the request. diff --git a/lib/square/api/sites_api.rb b/lib/square_legacy/api/sites_api.rb similarity index 98% rename from lib/square/api/sites_api.rb rename to lib/square_legacy/api/sites_api.rb index af81b112..0fed827a 100644 --- a/lib/square/api/sites_api.rb +++ b/lib/square_legacy/api/sites_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # SitesApi class SitesApi < BaseApi # Lists the Square Online sites that belong to a seller. Sites are listed in diff --git a/lib/square/api/snippets_api.rb b/lib/square_legacy/api/snippets_api.rb similarity index 99% rename from lib/square/api/snippets_api.rb rename to lib/square_legacy/api/snippets_api.rb index dc0d9dd6..b49e0b0e 100644 --- a/lib/square/api/snippets_api.rb +++ b/lib/square_legacy/api/snippets_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # SnippetsApi class SnippetsApi < BaseApi # Removes your snippet from a Square Online site. diff --git a/lib/square/api/subscriptions_api.rb b/lib/square_legacy/api/subscriptions_api.rb similarity index 99% rename from lib/square/api/subscriptions_api.rb rename to lib/square_legacy/api/subscriptions_api.rb index 6a35d7df..d93ab7af 100644 --- a/lib/square/api/subscriptions_api.rb +++ b/lib/square_legacy/api/subscriptions_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # SubscriptionsApi class SubscriptionsApi < BaseApi # Enrolls a customer in a subscription. diff --git a/lib/square/api/team_api.rb b/lib/square_legacy/api/team_api.rb similarity index 99% rename from lib/square/api/team_api.rb rename to lib/square_legacy/api/team_api.rb index 6da50d73..a39ec7e8 100644 --- a/lib/square/api/team_api.rb +++ b/lib/square_legacy/api/team_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # TeamApi class TeamApi < BaseApi # Creates a single `TeamMember` object. The `TeamMember` object is returned diff --git a/lib/square/api/terminal_api.rb b/lib/square_legacy/api/terminal_api.rb similarity index 99% rename from lib/square/api/terminal_api.rb rename to lib/square_legacy/api/terminal_api.rb index 5b575823..71e03d05 100644 --- a/lib/square/api/terminal_api.rb +++ b/lib/square_legacy/api/terminal_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # TerminalApi class TerminalApi < BaseApi # Creates a Terminal action request and sends it to the specified device. diff --git a/lib/square/api/transactions_api.rb b/lib/square_legacy/api/transactions_api.rb similarity index 99% rename from lib/square/api/transactions_api.rb rename to lib/square_legacy/api/transactions_api.rb index db070549..9526b1eb 100644 --- a/lib/square/api/transactions_api.rb +++ b/lib/square_legacy/api/transactions_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # TransactionsApi class TransactionsApi < BaseApi # Lists transactions for a particular location. diff --git a/lib/square/api/v1_transactions_api.rb b/lib/square_legacy/api/v1_transactions_api.rb similarity index 99% rename from lib/square/api/v1_transactions_api.rb rename to lib/square_legacy/api/v1_transactions_api.rb index c60b0e1d..d20efe29 100644 --- a/lib/square/api/v1_transactions_api.rb +++ b/lib/square_legacy/api/v1_transactions_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # V1TransactionsApi class V1TransactionsApi < BaseApi # Provides summary information for a merchant's online store orders. diff --git a/lib/square/api/vendors_api.rb b/lib/square_legacy/api/vendors_api.rb similarity index 99% rename from lib/square/api/vendors_api.rb rename to lib/square_legacy/api/vendors_api.rb index 6a0f3e8d..d9e359f2 100644 --- a/lib/square/api/vendors_api.rb +++ b/lib/square_legacy/api/vendors_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # VendorsApi class VendorsApi < BaseApi # Creates one or more [Vendor]($m/Vendor) objects to represent suppliers to diff --git a/lib/square/api/webhook_subscriptions_api.rb b/lib/square_legacy/api/webhook_subscriptions_api.rb similarity index 99% rename from lib/square/api/webhook_subscriptions_api.rb rename to lib/square_legacy/api/webhook_subscriptions_api.rb index 42d509b1..82d8ac00 100644 --- a/lib/square/api/webhook_subscriptions_api.rb +++ b/lib/square_legacy/api/webhook_subscriptions_api.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # WebhookSubscriptionsApi class WebhookSubscriptionsApi < BaseApi # Lists all webhook event types that can be subscribed to. diff --git a/lib/square/api_helper.rb b/lib/square_legacy/api_helper.rb similarity index 78% rename from lib/square/api_helper.rb rename to lib/square_legacy/api_helper.rb index 00fa0349..0f352022 100644 --- a/lib/square/api_helper.rb +++ b/lib/square_legacy/api_helper.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # API utility class class APIHelper < CoreLibrary::ApiHelper end diff --git a/lib/square/client.rb b/lib/square_legacy/client.rb similarity index 99% rename from lib/square/client.rb rename to lib/square_legacy/client.rb index 50235381..a96c4b6d 100644 --- a/lib/square/client.rb +++ b/lib/square_legacy/client.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # square client class. class Client include CoreLibrary diff --git a/lib/square/configuration.rb b/lib/square_legacy/configuration.rb similarity index 99% rename from lib/square/configuration.rb rename to lib/square_legacy/configuration.rb index d0062870..6a657b15 100644 --- a/lib/square/configuration.rb +++ b/lib/square_legacy/configuration.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # All configuration including auth info and base URI for the API access # are configured in this class. class Configuration < CoreLibrary::HttpClientConfiguration diff --git a/lib/square/exceptions/api_exception.rb b/lib/square_legacy/exceptions/api_exception.rb similarity index 87% rename from lib/square/exceptions/api_exception.rb rename to lib/square_legacy/exceptions/api_exception.rb index edb92a1b..48e4b9ed 100644 --- a/lib/square/exceptions/api_exception.rb +++ b/lib/square_legacy/exceptions/api_exception.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # Class for exceptions when there is a network error, status code error, etc. class APIException < CoreLibrary::ApiException end diff --git a/lib/square/http/api_response.rb b/lib/square_legacy/http/api_response.rb similarity index 98% rename from lib/square/http/api_response.rb rename to lib/square_legacy/http/api_response.rb index bfc40a6d..3e087d6a 100644 --- a/lib/square/http/api_response.rb +++ b/lib/square_legacy/http/api_response.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # Http response received. class ApiResponse < CoreLibrary::ApiResponse attr_reader :body, :cursor diff --git a/lib/square/http/auth/o_auth2.rb b/lib/square_legacy/http/auth/o_auth2.rb similarity index 98% rename from lib/square/http/auth/o_auth2.rb rename to lib/square_legacy/http/auth/o_auth2.rb index 7011dd4d..b49506b6 100644 --- a/lib/square/http/auth/o_auth2.rb +++ b/lib/square_legacy/http/auth/o_auth2.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # Utility class for OAuth 2 authorization and token management. class OAuth2 < CoreLibrary::HeaderAuth include CoreLibrary diff --git a/lib/square/http/http_call_back.rb b/lib/square_legacy/http/http_call_back.rb similarity index 86% rename from lib/square/http/http_call_back.rb rename to lib/square_legacy/http/http_call_back.rb index 36e0c6ff..67c53633 100644 --- a/lib/square/http/http_call_back.rb +++ b/lib/square_legacy/http/http_call_back.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # HttpCallBack allows defining callables for pre and post API calls. class HttpCallBack < CoreLibrary::HttpCallback end diff --git a/lib/square/http/http_method_enum.rb b/lib/square_legacy/http/http_method_enum.rb similarity index 81% rename from lib/square/http/http_method_enum.rb rename to lib/square_legacy/http/http_method_enum.rb index dad06b99..7974003b 100644 --- a/lib/square/http/http_method_enum.rb +++ b/lib/square_legacy/http/http_method_enum.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # HTTP Methods Enumeration. class HttpMethodEnum < CoreLibrary::HttpMethod end diff --git a/lib/square/http/http_request.rb b/lib/square_legacy/http/http_request.rb similarity index 82% rename from lib/square/http/http_request.rb rename to lib/square_legacy/http/http_request.rb index 40c61bb2..329ddc6b 100644 --- a/lib/square/http/http_request.rb +++ b/lib/square_legacy/http/http_request.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # Represents a single Http Request. class HttpRequest < CoreLibrary::HttpRequest end diff --git a/lib/square/http/http_response.rb b/lib/square_legacy/http/http_response.rb similarity index 81% rename from lib/square/http/http_response.rb rename to lib/square_legacy/http/http_response.rb index 53d746ff..4bddfbcf 100644 --- a/lib/square/http/http_response.rb +++ b/lib/square_legacy/http/http_response.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # Http response received. class HttpResponse < CoreLibrary::HttpResponse end diff --git a/lib/square/utilities/date_time_helper.rb b/lib/square_legacy/utilities/date_time_helper.rb similarity index 88% rename from lib/square/utilities/date_time_helper.rb rename to lib/square_legacy/utilities/date_time_helper.rb index 26f65ace..f7940187 100644 --- a/lib/square/utilities/date_time_helper.rb +++ b/lib/square_legacy/utilities/date_time_helper.rb @@ -1,5 +1,5 @@ require 'date' -module Square +module SquareLegacy # A utility that supports dateTime conversion to different formats class DateTimeHelper < CoreLibrary::DateTimeHelper end diff --git a/lib/square/utilities/file_wrapper.rb b/lib/square_legacy/utilities/file_wrapper.rb similarity index 94% rename from lib/square/utilities/file_wrapper.rb rename to lib/square_legacy/utilities/file_wrapper.rb index c6d2ce94..68cd20e9 100644 --- a/lib/square/utilities/file_wrapper.rb +++ b/lib/square_legacy/utilities/file_wrapper.rb @@ -1,4 +1,4 @@ -module Square +module SquareLegacy # A utility to allow users to set the content-type for files class FileWrapper < CoreLibrary::FileWrapper # The constructor. diff --git a/lib/square/utilities/webhooks_helper.rb b/lib/square_legacy/utilities/webhooks_helper.rb similarity index 97% rename from lib/square/utilities/webhooks_helper.rb rename to lib/square_legacy/utilities/webhooks_helper.rb index ddfb9c7f..365c7b04 100644 --- a/lib/square/utilities/webhooks_helper.rb +++ b/lib/square_legacy/utilities/webhooks_helper.rb @@ -1,7 +1,7 @@ require 'openssl' require 'base64' -module Square +module SquareLegacy class WebhooksHelper def self.is_valid_webhook_event_signature(request_body, signature_header, signature_key, notification_url) return false if request_body.nil? diff --git a/spec/user_journey_spec.rb b/spec/user_journey_spec.rb index d68f6eb9..7e36dd4b 100644 --- a/spec/user_journey_spec.rb +++ b/spec/user_journey_spec.rb @@ -30,11 +30,11 @@ end let :sq do - Square::Client.new(access_token: access_token, environment: environment) + SquareLegacy::Client.new(access_token: access_token, environment: environment) end let :unauthoerized_sq do - Square::Client.new(access_token: "bad_token") + SquareLegacy::Client.new(access_token: "bad_token") end let :customer2 do @@ -77,7 +77,7 @@ # access_token = "your_production_access_token" # name1 = "fruit" # name2 = "drink" - # api = Square::Client.new(access_token: access_token).v1_items + # api = SquareLegacy::Client.new(access_token: access_token).v1_items # # # create # response = api.create_category(location_id: location_id, body: {name: name1}) diff --git a/test/api/api_test_base.rb b/test/api/api_test_base.rb index 098453e3..b078f38a 100644 --- a/test/api/api_test_base.rb +++ b/test/api/api_test_base.rb @@ -3,12 +3,12 @@ require 'minitest/hell' require 'minitest/pride' require 'minitest/proveit' -require 'square' +require 'square_legacy' require_relative '../http_response_catcher' class ApiTestBase < Minitest::Test parallelize_me! - include Square + include SquareLegacy include CoreLibrary # Create configuration and set any test parameters diff --git a/test/http_response_catcher.rb b/test/http_response_catcher.rb index 7c4d15f4..8f9b6b59 100644 --- a/test/http_response_catcher.rb +++ b/test/http_response_catcher.rb @@ -1,4 +1,4 @@ -class HttpResponseCatcher < Square::HttpCallBack +class HttpResponseCatcher < SquareLegacy::HttpCallBack attr_accessor :response def on_before_request(request) diff --git a/test/webhooks/test_webhooks_helper.rb b/test/webhooks/test_webhooks_helper.rb index ce38ae26..b61faa5f 100644 --- a/test/webhooks/test_webhooks_helper.rb +++ b/test/webhooks/test_webhooks_helper.rb @@ -1,4 +1,4 @@ -require_relative '../../lib/square/utilities/webhooks_helper.rb' +require_relative '../../lib/square_legacy/utilities/webhooks_helper.rb' require 'minitest/autorun' require 'minitest/hell' require 'minitest/pride' @@ -18,7 +18,7 @@ def setup def test_signature_validation_pass @logger.info('Running test_signature_validation_pass') # Log a message - is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature( + is_valid = SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, @signature_header, @signature_key, @@ -35,7 +35,7 @@ def test_signature_validation_escaped_pass signatureKey = "signature-key"; url = "https://webhook.site/webhooks"; - is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature( + is_valid = SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( escpaedRequestBody, newSignatureHeader, signatureKey, @@ -46,7 +46,7 @@ def test_signature_validation_escaped_pass def test_signature_validation_fails_on_notification_url_mismatch @logger.info('Running test_signature_validation_fails_on_notification_url_mismatch') # Log a message - is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature( + is_valid = SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, @signature_header, @signature_key, @@ -57,7 +57,7 @@ def test_signature_validation_fails_on_notification_url_mismatch def test_signature_validation_fails_on_invalid_signature_key @logger.info('Running test_signature_validation_fails_on_invalid_signature_key') # Log a message - is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature( + is_valid = SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, @signature_header, 'MCmhFRxGX82xMwg5FsaoQA', @@ -67,7 +67,7 @@ def test_signature_validation_fails_on_invalid_signature_key end def test_signature_validation_fails_on_invalid_signature_header - is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature( + is_valid = SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, '1z2n3DEJJiUPKcPzQo1ftvbxGdw=', @signature_key, @@ -78,7 +78,7 @@ def test_signature_validation_fails_on_invalid_signature_header def test_signature_validation_fails_on_request_body_mismatch request_body = '{"merchant_id":"MLEFBHHSJGVHD","type":"webhooks.test_notification","event_id":"ac3ac95b-f97d-458c-a6e6-18981597e05f","created_at":"2022-06-13T20:30:59.037339943Z","data":{"type":"webhooks","id":"bc368e64-01aa-407e-b46e-3231809b1129"}}' - is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature( + is_valid = SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( request_body, @signature_header, @signature_key, @@ -98,7 +98,7 @@ def test_signature_validation_fails_on_request_body_formatted "id": "bc368e64-01aa-407e-b46e-3231809b1129" } }' - is_valid = Square::WebhooksHelper.is_valid_webhook_event_signature( + is_valid = SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( request_body, @signature_header, @signature_key, @@ -109,7 +109,7 @@ def test_signature_validation_fails_on_request_body_formatted def test_throws_error_on_empty_signature_key assert_raises(RuntimeError, 'signature_key is null or empty') do - Square::WebhooksHelper.is_valid_webhook_event_signature( + SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, @signature_header, '', @@ -120,7 +120,7 @@ def test_throws_error_on_empty_signature_key def test_throws_error_on_signature_key_not_configured assert_raises(RuntimeError) do - Square::WebhooksHelper.is_valid_webhook_event_signature( + SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, @signature_header, nil, @@ -131,7 +131,7 @@ def test_throws_error_on_signature_key_not_configured def test_throws_error_on_empty_notification_url assert_raises(RuntimeError, 'notification_url is null or empty') do - Square::WebhooksHelper.is_valid_webhook_event_signature( + SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, @signature_header, @signature_key, @@ -142,7 +142,7 @@ def test_throws_error_on_empty_notification_url def test_throws_error_on_notification_url_not_configured assert_raises(RuntimeError) do - Square::WebhooksHelper.is_valid_webhook_event_signature( + SquareLegacy::WebhooksHelper.is_valid_webhook_event_signature( @request_body, @signature_header, @signature_key,