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 *)channelIdParameters
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 queueDeclared In
BUYClient.h
pageSize
The page size for any paged request. This can range from 1-250. Default is 25
@property (nonatomic, assign) NSUInteger pageSizeDeclared In
BUYClient.h
shopDomain
The shop domain set using the initializer
@property (nonatomic, strong, readonly) NSString *shopDomainDeclared In
BUYClient.h
apiKey
The API Key set using the initializer
@property (nonatomic, strong, readonly) NSString *apiKeyDeclared In
BUYClient.h
channelId
The Channel ID set using the initializer
@property (nonatomic, strong, readonly) NSString *channelIdDeclared 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 *applicationNameDeclared In
BUYClient.h
urlScheme
The applications URLScheme, used to return to the application after a complete web checkout. Ex. @“storeApp://”
@property (nonatomic, strong) NSString *urlSchemeDeclared In
BUYClient.h
– getShop:
Fetches the shop’s metadata (from /meta.json).
- (NSURLSessionDataTask *)getShop:(BUYDataShopBlock)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
productIds |
An array of |
|---|---|
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)blockParameters
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)blockParameters
page |
Index of the page requested |
|---|---|
collectionId |
The |
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)blockParameters
page |
Index of the page requested |
|---|---|
collectionId |
The |
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
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)blockParameters
creditCard |
BUYCreditCard to prepare for usage |
|---|---|
checkout |
The BUYCheckout associated to the purchase.
The |
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)blockParameters
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 *)merchantIdParameters
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 *)merchantIdParameters
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)testIntegrationReturn Value
YES on success
Declared In
BUYClient+Test.h