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