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 |
---|---|
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 |
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 |
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 |
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