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. And names of various methods, classes and properties have been changed.

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.

Fetching Collections

The method -getCollections: has been removed. Use -getCollectionsPage:completion:.

Models Object Creation

A new class has been introduced, BUYModelManager, which adopts the related protocol of the same name. The BUYClient adds a new property, modelManager, which references an object of this type. This property is set automatically. The default model manager supports JSON transformations. For advanced applications, a custom model manager can be substituted. For more information, see the Caching section of this guide.

Always ensure that model objects have their modelManager property set. Models returned from client API calls will always have this property set, so you can use it to set on other models. For example, when adding line items to a cart or a checkout, simply set the modelManager on the line item to the same one. For cart line items, simply use the -addVariant: and -removeVariant: conveniences. To update a checkout, first update your cart object, then update the checkout by passing the cart to -[BUYCart updateWithCart:].


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.

To complete a checkout in one step, use the convenience method -completeCheckoutWithToken:paymentToken:completion: for native checkout.

For checkout with Apple Pay or through the web, use the appropriate payment provider: BUYApplePayPaymentProvider or BUYWebCheckoutPaymentProvider.

Product View Controller

The framework component of the SDK has been streamlined. All view classes (subclasses of UIView), and view controllers have been removed. The BUYProductView, BUYProductViewController, and other custom views have been moved into the Advanced Sample App. All of their names have been changed to remove the "BUY" prefix. 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.

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.

  • General changes:
    • Date properties have had "Date" removed from their names. e.g. createdAtDate -> createdAt.
    • The type of all to-many relationships have been changed from NSArray to NSSet (or NSOrderedSet). A few properties still exist which are typed as NSArray, but these are not proper relationships (they are arrays of strings or some other value type).
    • In some cases, convenience methods have been added to provide arrays for to-many properties. This is to support Swift, which has no NSOrderedSet equivalent.
  • BUYObject:

    • Many properties and methods of the class have been factored out into the BUYObject protocol.
    • JSONDictionary, a dynamic property, has been added. Replaces -updateWithJSON:, and provides JSON serialization.
  • BUYCheckout:

    • taxesIncluded has been renamed includesTaxes.
  • BUYCollection:

    • collectionId has been removed. Use identifier.
    • imageURL has been removed. Use imageLink.sourceURL.
  • BUYImage:

    • class has been renamed to BUYImageLink.
    • product has been added.
    • productId has been removed. Use product.identifier.
    • src has been renamed to sourceURL.
  • BUYOption:

    • product has been added.
    • productId has been removed. Use product.identifier.
  • BUYOrder:

    • statusURL has been changed to orderStatusURL.
    • New properties: processedAt, subtotalPrice and totalPrice.
  • Product:

    • productId has been removed. Use identifier.