Add to Cart with JSON
Experienced developers can use JSON when adding Kibo eCommerce to their product sites without needing to add any server side code. This supplementary JSON provides more developer control of the Add to Cart functionality, though it must be otherwise integrated with JavaScript. Buttons may be styled and matched to the existing site, and prices and rich product information may be pulled from Kibo and displayed on client’s site.
Getting Started
Before using any of the functions described in this guide, the Kibo module and an API key should be included. The format for including the Kibo module follows:
<script id="shopatronCart" src="https://cdn.shptrn.com/media/js/product/shopatronAPI-2.4.min.js" type="text/javascript">{"api_Key":"{api_Key}"}</script>
addToCart – Adds an Item to a Cart
Add an item to a cart with the addToCart method. If the user tries to add an item that is already in the cart, its quantity is updated; a duplicate item is not added.
Shopatron.addToCart(cartItem, options)
Parameters
The following parameters are defined in the addtoCart method.
* Required
Parameter Type Default Description cartItem.catalogID Integer The catalog set as default for the api_Key. The catalog for the item that is being added. cartItem.quantity Integer 1 The quantity for the item that is being added. cartItem.partNumber* String None The item’s Part Number cartItem.productLink String The current page. The link to the product detail page. cartItem.itemOptions Object {} An object that maps option names to the value for the option. options.success function None Use to notify the user when an item is added. options.error function (textStatus, errorThrown) {} None Use to notify the user if a request fails. options.complete function (textStatus) {} None Use to remove a processing graphic (such as a spinner) upon completion, successful or not.
checkout – Passes a Cart to Kibo for Checkout
Use checkout to link to Kibo checkout. When this method is invoked, the user is automatically redirected to checkout.
Shopatron.checkout(options)
Parameters
The following parameters are defined in the checkout method.
Parameter Type Default Description options.success function {} To direct the user to checkout Use to override the default functionality that automatically directs the user to checkout. options.error function (textStatus, errorThrown) {} None Use to notify the user if a request fails. options.complete function (textStatus) {} None Use to remove a processing graphic (such as a spinner) upon completion, successful or not.
getCart – Gets Cart Data
Use getCart to retrieve the data for an existing cart.
Shopatron.getCart(options)
Parameters
The following parameters are defined in the getCart method.
Parameter Type Default Description options.success function (cart, textStatus) {} None Use the success function to perform an action with the data retrieved. options.error function (textStatus, errorThrown) {} None Use to notify the user if a request fails. options.complete function (textStatus) {} None Use to remove a processing graphic (such as a spinner) upon completion, successful or not. options.template Friendly Boolean True or False If true, returns sorted product options.
Cart Fields
The following fields are variables defined in the cart.
Parameter Type Description cartID String A unique identifier for this cart. createdDate String A date (in ISO 8601 format) that identifies when the cart was created. completedDate String A date (in ISO 8601) format that identifies when the cart completed checkout. If the cart has not been completed, this value is null. locale String A locale (in IETF language tag format). currency String An ISO 4217 currency code. externalCartID String When the cart is passed to checkout, this value is returned. If the cart has not been loaded into checkout yet, this value is null. cartItems Object A mapping of cartItemIDs to objects that describes an item in the cart. cartItems[cartItemID]. catalogID Integer The catalog that this product is in. cartItems[cartItemID]. quantity Integer The quantity for this product. cartItems[cartItemID]. price String The price of the item in the cart, including additional price of options selected. cartItems[cartItemID]. product String A URL that points to a product data REST resource. cartItems[cartItemID]. itemOptions Object A mapping of option names to selected values. cartItems[cartItemID]. productLink String A link to the product detail page for the product.
getProductRecommendations – Gets Recommended Products
Use getProductRecommendations to retrieve a list of products recommended for the given part number(s).
Shopatron.getProductRecommendations(queryOptions, options)
Parameters
The following parameters are defined in the getProductRecommendations method.
* Required
Parameter Type Default Description queryOptions. catalogID Integer Default catalogID This field is only necessary when working with multi-catalog sites. queryOptions. pageSize Integer 3 The number of results desired to be received. queryOptions.minRank Integer 0 All products have a rank. This option restricts the set of returned products to only products with ranks within these values. queryOptions.maxRank Integer No default All products have a rank. This option restricts the set of returned products to only products with ranks within these values. queryOptions. availabilities Array of Strings Defaults to all of (Y|P|L|M|J|I|S) Only applies to recommendationType random. queryOptions. recommendationTypes String or array of Strings [othersAlso Bought, mfg Recommendations, topProducts, random] This allows the user to customize the results that are returned from this call. Recommended products are pulled from four sources: othersAlsoBought (this returns results based on relations from order history; “Customers who bought product A have also bought product B”), mfgRecommendations (these results come from the manufacturer-specified product recommendations in the product data), topProducts (this returns the most popular products in the catalog. These recommendations have nothing to do with the product(s) for which Kibo requested recommendations, but it is useful as a fallback if the previous two did not return any results), and random (if none of the previous methods return any results, Kibo can recommend products at random as well). queryOptions. recommendedFor* Array of Strings Provide the part number to get recommendations for. options.success function (product, textStatus) {} None Use the success function to provide feedback to the user that the item was removed successfully. options.error function (textStatus, errorThrown) {} None If the request fails, provides some feedback to the user. options.complete function (textStatus) {} None Use to remove a processing graphic (such as a spinner) upon completion, successful or not.
getProduct – Gets Product Data
Use getProduct to retrieve data for a line item that has the specified part number.
Shopatron.getProduct(productData, options)
Parameters
The following parameters are defined in the getProduct method.
* Required
Parameter Type Default Description productData.part Number* String None The part number of the item being inquired about. productData.catalogID Integer catalogID This field is only necessary when working with multi-catalog sites. options.success function (product, textStatus) {} None Use to perform an action on the retrieved data. options.error function (textStatus, errorThrown) {} None Use to notify a user if a request fails. options.complete function (textStatus) {} None Use to remove a processing graphic (such as a spinner) upon completion, successful or not. options.template Friendly Boolean True or False If true, returns sorted product options.
Product Fields
These fields are parameters defined as part of the product.
Parameter Occurs Type Description partNumber 1 A string of at least one character. Line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces are not allowed. Part number for the product. name 1 A string of at least one character. Line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces are not allowed. The product name. price 1 A decimal number greater than 0.00 with two places after the decimal The price the product is selling for and should not include currency symbols. priceDisplay 1 String This is related to the price field. The price field is the price as a number that can be used for calculations. The priceDisplay field is the price as a currency formatted string that can be used for displaying the price to the user; for example, {“price”: 1023.12,” priceDisplay”: “£1.023,12”}. availability.code 1 Must be one of (Y|N|D|L|M|P|I|S) The availability of the product. May be any of these codes: Y (Yes, item is in stock and ready to ship), N (No, item can be placed on backorder), L (Limited, limited availability), M (MFG ship, Item is in stock and ready to ship), J (Split to merchant, item is available), P (PreOrder, item is not available at this time and can be preordered), D (Discontinued, the item is discontinued and an attempt to find it will be made), I (Digital content, this item is available for immediate download), and S (Ship to store only, this item is Ship to Store Only). averageDealerMargin 1 A number between 0 and 1 The Average Dealer Margin for the product. This is a decimal value between 0.2 and 0.9, inclusive, expressed as a decimal. The formula for calculating Average Dealer Margin is: (offer price – wholesale price) x offer price locale 1 A IETF locale code The locale for the product. currency 1 ISO 4217 The currency used, expressed as an ISO 4217 currency code. image 1 A URL A URL pointing to the product image. images 1-n An array of Objects Each object in the array describes an image. The array is ordered by image rank starting with the primary image. images[].name 0-1 Any String A label for the image. Images[].url 1 A URL An image resource. description 0-1 Any string A short description of the product. VATRate 0-1 A number between 0 and 1 Only appears for catalogs that use VAT. productOptions Object A mapping of optionName to the product option definition. productOptions[groupID]. displayName 0-1 Any String This can be used if option name presented to the user needs to be different than what is stored with the order. For example, the manufacturer might want to store a code to facilitate automation but wants to display a human-readable version to the user. productOptions[groupId]. description 0-1 Any String A description of the option group. productOptions[groupID]. optionChoices.options 0-1 An object, where the key is the option name and the value is an option definition. The set of options available for this group. productOptions[groupId]. optionChoices.options [optionId] 1-n An option definition The set of options available for this group. optionID 0-n A String of at least one character. Line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces are not allowed. The group name of the option. productOptions[groupID]. optionChoices.options [optionID].displayName 0-1 Any String Use this if the option value to be stored differs from the value that should be displayed. productOptions[groupID]. optionChoices.options [optionID].description 0-1 Any String A description of the optionID choice. productOptions[groupID]. optionChoices.options [optionID].additionalPrice 0-1 A decimal number greater than 0.00 with two places after the decimal The additional price, if any, required to purchase the product with this option. productOptions[groupID]. optionChoices.options [optionID]. additionalPriceDisplay 0-1 String This is related to the additionalprice field. The additionalprice field is the price as a number that can be used for calculations. The additionalpriceDisplay field is the price as a currency formatted String that can be used for displaying the price to the user; for example, {“price”: 1023.12, “additionalpriceDisplay”: “£1.023,12”}. productOptions[groupId]. optionChoices.options [optionId].rank 1 Any Integer A ranking of the product with the selected option. productOptions[groupID]. optionChoices.options [optionID].image 0-1 A URL A URL pointing to an option image. optionSets 0-n Array This defines a valid combination of options. It can be used to describe slaved options. optionSets.selectedOptions 1-n An object with groupId-optionId pairs The value of the selected option. weight 0 An object If weight based shipping is being used, the weight of the product needs to be known. weight.value 1 A decimal number If weight based shipping is being used, the weight of the product needs to be known. weight.units 1 Must be one of (lb|kg) Units for this product’s weight. Used for weight-based shipping. shippingMethod 0-1 A non-negative Integer This is a Kibo shipping method ID. customFields 0-1 Any value Any custom data the client wants to store with the product. When products are coming from Kibo, specs will be populated here. customFields.description 1 String The spec description. customFields.name 1 String The spec name. customFields.specType 1 String The spec type.
removeItem – Removes an Item from the Cart
Use removeItem to remove the specified line item from a cart.
Shopatron.removeItem(cartItem, options)
Parameters
The following parameters are defined in the removeItem method.
* Required
Parameter Type Default Description cartItem.cartItemID* String None The cartItemID for the line item that is being updated. cartItem.quantity* String None The new quantity for the item. options.success function {} None Use to notify the user when a quantity is updated. options.error function (textStatus, errorThrown) {} None Use to notify the user if a request fails.
updateQuantity – Updates the Quantity of an Item in the Cart
Use updateQuantity to change the quantity of the specified line item.
Shopatron.updateQuantity(cartItem, options)
Parameters
The following parameters are defined in the removeItem method.
* Required
Parameter Type Default Description cartItem.cartItemID* String None The cartItemID for the line item that is being updated. cartItem.quantity* String None The new quantity for the item. options.success function {} None Use to notify the user when a quantity is updated. options.error function (textStatus, errorThrown) {} None Use to notify the user if a request fails. options.complete function (textStatus) {} None Use to remove a processing graphic (such as a spinner) upon completion, successful or not.
proceedToCheckout – Passed the Cart to Kibo for Checkout
Use proceedToCheckout to load the cart into Kibo checkout. It will return a link to follow in order to proceed to checkout. One optional parameter, catalogID, is expected, which can be used to override into which catalog to load the cart. Pass the cart to Kibo for checkout.
The user is automatically redirected to checkout when they invoke this method. Developers building their own cart HTML will use this to link to Kibo checkout.
Shopatron.proceedToCheckout(checkoutOptions, options)
Parameters
The following parameters are defined in the removeItem method.
* Required
Parameter Type Default Description checkoutOptions.catalogID Integer Default checkoutOptions.catalogID _catalog_id This optional parameter can be _catalog_id This optional parameter can be used to override which checkout catalog the cart is loaded into. used to override which checkout catalog the cart is loaded into. used to override which checkout catalog the cart is loaded into. used to override which checkout catalog the cart is loaded into. options.success function (product, textStatus) {} No default Use the success function to override the default functionality of automatically redirecting to checkout. options.error function (textStatus, errorThrown) {} No default Use to notify the user if a request fails. options.complete function (textStatus) {} No default This could be used to remove some processing graphic whether the request was successful or not.
