v3 migration guide

Basics

You can upgrade your shopping cart integration to Snipcart's latest version, v3, released in Oct. 2019.

There are a few reasons to upgrade. The most apparent change is the user interface of the cart. The new design is sober and built to fit most websites with little modifications. We followed the best UX practices for a conversion-centric checkout flow and used a mobile-first approach.

You can more easily override cart templates for a full-page checkout, a small, centered modal, a slide-in cart, etc.!

We also made it easier to inject your aesthetics through the checkout. From colors and animations to adding or deleting fields, you can do lots of stuff. We now have an HTML-like syntax making it easy to play with cart components.

Finally, it doesn't depend on any third-party libraries in the global scope, such as jQuery.

Keep in mind that despite the advantages, there is no immediate need to upgrade; if you are satisfied with your current integration, we'll continue to support the v2 for the foreseeable future.

However, new features added inside v3 won't be ported over to the v2.

Migration steps

If you haven't customized your cart, migrating from v2 to v3 is, in most cases, as simple as swapping the installation script found in this entry.

Most of the product definition attributes behave in the same way, except for a few exceptions listed below.

If you've applied any customization to your cart, you can read our breaking changes section to identify modifications that require an action on your end.

Breaking changes

While migrating your current integration, some changes will require your attention:

Installation

  • You need to specify the placement of the cart inside your markup as well as specifying the API key. Check out our installation guide for more details.
  • jQuery can be removed from the installation if it isn't necessary for your website. It isn't a dependency for Snipcart v3.
  • Order custom fields need to be moved from the installation script to the Snipcart div and transformed from attributes to HTML tags. Read this entry for more details.

Product definition

  • The data-item-categories attribute is no longer comma separated. You can use pipes (|) to separate any categories.
  • The data-item-stackable attribute isn't boolean anymore, but a string that describes the different possible behaviors. Read this entry for more details.

Cart summary and customer dashboard

  • The snipcart-total-items has been renamed to snipcart-items-count.

Customization

To allow this improved user experience, we had to rebuild the cart from scratch. Hence why the markup and styles have changed, and not every customization can be ported into this new installation. That being said, it should now be easier to customize the cart to fit your branding. Check out this entry for more details.

Style customization

Just like its predecessor, you can modify the styling of the cart v3 by adding or overriding any CSS in Snipcart's CSS rules. We recommended you to use the developer tools offered by your browser to figure out which classes to target, to apply the desired changes.

Markup customization

If you used direct DOM manipulations to insert or edit HTML inside the cart, you'll need to use our customization feature to port over these changes. To learn more about this functionality, you can read this entry.

JavaScript API

The JavaScript API, now called JavaScript SDK, has been rebuilt and reorganized. Most methods can be found in the new SDK under a different name.

Most use cases can be replicated using this new SDK, but we're still working on providing relevant features, such as events, to accommodate all possible scenarios.

Localization

We have revamped our localization system; it's now easier to support multiple languages and regionals. You can read this entry for more information.

The community contributions for the v3 can be found in this new repository. The localization file format is much improved.

Unsupported features

It's also worth noting that there are still a few features, previously available with the v2, that are currently under development:

  • Custom validation

To get updated on any future development, you can subscribe to our newsletter, or keep track of our release notes.

Some payment gateways won't be ported inside the v3, but are available using our custom payment gateway functionality:

  • Pin payments
  • Paymill
  • Paysafe

If you have any unanswered questions, feel free to drop us a line at geeks@snipcart.com or through our live chat support. Our developers will gladly answer any questions or concerns you might have while migrating.

Was this article helpful?