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 REST

With the Add to Cart REST API, developers can add a line item to an existing shopping cart, retrieve the contents of a cart, modify the quantity of an item in a cart, and delete items from a cart. Follow the steps below for how to implement the following methods through API requests:

  • Add a Product to a Cart
  • Get Cart Data
  • Get Cart Item Data
  • Get Product Data
  • Remove an Item from a Cart
  • Update the Quantity of an Item in a Cart
  • Proceed to Checkout

This guide also defines the product data and cart data values that can be edited.

Add a Product to a Cart

Use the REST API to add a line item to an existing Kibo cart. To add the line item, use the following POST method and include data about the line item to be added.

Required and Optional Parameters

ParameterRequiredDescription
productYesThe REST resource for the product.
productLinkYesThe direct link to the product detail page.
catalogIDOptionalThe manufacturer catalog ID for the product. If omitted, the default catalog that is configured for this API key is used.
quantityOptionalHow many of this product to add. Defaults to 1 if not included.
itemOptionsOptionalOptions that apply to the line item being added. In the preceding code, options include values for color and size.

Example Request

POST https://product.shopatron.com/cart/{cartID}/cartItems?api_key={api_key}

Where:

  • cartID is the ID of the cart to which the line item is being added. This value is a unique identifier created for the cart
  • api_key is the API key obtained from Kibo

The request body contains the above parameters:

Accept:application/json{
   "product":"https://product.shopatron.com/product/abc123?api_key=asdf1234&catalogID=1",
   "catalogID":1,
   "quantity":1,
   "itemOptions":{ <a href="javascript:;"><i class="fa fa-minus-square-o"> 
      "192512":"200260",
      "803881":"200405"
   },
   "productLink":"https://product.shopatron.com/products/abc123">

Example Responses

The possible response codes are given here:

Response CodeDescription
201 CreatedItem successfully added to cart. Includes a cartItemID for the item that was added.
403 ForbiddenThe specified API key does not exist.
400 Bad RequestThe included parameter was either not passed or was not a valid URL.

When an item has been successfully added to the cart, a 201 Created response is returned. The response includes the system-generated cartItemID for the item. Use this cartItemID to get, update, or delete cart contents. A success response would look like:

HTTP/1.1 201 Created Location:
https://product.shopatron.com/cart/{cartID}/cartItems/{cartItemID}?api_key?={api_key}
Content-Type: application/json

{
  "cartItemId":1234
}

If an API key that does not exist is entered, a 403 Forbidden response is returned and no action is taken. This invalid API key error might return:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "additionalInfo": "Api_key: {api_key} is not valid”
}

If the value entered for the product, product link, or cart ID is not valid, a 404 Bad Request response is returned and no action is taken. The response would look like:

HTTP/1.1 404 Bad Request Content-Type: application/json

{
  "error": "Bad Request", "additionalInfo": "...”
}

Get Cart Data

Get data for all or part of a cart with the below request:

GET https://product.shopatron.com/cart/{cart_id}?api_key={api_key}

Where:

  • cart_ID is the ID of the cart to which the item will be added
  • api_key is the API key obtained from Kibo

Note that the request header should be “Content-Type: application/json.”

Parameters

The following parameters are usually returned in the GET response:

ParameterDescription
catalogIDThe manufacturer catalog ID.
quantityThe number of these items being added to the cart.
productThe URL of the product being added to the cart.
itemOptionsOptions that apply to the line item being added.
priceThe total cost of the item. Includes option additional price if any.
productLinkA link to the product detail page associated with this item.

Example Responses

The possible response codes are given here:

Response CodeDescription
200 OKSuccess response, with cart data.
403 ForbiddenAPI key does not exist.
404 Not FoundInvalid fragment.

When a valid cart ID or fragment and a valid API key are provided, a 200 OK success response is returned, along with the cart data. The cart data associated with the response is slightly different, depending on whether the data is for a complete cart or a partial cart. This first example displays the data for a complete cart:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "completedDate": null,
  "currency": "USD",
  "cartID": "6b98c08f38e5dc65583abd24b07e7ace",
  "createdDate": "2013-06-14T13:43:05-0700",
  "locale": "en-US",
  "externalCartID": null,
  "cartItems": {
    "8076a85ecb1f65018cace8030c3a3ba4": {
      "catalogID": "0",
      "quantity": 2,
      "price": "49.99",
      "product": "https://product.shopatron.com/product/100090?api_key=9ktd32ij&catalogID=0",
      "itemOptions": {
        "192511": "200259",
        "803881": "200404"
      },
      "productLink": "https://my.store.com/products/100090"
    },
    "8224ef50a37bc5954421e9e4826850dc": {
      "catalogID": "0",
      "quantity": 1,
      "price": "49.99",
      "product": "https://product.shopatron.com/product/100110?api_key=9ktd32ij&catalogID=0",
      "itemOptions": {
        "192512": "200260",
        "803881": "200405"
      },
      "productLink": "https://my.store.com/products/100110"
    }
  }
}

The following is a response for a partial cart:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "completedDate": null,
  "currency": "USD",
  "cartID": "6b98c08f38e5dc65583abd24b07e7ace",
  "createdDate": "2013-06-14T13:43:05-0700",
  "locale": "en-US",
  "externalCartID": null,
  "cartItems": {
    "8076a85ecb1f65018cace8030c3a3ba4": {
      "catalogID": "0",
      "quantity": 2,
      "price": "49.99",
      "product": "https://product.shopatron.com/product/100090?api_key=9ktd32ij&catalogID=0",
      "itemOptions": {
        "192511": "200259",
        "803881": "200404"
      },
      "productLink": "https://my.store.com/products/100090"
    },
    "8224ef50a37bc5954421e9e4826850dc": {
      "catalogID": "0",
      "quantity": 1,
      "price": "49.99",
      "product": "https://product.shopatron.com/product/100110?api_key=9ktd32ij&catalogID=0",
      "itemOptions": {
        "192512": "200260",
        "803881": "200405"
      },
      "productLink": "https://my.store.com/products/100110"
    }
  }
}

If an API key that does not exist is entered, a 403 Forbidden response is returned with no headers or additional data and no action is taken. This error response is displayed below:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "additionalInfo": "Api_key: {api_key} is not valid"
}

If an invalid cart ID or fragment is entered, a 404 Not Found code is returned and no action is taken.

HTTP/1.1 404 Not found
Content-Type: application/json

{
  error: "Not Found",
  additionalInfo: "The requested cart property:{fragment} does not exist in cartID:{cartID}"
}

Get Cart Item Data

Get data for a specific cart item with the following request:

GET
https://product.shopatron.com/cart/{cart_id}/cartItems/{cartItemID}?api_key={api_key
}

Where:

  • cart_ID is the ID of the cart to which the item will be added
  • cartItemID is the cartItemID for an item, as returned when the product was added to the cart, and is required only if a partial cart is being inquired about
  • api_key is the API key obtained from Kibo

Note that the request header should be “Content-Type: application/json.”

ParameterDescription
catalogIDThe manufacturer catalog ID.
quantityThe number of these items being added to the cart.
productThe URL of the product being added to the cart.
priceThe total cost of the item. Includes option additional price if any.
imageAn image of the product with the selected option.
itemOptionsOptions that apply to the line item being added.
productLinkA link to the product detail page associated with this item.

Example Responses

The possible response codes are given here. Details on each response code follow.

Response CodeDescription
200 OKSuccess response, with cart item data.
403 ForbiddenThe specified API key does not exist.
404 Not FoundInvalid fragment.

When a valid cart ID or fragment and a valid API key are provided, a 200 OK success response is returned, along with the cart item data. The cart item data associated with the response is slightly different, depending on whether the data is for a complete cart or a partial cart.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "product":"https://product.shopatron.com/product/abc123?api_key={api_key}", 
  "catalogID":1,
  "quantity":1, "price":"1.00",
  "image":"https://cdn.shptrn.com/...", "itemOptions":{
  "color":"Red",
  "size":"XL",
},
  "productLink":"https://lambo.cust.shopatron.com/products/abc123",
}

If an API key that does not exist is entered, a 403 Forbidden response is returned, with no headers or additional data and no action is taken.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "additionalInfo": "Api_key: {api_key} is not valid"
}

Get Product Data

Get data for a product in the cart by specifying its part number, as explained in detail below.

GET
https://product.shopatron.com/product/{partNumber}?api_key={api_key}&catalogID=
{catalogID}

Where:

  • partNumber is the part number for the product
  • api_key is the API key obtained from Kibo

Note that the request header should be “Accept: application/json.”

Parameters

The parameters returned in the response include:

ParametersOccursData TypeDescription
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 decimal.The price the product is selling for. Should not include currency symbols.
availability.codeMust 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
locale1An IETF locale codeThe locale for the product.
currency1ISO 4217The currency codes for the product.
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 the 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 definitionThe 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].rank1Any IntegerA ranking of the product with the selected option.
productOptions[groupID]. optionChoices.options [optionID].image0-1A URLA URL pointing to an option image.
optionSet0-nselectedOption elementsThis 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 Order Management shipping method ID.
customFields0-1AnythingAny custom data the client wants to store with the product. When products are coming from Kibo, specs will be populated here.

The possible response codes are given here. Details on each response code follow.

Response CodeDescription
200 OKSuccess response, with product data.
403 ForbiddenAPI key does not exist.
404 Not FoundNon-existent part number.

When a valid part number and a valid API key are provided, a 200 OK success response is returned, along with the cart data.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "partNumber": "100060",
  "name": "Many slaved options",
  "price": "49.99",
  "availability": {
    "code": "M"
  },
  "averageDealerMargin": "0.40",
  "locale": "en-US",
  "currency": "USD",
  "description": "Sizes:<br>\n<b>S (32BC-34B)<br>\nM (34BC-36B)<br>\nL (36BC- 38B)<br>\nXL (38BC-40B)<br></b>\nBody: 88% polyester / 12% Lycra®<br>\nFront Lining: 72% polyester / 21% Sorbtek®/ 7% spandex spacer fabric<br>\nBack Lining: Powermesh 83% nylon / 17% Lycra®",
  "image": "https://cdn.shptrn.com/media/mfg/2230/product_image/123f1abb0704fa5d6893cb6 4ada9e2ac.jpg?1330767605",
  "images": [
    {
      "url": "https://cdn.shptrn.com/media/mfg/2230/product_image/123f1abb0704fa5d6893cb6 4ada9e2ac.jpg?1330767605"
    },
    {
      "name": "Front",
      "url": "https://cdn.shptrn.com/media/mfg/2230/product_image/x1_123f1abb0704fa5d6893 cb64ada9e2ac.jpg?1330767605"
    }
  ],
  "productOptions": {
    "192502": {
      "displayName": "Size",
      "description": null,
      "rank": 14,
      "optionChoices": {
        "options": {
          "200259": {
            "displayName": "Small",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "1"
          },
          "200260": {
            "displayName": "Medium",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "2"
          },
          "200389": {
            "displayName": "Large",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "3"
          }
        }
      }
    },
    "192503": {
      "displayName": "Size",
      "description": null,
      "rank": 12,
      "optionChoices": {
        "options": {
          "200259": {
            "displayName": "Small",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "2"
          },
          "200260": {
            "displayName": "Medium",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "3"
          },
          "200389": {
            "displayName": "Large",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "4"
          },
          "200391": {
            "displayName": "Extra-Small",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "1"
          }
        }
      }
    },
    "793993": {
      "displayName": "Color",
      "description": null,
      "rank": 10,
      "optionChoices": {
        "options": {
          "200258": {
            "displayName": "Black",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "1",
            "image": "https://cdn.shptrn.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c b64ada9e2ac_793993_200258.jpg?1330767605"
          },
          "200390": {
            "displayName": "White",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "2",
            "image": "https://cdn.shptrn.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c b64ada9e2ac_793993_200390.jpg?1330767605"
          },
          "200392": {
            "displayName": "Green",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "3",
            "image": "https://cdn.shptrn.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c b64ada9e2ac_793993_200392.jpg?1330767605"
          },
          "200393": {
            "displayName": "Blue",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "4",
            "image": "https://cdn.shptrn.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c b64ada9e2ac_793993_200393.jpg?1330767605"
          }
        }
      }
    },
    "794203": {
      "displayName": "Size",
      "description": null,
      "rank": 15,
      "optionChoices": {
        "options": {
          "200259": {
            "displayName": "Small",
            "description": null,
            "additionalPrice": "0.00",
            "rank": "1"
          }
        }
      }
    }
  },
  "optionSets": [
    {
      "selectedOptions": {
        "192502": "200259",
        "793993": "200258"
      }
    },
    {
      "selectedOptions": {
        "192502": "200260",
        "793993": "200258"
      }
    },
    {
      "selectedOptions": {
        "192502": "200389",
        "793993": "200258"
      }
    },
    {
      "selectedOptions": {
        "192503": "200391",
        "793993": "200390"
      }
    },
    {
      "selectedOptions": {
        "192503": "200259",
        "793993": "200390"
      }
    },
    {
      "selectedOptions": {
        "192503": "200260",
        "793993": "200390"
      }
    },
    {
      "selectedOptions": {
        "192503": "200389",
        "793993": "200390"
      }
    },
    {
      "selectedOptions": {
        "793993": "200392",
        "794203": "200259"
      }
    },
    {
      "selectedOptions": {
        "192502": "200259",
        "793993": "200393"
      }
    },
    {
      "selectedOptions": {
        "192502": "200260",
        "793993": "200393"
      }
    },
    {
      "selectedOptions": {
        "192502": "200389",
        "793993": "200393"
      }
    }
  ],
  "shippingMethod": "3",
  "customFields": [
    {
      "name": "Hidden Spec",
      "description": "Hidden Spec Value",
      "specType": "hidden"
    },
    {
      "name": "Sizing Chart",
      "description": "Download Sizing Chart (PDF)",
      "specType": "file",
      "specResource": "https://cdn.shptrn.com/media/mfg/2230/spec_file/24148092.pdf?1307492349"
    },
    {
      "name": "GlobalImageSpec",
      "description": "BR flag (global image)",
      "specType": "global_image",
      "specResource": "https://cdn.shptrn.com/media/mfg/2230/spec_file/g_br.jpg?1307492349"
    },
    {
      "name": "Size",
      "description": "Big",
      "specType": "text"
    },
    {
      "name": "UniqueImageSpec",
      "description": "JM flag (unique image)",
      "specType": "unique_image",
      "specResource": "https://cdn.shptrn.com/media/mfg/2230/spec_file/24041865.jpg?1307492349"
    }
  ]
}

If an API key that does not exist is entered, a 403 Forbidden response is returned, with no headers or additional data. No action is taken.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  error: "Forbidden",
  additionalInfo: "Api_key:{api_key} is not valid"
}

If the value entered for the part number is not valid, a 404 Not Found code is returned. No action is taken.

HTTP/1.1 404 Not found
Content-Type: application/json

{
  error: "Not Found",
  additionalInfo: "No such product:{partNumber}"
}

Remove an Item from a Cart

It is possible to remove line items from a shopping cart using the DELETE method. If there is more than one of this item in the cart, all of them will be removed.

DELETE https://product.shopatron.com/cart/{cartID}/cartItems/{cartItemID}?api_key={api_key}

Where:

  • cartID is the ID of the cart from which the line item is being removed
  • cartItemID is the ID of the item being removed, as returned by Add Item to Cart
  • api_key is the API key obtained from Kibo

Note that the request header should be “Content-Type: application/json.”

Example Responses

The possible response codes are given here. Details on each response code follow.

Response CodeDescription
204 No ContentItem was removed as requested.
403 ForbiddenAPI key does not exist.

When the item has been removed as requested, a 204 No Content response is returned.

HTTP/1.1 204 No Content

If the API key entered does not exist, a 403 Forbidden response is returned, with no headers or additional data.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  error: "Forbidden",
  additionalInfo: "Api_key:{api_key} is not valid"
}

Update the Quantity of an Item in a Cart

The quantity can be changed for any line item in a cart, provided that the Cart ID and Item ID are known. To update the quantity, use the PUT method as follows:

PUT
https://product.shopatron.com/cart/{cartID}/cartItems/{cartItemID}/quantity?api_key={api_key} Content-Type: application/json

Where:

  • cartID is the cart ID for the cart that the item is in
  • cartItemID is the Kibo-assigned item ID for the item, as returned by Add Item to Cart
  • api_key is the API key obtained from Kibo

Note that the request header should be “Content-Type: application/json.”

The request data should include the new quantity for the item. This example specifies a new quantity of 2, regardless of the current quantity of that item.

2

Example Responses

The possible response codes are given here. Details on each response code follow.

Response CodeDescription
204 No ContentQuantity was updated as requested.
403 ForbiddenAPI key does not exist.

When a valid API key, cart ID, and cart item ID are entered and the quantity has been modified as requested, a 204 No Content response is returned:

HTTP/1.1 204 No Content

If an invalid API key is provided, then the following error would occur:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "additionalInfo": "Api_key: {api_key} is not valid"
}

A nonexistent cart ID would return the following error:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Not Found",
  "additionalInfo": "The requested cart property: {cartItemID} does not exist in cartID: {cartID}"
}

Proceed to Checkout

Use this call 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.

This uses the loadOrder API the same way a CFE does. 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.

The request should be:

POST https://product.shopatron.com/cart/{cartID}?api_key={api_key}

Where:

  • cartID is the cart ID for the cart that the item is in
  • api_key is the API key obtained from Kibo

Note that the request header should be “Content-Type: application/json.”

The request data should include the quantity for the item. This example sets the new quantity to 6, regardless of the current quantity of that item.

{
  "catalogID": 6
}

Example Responses

The following parameters are included in a response:

ParameterDescription
checkoutOptions. catalogIDThis optional parameter can be used to override which checkout catalog the cart is loaded into.
options.successUse the success function to override the default functionality of automatically redirecting to checkout.
options.errorIf the request fails, provide some feedback to the user.
options.completeThis could be used to remove some processing graphic whether the request was successful or not.

The possible response codes are given here. Details on each response code follow.

Response CodeDescription
201 CreatedQuantity was updated as requested.
403 ForbiddenAPI key is not valid.

When a valid API key, cart ID, and cart item ID are entered and the quantity has been modified as requested, a 201 Created response is returned:

HTTP/1.1 201 Created
Content-Type: application/json Location: https://...

{
  "checkoutLink": "https://..."
}

If an invalid API key is provided, then the following error response is returned:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "additionalInfo": "Api_key: {api_key} is not valid"
}

Product Data Fields

These values can be defined for a product:

ParameterData TypeDescription
partNumberA 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.
nameA string of at least one character. Line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces are not allowed.The product name.
priceA decimal number greater than 0.00 with two places after the decimalThe price the product is selling for and should not include currency symbols.
availability.codeString that 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).
averageDealerMarginAn 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
localeAn IETF locale codeThe locale for the product.
currencyISO 4217The currency codes for the product.
imageA URLA URL pointing to the product image.
imagesAn array of ObjectsEach object in the array describes an image. The array is ordered by image rank starting with the primary image.
images[].nameAny StringA label for the image.
images[].urlA URLAn image resource.
descriptionAny StringA short description of the product.
VATRateA number between 0 and 1Only appears for catalogs that use VAT.
productOptionsObjectA mapping of optionName to the product option definition.
productOptions[groupID]. displayNameAny 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]. descriptionAny StringA description of the option group.
productOptions[groupID]. optionChoices.optionsAn 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]An Option definition.The set of options available for this group.
optionIDA 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].displayNameAny StringUse this if the option value to be stored differs from the value that should be displayed.
productOptions[groupID]. optionChoices.options [optionID].descriptionAny StringA description of the optionID choice.
productOptions[groupID]. optionChoices.options [optionID].additionalPriceA 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].rankAny IntegerAn option rank that can be useful when building UIs.
productOptions[groupID]. optionChoices.options [optionID].imageA URLA URL pointing to an option image.
optionSetselectedOption elementsThis defines a valid combination of options. It can be used to describe slaved options.
optionSets.selectedOptionsAn Object with groupId-optionId pairsThe value of the selected option.
weightObjectIf weight based shipping is being used, the weight of the product needs to be known.
weight.valueA decimal numberIf weight based shipping is being used, the weight of the product needs to be known.
weight.unitsMust be one of (lb|kg)Units for this product’s weight. Used for weight-based shipping.
shippingMethodA non-negative IntegerThis is a Kibo Order Management shipping method ID.
customFieldsAny valueAny custom data the client wants to store with the product. When products are coming from Kibo, specs will be populated here.

Cart Data Fields

These values can be defined for a cart:

ParameterData TypeDescription
cartIDStringA unique identifier for this cart.
createdDateStringA date in ISO 8601 format indicating when the cart was first created.
completedDateStringA date in ISO 8601 format indicating when the cart has 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, it passes returns this value. 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]. catalogIDIntThe catalog that this product is in.
cartItems[cartItemID]. quantityIntThe 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.