BUYClient Class Reference

Inherits from NSObject
Declared in BUYClient.h

Overview

The BUYDataClient provides all requests needed to perform request on the Shopify Checkout API. Use this class to perform tasks such as getting a shop, products for a shop, creating a Checkout on Shopify and completing Checkouts.

Other Methods

– initWithShopDomain:apiKey:channelId:

Initialize a BUYDataClient using a shop’s domain, API key and the Channel ID.

- (instancetype)initWithShopDomain:(NSString *)shopDomain apiKey:(NSString *)apiKey channelId:(NSString *)channelId

Parameters

shopDomain

The Shop Domain i.e. abetterlookingshop.myshopify.com

apiKey

The API key provided via the Mobile SDK Channel on Shopify Admin

channelId

The Channel ID provided on Shopify Admin

Return Value

An instance of BUYDataClient

Declared In

BUYClient.h

  queue

Queue where callbacks will be called defaults to main queue

@property (nonatomic, strong) dispatch_queue_t queue

Declared In

BUYClient.h

  pageSize

The page size for any paged request. This can range from 1-250. Default is 25

@property (nonatomic, assign) NSUInteger pageSize

Declared In

BUYClient.h

  shopDomain

The shop domain set using the initializer

@property (nonatomic, strong, readonly) NSString *shopDomain

Declared In

BUYClient.h

  apiKey

The API Key set using the initializer

@property (nonatomic, strong, readonly) NSString *apiKey

Declared In

BUYClient.h

  channelId

The Channel ID set using the initializer

@property (nonatomic, strong, readonly) NSString *channelId

Declared In

BUYClient.h

  )

The Merchant ID is used for Apple Pay and set using enableApplePayWithMerchantId:

@property (nonatomic, strong, readonly) NSString *DEPRECATED_MSG_ATTRIBUTE ( "Set the `merchantId` on a BUYViewController subclass" )

Declared In

BUYClient.h

  applicationName

Application name to attribute orders to. Defaults to app bundle name (CFBundleName)

@property (nonatomic, strong) NSString *applicationName

Declared In

BUYClient.h

  urlScheme

The applications URLScheme, used to return to the application after a complete web checkout. Ex. @“storeApp://”

@property (nonatomic, strong) NSString *urlScheme

Declared In

BUYClient.h

– getShop:

Fetches the shop’s metadata (from /meta.json).

- (NSURLSessionDataTask *)getShop:(BUYDataShopBlock)block

Parameters

block

(^BUYDataShopBlock)(BUYShop shop, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getProductsPage:completion:

Fetches a single page of products for the shop.

- (NSURLSessionDataTask *)getProductsPage:(NSUInteger)page completion:(BUYDataProductListBlock)block

Parameters

page

Page to request. Pages start at 1.

block

(^BUYDataProductListBlock)(NSArray products, NSUInteger page, BOOL reachedEnd, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getProductById:completion:

Fetches a single product by the ID of the product.

- (NSURLSessionDataTask *)getProductById:(NSString *)productId completion:(BUYDataProductBlock)block

Parameters

productId

Product ID

block

(^BUYDataProductBlock)(BUYProduct product, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getProductsByIds:completion:

Fetches a list of product by the ID of each product.

- (NSURLSessionDataTask *)getProductsByIds:(NSArray *)productIds completion:(BUYDataProductsBlock)block

Parameters

productIds

An array of NSString objects with Product IDs to fetch

block

(^BUYDataProductsBlock)(NSArray products, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getCollections:

Fetches the collections on the shop

- (NSURLSessionDataTask *)getCollections:(BUYDataCollectionsBlock)block

Parameters

block

(^BUYDataCollectionsBlock)(NSArray collections, NSError error)

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getProductsPage:inCollection:completion:

Fetches the products in the given collection with the collection’s default sort order set in the shop’s admin

- (NSURLSessionDataTask *)getProductsPage:(NSUInteger)page inCollection:(NSNumber *)collectionId completion:(BUYDataProductListBlock)block

Parameters

page

Index of the page requested

collectionId

The collectionId found in the BUYCollection object to fetch the products from

block

(NSArray products, NSUInteger page, BOOL reachedEnd, NSError error)

Return Value

the associated NSURLSessionDataTask

Declared In

BUYClient.h

– getProductsPage:inCollection:sortOrder:completion:

Fetches the products in the given collection with a given sort order

- (NSURLSessionDataTask *)getProductsPage:(NSUInteger)page inCollection:(NSNumber *)collectionId sortOrder:(BUYCollectionSort)sortOrder completion:(BUYDataProductListBlock)block

Parameters

page

Index of the page requested

collectionId

The collectionId found in the BUYCollection object to fetch the products from

sortOrder

The sort order that overrides the default collection sort order

block

(NSArray products, NSUInteger page, BOOL reachedEnd, NSError error)

Return Value

the associated NSURLSessionDataTask

Declared In

BUYClient.h

– createCheckout:completion:

Builds a checkout on Shopify. The checkout object is used to prepare an order

- (NSURLSessionDataTask *)createCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutBlock)block

Parameters

checkout

BUYCheckout to create on Shopify

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– createCheckoutWithCartToken:completion:

Builds a checkout on Shopify using a Cart Token from an existing cart on your Shopify store’s storefront. The BUYCheckout object is used to prepare an order.

- (NSURLSessionDataTask *)createCheckoutWithCartToken:(NSString *)cartToken completion:(BUYDataCheckoutBlock)block

Parameters

cartToken

Cart Token associated with an existing BUYCheckout on Shopify

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– applyGiftCardWithCode:toCheckout:completion:

Applies a gift card code to the checkout.

- (NSURLSessionDataTask *)applyGiftCardWithCode:(NSString *)giftCardCode toCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutBlock)block

Parameters

giftCardCode

The gift card code to apply on an existing checkout on Shopify. Note: This is not the same as the gift card identifier.

checkout

An existing BUYCheckout on Shopify

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– removeGiftCard:fromCheckout:completion:

Removes a gift card from the checkout.

- (NSURLSessionDataTask *)removeGiftCard:(BUYGiftCard *)giftCard fromCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutBlock)block

Parameters

checkout

An existing BUYCheckout on Shopify

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

giftCardCode

The BUYGiftCard identifier to remove on an existing checkout on Shopify.

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getCheckout:completion:

Retrieves an updated version of a BUYCheckout from Shopify.

- (NSURLSessionDataTask *)getCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutBlock)block

Parameters

checkout

The BUYCheckout to retrieve (updated) from Shopify

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Discussion

Note: There’s no guarantee that the BUYCheckout returned will be the same as the one that is passed in. We recommended using the BUYCheckout returned in the block.

Declared In

BUYClient.h

– updateCheckout:completion:

Updates a given BUYCheckout on Shopify.

- (NSURLSessionDataTask *)updateCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutBlock)block

Parameters

checkout

The BUYCheckout to updated on Shopify

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Discussion

Note: There’s no guarantee that the BUYCheckout returned will be the same as the one that is passed in. We recommended using the BUYCheckout returned in the block.

Note: A BUYCheckout object with an orderId is a completed checkout.

Declared In

BUYClient.h

– completeCheckout:completion:

Finalizes the BUYCheckout and charges the credit card. This enqueues a completion job on Shopify and returns immediately. You must get the job’s status by calling checkCompletionStatusOfCheckout:block

- (NSURLSessionDataTask *)completeCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutBlock)block

Parameters

checkout

The BUYCheckout to complete

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Discussion

Note: There’s no guarantee that the BUYCheckout returned will be the same as the one that is passed in. We recommended using the BUYCheckout returned in the block.

Declared In

BUYClient.h

– completeCheckout:withApplePayToken:completion:

Finalizes the checkout and charges the credit card associated with the payment token from PassKit (Apple Pay). This only enqueues a completion job, and will return immediately. You must get the job’s status by calling checkCompletionStatusOfCheckout:block

- (NSURLSessionDataTask *)completeCheckout:(BUYCheckout *)checkout withApplePayToken:(PKPaymentToken *)token completion:(BUYDataCheckoutBlock)block

Parameters

checkout

The BUYCheckout to complete

token

The PKPaymentToken

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Discussion

Note: There’s no guarantee that the BUYCheckout returned will be the same as the one that is passed in. We recommended using the BUYCheckout returned in the block.

Declared In

BUYClient.h

– getCompletionStatusOfCheckout:completion:

Retrieve the status of a BUYCheckout. This checks the status of the current payment processing job for the provided checkout. Once the job is complete (status == BUYStatusComplete), you can retrieve the completed order by calling getCheckout:completion

- (NSURLSessionDataTask *)getCompletionStatusOfCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutStatusBlock)block

Parameters

checkout

The BUYCheckout to retrieve completion status for

block

(^BUYDataCheckoutStatusBlock)(BUYCheckout checkout, BUYStatus status, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getCompletionStatusOfCheckoutURL:completion:

Retrieve the status of a checkout given a URL obtained in the UIApplicationDelegate method application:sourceApplication:annotation

- (NSURLSessionDataTask *)getCompletionStatusOfCheckoutURL:(NSURL *)url completion:(BUYDataCheckoutStatusBlock)block

Parameters

url

The URL resource used to open the application

block

(^BUYDataCheckoutStatusBlock)(BUYCheckout checkout, BUYStatus status, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– getShippingRatesForCheckout:completion:

Retrieves a list of applicable shipping rates for a given BUYCheckout. Add the preferred/selected BUYShippingRate to BUYCheckout, then update BUYCheckout

- (NSURLSessionDataTask *)getShippingRatesForCheckout:(BUYCheckout *)checkout completion:(BUYDataShippingRatesBlock)block

Parameters

checkout

The BUYCheckout to retrieve shipping rates for

block

(^BUYDataShippingRatesBlock)(NSArray shippingRates, BUYStatus status, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– storeCreditCard:checkout:completion:

Prepares a credit card for usage during the checkout process. This sends it to Shopify’s secure servers. Note: Storing the token does not charge the associated card (credit or otherwise). The card will be charged upon finalizing the checkout (completeCheckout:completion:)

- (NSURLSessionDataTask *)storeCreditCard:(id<BUYSerializable>)creditCard checkout:(BUYCheckout *)checkout completion:(BUYDataCreditCardBlock)block

Parameters

creditCard

BUYCreditCard to prepare for usage

checkout

The BUYCheckout associated to the purchase. The billingAddress stored on the BUYCheckout object is optional and recommended and used (if provided) to help with fraud checking.

block

(^BUYDataCreditCardBlock)(BUYCheckout checkout, NSString paymentSessionId, NSError *error);

Return Value

The associated NSURLSessionDataTask

Discussion

You MUST call completeCheckout:completion: after this call and receiving a paymentSessionId. The paymentSessionId on the BUYCheckout object is not persisted on updateCheckout:completion: calls.

Declared In

BUYClient.h

– removeProductReservationsFromCheckout:completion:

Convenience method to release all product inventory reservations by setting its reservationTime to @0 and calls updateCheckout:completion. We recommend creating a new BUYCheckout object from a BUYCart for further API calls.

- (NSURLSessionDataTask *)removeProductReservationsFromCheckout:(BUYCheckout *)checkout completion:(BUYDataCheckoutBlock)block

Parameters

checkout

The BUYCheckout to expire

block

(^BUYDataCheckoutBlock)(BUYCheckout checkout, NSError error);

Return Value

The associated NSURLSessionDataTask

Declared In

BUYClient.h

– enableApplePayWithMerchantId:

Enable Apple Pay by calling this method with the Merchant ID provided via Apple Pay setup in the Mobile SDK Channel on Shopify Admin

- (void)enableApplePayWithMerchantId:(NSString *)merchantId

Parameters

merchantId

The Merchant ID generated on Shopify Admin

Declared In

BUYClient.h

Test Methods

– testIntegrationWithMerchantId:

Test the integration with your shop. This should not be shipped in production code. This is a syncronous network call.

- (BOOL)testIntegrationWithMerchantId:(NSString *)merchantId

Parameters

merchantId

the merchant ID setup for Apple Pay in the Integration page of the Mobile Channel

Return Value

YES on success

Declared In

BUYClient+Test.h

– testIntegration

Test the integration with your shop. This should not be shipped in production code. This is a syncronous network call.

- (BOOL)testIntegration

Return Value

YES on success

Declared In

BUYClient+Test.h