OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

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

ParameterTypeDefaultDescription
cartItem.catalogIDIntegerThe catalog set as default for the api_Key.The catalog for the item that is being added.
cartItem.quantityInteger1The quantity for the item that is being added.
cartItem.partNumber*StringNoneThe item’s Part Number
cartItem.productLinkStringThe current page.The link to the product detail page.
cartItem.itemOptionsObject{}An object that maps option names to the value for the option.
options.successfunctionNoneUse to notify the user when an item is added.
options.errorfunction (textStatus, errorThrown) {}NoneUse to notify the user if a request fails.
options.completefunction (textStatus) {}NoneUse 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.

ParameterTypeDefaultDescription
options.successfunction {}To direct the user to checkoutUse to override the default functionality that automatically directs the user to checkout.
options.errorfunction (textStatus, errorThrown) {}NoneUse to notify the user if a request fails.
options.completefunction (textStatus) {}NoneUse 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.

ParameterTypeDefaultDescription
options.successfunction (cart, textStatus) {}NoneUse the success function to perform an action with the data retrieved.
options.errorfunction (textStatus, errorThrown) {}NoneUse to notify the user if a request fails.
options.completefunction (textStatus) {}NoneUse to remove a processing graphic (such as a spinner) upon completion, successful or not.
options.template FriendlyBooleanTrue or FalseIf true, returns sorted product options.

Cart Fields

The following fields are variables defined in the cart.

ParameterTypeDescription
cartIDStringA unique identifier for this cart.
createdDateStringA date (in ISO 8601 format) that identifies when the cart was created.
completedDateStringA date (in ISO 8601) format that identifies when the cart completed checkout. If the cart has not been completed, this value is null.
localeStringA locale (in IETF language tag format).
currencyStringAn ISO 4217 currency code.
externalCartIDStringWhen the cart is passed to checkout, this value is returned. If the cart has not been loaded into checkout yet, this value is null.
cartItemsObjectA mapping of cartItemIDs to objects that describes an item in the cart.
cartItems[cartItemID]. catalogIDIntegerThe catalog that this product is in.
cartItems[cartItemID]. quantityIntegerThe quantity for this product.
cartItems[cartItemID]. priceStringThe price of the item in the cart, including additional price of options selected.
cartItems[cartItemID]. productStringA URL that points to a product data REST resource.
cartItems[cartItemID]. itemOptionsObjectA mapping of option names to selected values.
cartItems[cartItemID]. productLinkStringA 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

ParameterTypeDefaultDescription
queryOptions. catalogIDIntegerDefault catalogIDThis field is only necessary when working with multi-catalog sites.
queryOptions. pageSizeInteger3The number of results desired to be received.
queryOptions.minRankInteger0All products have a rank. This option restricts the set of returned products to only products with ranks within these values.
queryOptions.maxRankIntegerNo defaultAll products have a rank. This option restricts the set of returned products to only products with ranks within these values.
queryOptions. availabilitiesArray of StringsDefaults to all of (Y|P|L|M|J|I|S)Only applies to recommendationType random.
queryOptions. recommendationTypesString 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 StringsProvide the part number to get recommendations for.
options.successfunction (product, textStatus) {}NoneUse the success function to provide feedback to the user that the item was removed successfully.
options.errorfunction (textStatus, errorThrown) {}NoneIf the request fails, provides some feedback to the user.
options.completefunction (textStatus) {}NoneUse 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

ParameterTypeDefaultDescription
productData.part Number*StringNoneThe part number of the item being inquired about.
productData.catalogIDIntegercatalogIDThis field is only necessary when working with multi-catalog sites.
options.successfunction (product, textStatus) {}NoneUse to perform an action on the retrieved data.
options.errorfunction (textStatus, errorThrown) {}NoneUse to notify a user if a request fails.
options.completefunction (textStatus) {}NoneUse to remove a processing graphic (such as a spinner) upon completion, successful or not.
options.template FriendlyBooleanTrue or FalseIf true, returns sorted product options.

Product Fields

These fields are parameters defined as part of the product.

ParameterOccursTypeDescription
partNumber1A 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.
name1A string of at least one character. Line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces are not allowed.The product name.
price1A decimal number greater than 0.00 with two places after the decimalThe price the product is selling for and should not include currency symbols.
priceDisplay1StringThis 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.code1Must 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).
averageDealerMargin1A number between 0 and 1The 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
locale1A IETF locale codeThe locale for the product.
currency1ISO 4217The currency used, expressed as an ISO 4217 currency code.
image1A URLA URL pointing to the product image.
images1-nAn array of ObjectsEach object in the array describes an image. The array is ordered by image rank starting with the primary image.
images[].name0-1Any StringA label for the image.
Images[].url1A URLAn image resource.
description0-1Any stringA short description of the product.
VATRate0-1A number between 0 and 1Only appears for catalogs that use VAT.
productOptionsObjectA mapping of optionName to the product option definition.
productOptions[groupID]. displayName0-1Any StringThis 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]. description0-1Any StringA description of the option group.
productOptions[groupID]. optionChoices.options0-1An 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-nAn option definitionThe set of options available for this group.
optionID0-nA 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].displayName0-1Any StringUse this if the option value to be stored differs from the value that should be displayed.
productOptions[groupID]. optionChoices.options [optionID].description0-1Any StringA description of the optionID choice.
productOptions[groupID]. optionChoices.options [optionID].additionalPrice0-1A decimal number greater than 0.00 with two places after the decimalThe additional price, if any, required to purchase the product with this option.
productOptions[groupID]. optionChoices.options [optionID]. additionalPriceDisplay0-1StringThis 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].rank1Any IntegerA ranking of the product with the selected option.
productOptions[groupID]. optionChoices.options [optionID].image0-1A URLA URL pointing to an option image.
optionSets0-nArrayThis defines a valid combination of options. It can be used to describe slaved options.
optionSets.selectedOptions1-nAn object with groupId-optionId pairsThe value of the selected option.
weight0An objectIf weight based shipping is being used, the weight of the product needs to be known.
weight.value1A decimal numberIf weight based shipping is being used, the weight of the product needs to be known.
weight.units1Must be one of (lb|kg)Units for this product’s weight. Used for weight-based shipping.
shippingMethod0-1A non-negative IntegerThis is a Kibo shipping method ID.
customFields0-1Any valueAny custom data the client wants to store with the product. When products are coming from Kibo, specs will be populated here.
customFields.description1StringThe spec description.
customFields.name1StringThe spec name.
customFields.specType1StringThe 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

ParameterTypeDefaultDescription
cartItem.cartItemID*StringNoneThe cartItemID for the line item that is being updated.
cartItem.quantity*StringNoneThe new quantity for the item.
options.successfunction {}NoneUse to notify the user when a quantity is updated.
options.errorfunction (textStatus, errorThrown) {}NoneUse 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

ParameterTypeDefaultDescription
cartItem.cartItemID*StringNoneThe cartItemID for the line item that is being updated.
cartItem.quantity*StringNoneThe new quantity for the item.
options.successfunction {}NoneUse to notify the user when a quantity is updated.
options.errorfunction (textStatus, errorThrown) {}NoneUse to notify the user if a request fails.
options.completefunction (textStatus) {}NoneUse 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

ParameterTypeDefaultDescription
checkoutOptions.catalogIDIntegerDefaultcheckoutOptions.catalogID
_catalog_idThis optional parameter can be_catalog_idThis 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.successfunction (product, textStatus) {}No defaultUse the success function to override the default functionality of automatically redirecting to checkout.
options.errorfunction (textStatus, errorThrown) {}No defaultUse to notify the user if a request fails.
options.completefunction (textStatus) {}No defaultThis could be used to remove some processing graphic whether the request was successful or not.