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). The default is [othersAlsoBought, mfgRecommendations, topProducts, random]. However, if a manufacturer wanted their recommendations to always come first and to never display products at random, they could set this value to [mfgRecommendations, othersAlsoBought, topProducts].
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.