Presenting a storefront

The Buy SDK provides access to shop data that a mobile app can use to present a native mobile storefront. This includes details about the shop itself, the product catalog, and customer accounts. Customer support is described in Customer accounts.

Getting the Shop

The shop, represented by the BUYShop class, includes useful information that describes the shop, including the mailing address, web address, and currency. The currency information is essential for correctly displaying product prices. The shop does not change often. It is reasonable to fetch it once per user session, and cache it—or just the properties you need—somewhere easy to access. Commonly, you might store it in your application delegate, and pass a reference along to other objects that need it.

[client getShop:^(BUYShop *shop, NSError *error) {
    if (shop && !error) { = shop;
        // continue fetching other information
    else {
        // Handle error

Getting Collections

Collections and products are provided in paginated lists. The page size is configurable using the pageSize property of BUYClient. Pages are numbered starting at 1. To get a partial list of collections, provide the desired page number:

[client getCollectionsPage:1 completion:^(NSArray *collections, NSUInteger page, BOOL reachedEnd, NSError *error) {
    if (collection && !error) {
        self.collections = collections;
        // display list of collections
    } else {
        // Handle errors here

The Collection entity, represented by the BUYCollection class, defines two relationships: image and products. The image is an instance of BUYImageLink, which includes a sourceURL property. You must make a separate request for the image assigned to a collection using this URL. The products property is a convenient place to store products downloaded separately (see below). By default, the relationship is always empty.

Getting Products

Products returned from the API include all of their subordinate objects, including variants, options, and option values.

To get a partial list of products, use -getProductsPage:completion:.

[client getProductsPage:1 completion:^(NSArray *products, NSUInteger page, BOOL reachedEnd, NSError *error) {
    if (products && !error) {
        self.products = products;
        // display list of products
    } else {
        // Handle errors here

To get products in a single collection, use -getProductsPage:inCollection:completion:, passing in the identifier for the collection.

Shared links to products often use the handle in the URL. To get a single product using its handle, use -getProductByHandle:completion:.

Finally, to get a product or products using their identifiers, use -getProductById:completion: or -getProductsByIds:completion:.