Skip to content

Commit

Permalink
Update README with FAQ
Browse files Browse the repository at this point in the history
  • Loading branch information
@juanpprieto
juanpprieto committed Feb 3, 2025
1 parent c99bf7e commit 89a754b
Showing 1 changed file with 82 additions and 41 deletions.
123 changes: 82 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,59 +40,91 @@ To validate that the upgrade was successful or that your are using v3.0, open yo

In addition you can check that the client is using the Cart API by monitoring the network tab on your preferred developer tools when adding a line item to the cart. If you see that the operation performed was `cartLinesAdd` rather than `checkoutCreate`, then you are using v3.0.

## Updated SDK Checkout interface
## FAQ

Prior to v3.0 the SDK [checkout interface](https://shopify.github.io/js-buy-sdk/#creating-a-checkout) used the [deprecated](https://shopify.dev/changelog/deprecation-of-checkout-apis) [Checkout API](https://shopify.dev/docs/api/storefront/2024-04/objects/Checkout) to handle both Cart and Checkout use cases. This updated `.checkout` interface is now based on the Cart API, which means that it can only handle Cart use cases supported by the current API.
### Why is the JS Buy SDK being deprecated?

## Cart-based checkout object compatibility
We know the important role the JS Buy SDK library played in allowing merchants to create e-commerce experiences. When it was first released in 2016, our main priority was to provide quick and easy ways to interact with our GraphQL APIs. However, over the years, a lot has changed and the SDK is no longer the optimal client to fully leverage all of Shopify capabilities.

The following table highlights the supported and _unsupported_ fields returned in the cart-driven checkout object
### What do I need to do now?

| field | compatibility | notes |
|---|---|---|
| appliedGiftCards | ✅ | |
| createdAt | ✅ | |
| currencyCode | ✅ | |
| customAttributes | ✅ | |
| discountApplications | ✅ | |
| email | ✅ | |
| id | ✅ℹ️ | The return ID will be a Cart ID e.g `gid://shopify/Cart/...` |
| lineItems | ✅ | |
| lineItemsSubtotalPrice | ✅ | |
| note | ✅ | |
| paymentDue | ✅ | |
| paymentDueV2 | ✅ | |
| shippingAddress | ✅ | |
| subtotalPrice | ✅ | |
| subtotalPriceV2 | ✅ | |
| totalPrice | ✅ | |
| totalPriceV2 | ✅ | |
| totalTax | ✅ | |
| totalTaxV2 | ✅ | |
| updatedAt | ✅ | |
| webUrl | ✅ | |

Fields _not_ supported

| field | compatibility | notes |
You have multiple options: a) switch to the Storefront API Client, our recommendation and more future-proof solution; see [our migration guide](https://github.com/Shopify/js-buy-sdk/tree/sd-deprecation/migration-guide) to help you transition, [docs](https://github.com/Shopify/shopify-app-js/tree/main/packages/api-clients/storefront-api-client#readme), [NPM package](https://www.npmjs.com/package/@shopify/storefront-api-client) or b) upgrade to JS Buy SDK V3, our last and final release of the JS Buy SDK library. See [this upgrade guide](https://github.com/Shopify/js-buy-sdk/blob/main/README.md##how-to-upgrade-to-v30) to install v3.0. c) switch to [one of our other solutions](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/getting-started).

Shopify has evolved since the JS Buy SDK was first released, so we encourage you to explore and determine if one of our themes for an Online Store is a better fit for your needs. This action must be completed before July 1, 2025 11:00 AM ET.

### Something’s gone wrong and I’m not sure what it is. Is the JS Buy SDK the reason?

The only functionality that should be affected is the cart and checkout. For example, customers can’t complete purchases or the website crashes when a customer attempts to add to cart or view their cart. Other possible issues could be related to any existing workflows that rely on the `.order`, `.completedAt` or any other no longer supported Checkout specific fields. We have set these fields to their default values to mitigate any breaking changes, but we can’t guarantee all existing functionality.

### What if I run into issues upgrading?

You may be using one of the fields that is no longer supported in JS Buy SDK v3.0. If you are not a developer, we recommend contacting the people who last worked on your store, whether that was to initially build it or help maintain it over time. If you are looking to work with an agency, check out our [partner directory](https://www.shopify.com/partners/directory) for more information.

### How do I find out if my store is using JS Buy SDK?

If your store is affected, you would have received an email from us. Another way to verify is to search for `shopify-buy` in your codebase or the snippets you embedded into your site. If this is not possible, then we recommend contacting a third-party partner.

### I think I’m on an earlier version of JS Buy SDK. How do I upgrade to v3.0?

We’d recommend reviewing our [changelog](https://github.com/Shopify/js-buy-sdk/blob/main/CHANGELOG.md) to first upgrade your store to v2.22.0 of the JS Buy SDK, and then upgrade to v3.0 after that. In addition, we are constantly evolving our [solutions](https://www.shopify.com/online) and we encourage you to explore them and see if one might better fit your needs.

### What happens if I do not take any action?

If you do not take any action before `July 1, 2025 11:00 AM ET`, your store will lose the ability for customers to complete purchases and your site may become unavailable for users with existing carts.


### I read that the Checkout API is being deprecated in April 2025, but the JS Buy SDK that uses Checkout APIs is being deprecated on July 1, 2025. Which date is it? and what if I can’t complete the upgrade by April?

All merchants using JS Buy SDK will be granted an automatic one-time extension to complete the switch to v3.0 before July 1, 2025 at 11:00 AM ET. The JS Buy SDK v3.0 update removes the dependency on Checkout APIs and replaces them with Cart APIs. This means that when you call methods on the Checkout resource, they’ll use Cart APIs instead. We did our best to keep the inputs and outputs the same, but some features from the Checkout APIs do not have a Cart API equivalent, so please test thoroughly after upgrading.

### How long will JS Buy SDK v3.0 be supported?

JS Buy SDK v3.0 will be supported until January 1, 2026. Upgrading to JS Buy SDK v3.0 should be considered a short-term solution before implementing a long-term solution such as [Storefront Client](https://github.com/Shopify/shopify-app-js/tree/main/packages/api-clients/storefront-api-client#readme), [Hydrogen](https://hydrogen.shopify.dev/), or [Storefront Web Components](https://shopify.dev/docs/storefronts/headless/additional-sdks/web-components) or [Online Store Editor](https://www.shopify.com/website/builder).

### Why would I upgrade to JS Buy SDK v3.0 if it’s the last and final release?

This option is the easiest and fastest way to remain functional and give you more time to consider, plan and implement a better long-term solution such as using the Storefront Client.


### How long will it take to migrate to Storefront API Client?

This will heavily depend on your e-commerce experience and what level of technical resources you have available. If you do not have access to technical resources or are unsure where to begin, you can review the [migration guide](https://github.com/Shopify/js-buy-sdk/tree/sd-deprecation/migration-guide), or contact a [third-party agency](https://www.shopify.com/partners/directory) who could provide consultation.

### How will I know I have successfully switched to JS Buy SDK v3.0?

Once you have updated your project to use v3.0, you can check your package.json to ensure that the `shopify-buy` dependency is now at 3.0.0. In addition you can check that the client is using the Cart API by monitoring the network tab of your preferred developer tools when adding a line item to the cart. If you see that the operation performed was `cartLinesAdd` rather than `checkoutCreate`, then you have switched to v3.0 successfully. [More information](https://github.com/Shopify/js-buy-sdk#how-validate-that-i-am-using-v30)

### I’m debating if I should migrate to the Storefront API Client. What are the benefits?

Migrating to the Storefront API Client is a great way to future-proof your e-commerce experience by gaining full control on how your store interacts with Shopify APIs. You will get access to [globally-deployed Carts](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage), offering improved performance, scalability, and a richer feature set including subscriptions, product bundles, contextual pricing, Shopify Functions, and UI extensions, and more. In addition, we have other solutions available that might better fit your needs like Hydrogen, Storefront Web Components or Online Store Editor.

### How will I know my e-commerce experience will still work after I take action?

If you migrate to Storefront API Client, there is virtually no use case that can’t be addressed with the right technical implementation. Upfront planning and following the migration guide will be critical to a smooth successful migration. If you decide to switch to the JS Buy SDK v3.0, the majority of use cases should still work successfully, but there’s no guarantee it will work with future Shopify features. Additionally, there are several fields that are no longer compatible:

#### Fields no longer supported

| field | compatibility | notes | solution? |
|---|---|---|
| completedAt | ⚠️ | Not supported. Defaults to `null` |
| order | ⚠️ | Not supported. Defaults to `null` |
| orderStatusUrl | ⚠️ | Not supported. Defaults to `null` |
| ready | ⚠️ | Not supported. Defaults to `false` |
| requiresShipping | ⚠️ | Not supported. Defaults to `true` |
| shippingLine | ⚠️ | Not supported. Defaults to `null` |
| taxExempt | ⚠️ | Not supported. Defaults to `false` |
| taxesIncluded | ⚠️ | Not supported. Defaults to `false` |
| completedAt | ⚠️ | Not supported. Defaults to `null` | The Cart API does not maintain the state of a completed Cart that became an order. |
| order | ⚠️ | Not supported. Defaults to `null` | To retrieve customer orders, please use either the [Customer Account API](https://shopify.dev/docs/api/customer) or the legacy [Customer API](https://shopify.dev/docs/api/storefront/2025-01/objects/customer). |
| orderStatusUrl | ⚠️ | Not supported. Defaults to `null` | same as above |
| ready | ⚠️ | Not supported. Defaults to `false` | The [Cart API](https://shopify.dev/docs/api/storefront/2025-01/objects/cart) returns only carts that are considered ready. Simply bypass or remove any existing code depending on this field. |
| requiresShipping | ⚠️ | Not supported. Defaults to `true` | The [Cart API](https://shopify.dev/docs/api/storefront/2025-01/objects/cart) does not contain shipping information, this is currently handled in the Checkout flow. Remove any existing code depending on these fields. |
| shippingLine | ⚠️ | Not supported. Defaults to `null` | same as above |
| taxExempt | ⚠️ | Not supported. Defaults to `false` |
The [Cart API](https://shopify.dev/docs/api/storefront/2025-01/objects/cart) does not have Tax aware as this is currently handled in the Checkout flow. Remove any existing code depending on this field. |
| taxesIncluded | ⚠️ | Not supported. Defaults to `false` | same as above |

### Updated `.checkout` methods compatibility table

#### Updated `.checkout` methods

The updated checkout interface supports all existing methods with some limitations:

| method | compatibility | notes |
|---|---|---|
| fetch | ✅ | |
| create | ✅⚠️ | - Does not create a localized checkout when passing `presentmentCurrencyCode` <br /> - Does not localize an _empty_ checkout created with `buyerIdentity.countryCode`. (Must create with lineItems) |
| create | ✅⚠️ | - Does not create localized checkouts when passing `presentmentCurrencyCode` <br /> - Does not localize an _empty_ checkout created with `buyerIdentity.countryCode`. (Must create with lineItems) |
| updateAttributes | ✅⚠️ | - It does not update a checkout to support `allowPartialAddresses` |
| updateEmail | ✅ | |
| addLineItems | ✅ | |
Expand All @@ -105,6 +137,15 @@ The updated checkout interface supports all existing methods with some limitatio
| removeGiftCard | ✅ | |
| updateShippingAddress | ✅ | |


### [after July 1] I’m very upset! My customers are not able to complete their purchases. What’s going on?

If your customers are not able to complete purchases, we recommend you first verify if your e-commerce experience is using the JS Buy SDK. You can verify this by checking the `package.json` as highlighted in our validation guide. If this is the case, then there are two options available:

a. Switch to the [Storefront API Client](https://github.com/Shopify/shopify-app-js/tree/main/packages/api-clients/storefront-api-client#readme), which manages the API's authentication information and provides various methods that enable devs to interact with the API. This is the preferred and more future-proof solution.

b. Upgrade to JS Buy SDK v3.0. This latest version will work for most use cases and the process is more straightforward. We created a [migration guide](https://github.com/Shopify/js-buy-sdk/tree/sd-deprecation/migration-guide) to help you upgrade.

---

![Build](https://github.com/shopify/js-buy-sdk/actions/workflows/ci.yml/badge.svg)
Expand Down

0 comments on commit 89a754b

Please sign in to comment.