Migrating from version 1

The following are the main areas of change between SDK version 1 and 2. You will need to update your code to address these changes. Some functionality that was deprecated in 1.1 and 1.2 releases has been removed. Some new functionality has been added. The names of various methods, classes and properties have been changed as well.

Initializing the API Client

When creating the API client (instance of BUYClient), you are required to provide the app ID, instead of the channel ID. The App ID is simply the string "8". It is the same for all shops. Your API key should be unchanged.

As well, the BuyClientFactory has been removed and replaced with a fluent builder pattern using BuyClientBuilder.

BuyClient buyClient = new BuyClientBuilder()


As part of the update to Retrofit 2.0, the Callback object used to return results from the API was changed. To update your code you will need to change your imports to replace import retrofit.Callback; with import com.shopify.buy.dataprovider.Callback;.

The success function has also changed:

Version 1.x:

void success(T data, retrofit.client.Response response)

Version 2.x:

void success(T data)

Where T is the type of Object returned from the API.


Error response and handling has been improved. The Retrofit Error is not longer directly returned in the Callbacks, and has been replaced by BuyClientError.

Model Definition Changes

Various changes have been made to the data model. You will need to update your code to use the new names. In some cases, you will need to update for a type change. The data type used for id in models have been normalized and are now consistently Longs.

Checkout and ShippingRates

Some API client methods have changed their arguments and naming. Methods which formerly took a checkout object, but did not modify or update the checkout, now only take the checkout token. This is to avoid any ambiguity or suggestion that changes to the checkout would be propagated. If you change your checkout directly, always be sure to update it with the API client to sync your changes to Shopify.

In prior versions of the SDK, it was necessary to periodically check the status of a completed checkout until it had finished processing. Now the SDK does that work for you. Similarly, if you request updated shipping rates, the SDK will not return until the new shipping rates are ready.

Product Details UI

The SDK has been streamlined and the UI components have been removed. The ProductDetailsActivity, ProductDetailsFragment, and other custom views have been moved into the Sample App. These classes are best used as demonstration code. If you use these classes in your app, you should copy them from the Sample code, and customize them as necessary.


The BuyClient has been updated to take a PaymentToken in completeCheckout instead of a session id. The PaymentToken is returned from the storeCreditCard function.

Fetching Collections and Products

The method getProductPage has been renamed to getProducts, and the getCollections method is now paginated.