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