Welcome
ADD TO CART XML API GUIDE 11/11/13 | PAGE 1
SHOPATRON INTEGRATION TOOLSET
Add to Cart Developer’s Guide FOR USE WITH SHOPATRON'S ADD TO CART SOFTWARE
Revision History
Revision/
Version
Number
Summary of Modifications Date Author/Writer Subject Matter
Expert(s)
Not
Applicable
Converted to new branding
template; minor style and
format modifications.
May 31, 2013 Michael Lujan Dave Miller
Not
Applicable
Updates to samples and
parameters.
August 26, 2013 Michael Lujan Dave Miller,
Jason Desrosiers
Not
Applicable
Updates to include the catalog
override capability and minor
changes to clarify some of the
samples.
November 4, 2013 Michael Lujan Dave Miller,
Jason Desrosiers
Copyright © 2013 Shopatron, Inc.
Add to Cart Developer’s Guide
This document contains proprietary and confidential information of Shopatron, Inc., and is
protected by Federal copyright law. The contents of this document may not be disclosed to
third parties, translated, copied, or duplicated in any form, in whole or in part, (or by any
means, electronic, mechanical, photocopying, or otherwise) without the express written
permission of Shopatron, Inc.
The information contained in this document is subject to change without notice. Neither
Shopatron, Inc., its affiliates, nor their directors, officers, employees, or agents, are
responsible for punitive or multiple damages or lost profits or other special, direct, indirect,
incidental, or consequential damages, including any damages resulting from loss of business
arising out of or resulting from the use of this material, or for technical or editorial omissions or
errors made in it.
Aspects of the Shopatron network are patented, patent-pending, or patent-applied for.
Shopatron North America
Shopatron, Inc.
P.O. Box 5351
San Luis Obispo, CA, 93403
Shopatron Europe
Shopatron UK, Ltd.
Newport House
19-21 Newport Street
Old Town, Swindon SN1 3DX
Contents
Welcome ...................................................................................................................... 6
About this Document .................................................................................................. 6
About the REST API .................................................................................................... 6
Add a Product to a Cart .............................................................................................. 6
Request ............................................................................................................................... 6
Request data ....................................................................................................................... 7
Mandatory request parameters .......................................................................................... 7
Optional request parameters ............................................................................................. 7
Possible responses ............................................................................................................ 8
Success response .............................................................................................................. 8
Error response: Invalid API key ......................................................................................... 8
Error response: Invalid product, product link, or cart ID ................................................. 8
Example ............................................................................................................................... 9
Request ............................................................................................................................. 9
Response .......................................................................................................................... 9
Get Cart Data ............................................................................................................... 9
Request headers ................................................................................................................. 9
Request data ....................................................................................................................... 9
Possible responses .......................................................................................................... 10
Success response ............................................................................................................ 10
Success response for complete cart ................................................................................ 10
Success response for partial cart ..................................................................................... 11
Response fields ............................................................................................................... 11
Error response: Invalid API key ....................................................................................... 11
Error response: Non-existent fragment .......................................................................... 12
Get CartItem Data ...................................................................................................... 12
Request headers ............................................................................................................... 12
Request data ..................................................................................................................... 12
Possible responses .......................................................................................................... 12
Success response ............................................................................................................ 13
Response fields ............................................................................................................... 13
Error response: Invalid API key ....................................................................................... 13
Get Product Data ....................................................................................................... 14
Request ............................................................................................................................. 14
Request headers ............................................................................................................... 14
Request data ..................................................................................................................... 14
Possible responses .......................................................................................................... 14
Success response ............................................................................................................ 14
Response fields ............................................................................................................... 18
Error response: Invalid API key ....................................................................................... 22
Error response: Non-existent part number ..................................................................... 22
Remove an Item from a Cart ..................................................................................... 22
Request ............................................................................................................................. 22
Request headers ............................................................................................................... 23
Request data ..................................................................................................................... 23
Possible responses .......................................................................................................... 23
Success response ............................................................................................................ 23
Error response: Invalid API key ....................................................................................... 23
Example ............................................................................................................................. 23
Request ........................................................................................................................... 23
Response ........................................................................................................................ 23
Update the Quantity of an Item in a Cart ................................................................. 24
Request ............................................................................................................................. 24
Request headers ............................................................................................................... 24
Request data ..................................................................................................................... 24
Possible responses .......................................................................................................... 24
Success response ............................................................................................................ 25
Error response: Invalid API key ....................................................................................... 25
Error response: Non-existent CartItemID ........................................................................ 25
Example ............................................................................................................................. 25
Request ........................................................................................................................... 25
Response ........................................................................................................................ 25
Proceed to Checkout ................................................................................................ 25
Request ............................................................................................................................. 26
Request headers ............................................................................................................... 26
Request data ..................................................................................................................... 26
Possible responses .......................................................................................................... 26
Success response ............................................................................................................ 26
Response fields ............................................................................................................... 27
Error response: Invalid API key ....................................................................................... 27
Product Data Fields ................................................................................................... 27
Cart Data Fields ......................................................................................................... 31
Welcome
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 6
Welcome
Now it's easy to add Shopatron eCommerce to your product pages. By integrating a Shopatron online
store into your website, you can access an established international dealer base for your order fulfillment.
You can use the Add to Cart APIs to include Add to Cart buttons on your web pages, provide a Quick
Cart view, and display a shopping cart. The shopping cart page can be a standard Shopatron cart, a
stylized version of a Shopatron cart, or a cart that you design to coordinate with your website.
With our 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.
About this Document
This Developer's Guide describes how to can use Shopatron's REST API to add eCommerce to your
product pages. The REST APIs make it possible for experienced developers to add Shopatron checkout
to brand websites.
For those who do not have development expertise, we've created other ways to implement Shopatron
eCommerce solutions. For details, see these related documents:
Using the Add to Cart API with XML – the simplest way to implement Shopatron's Add to Cart
Using the Add to Cart API with JavaScript – a more flexible approach, which requires a little more
technical savvy
JSON for Add to Cart –can be used with the JavaScript approach for additional control
About the REST API
This document describes how to use our REST API to implement a Shopatron cart solution.
REpresentational State Transfer (REST) is a style of software architecture for distributed systems such as
the World Wide Web. REST has emerged as a predominant Web service design model. See Wikipedia
(http://en.wikipedia.org/wiki/REST) for additional information about REST.
Add a Product to a Cart
You can use the REST API to add a line item to an existing Shopatron cart. To add the line item, you use
the POST method and include data about the line item you want to add.
Request
POST http://product.shopatron.com/cart/{cartID}/cartItems?api_key={api_key}
Add a Product to a Cart
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 7
Where:
cartID is the ID of the cart to which the line item is being added. This value is a unique identifier that
you create for the cart
api_key is the API key you obtained from Shopatron
Request data
The format of the data to POST follows:
Accept: application/json
{
"product":
"http://product.shopatron.com/product/abc123?api_key=asdf1234&catalogID=1",
"catalogID": 1,
"quantity": 1,
"itemOptions": {
"192512": "200260",
"803881": "200405"
},
"productLink": "http://product.shopatron.com/products/abc123"
}
Mandatory request parameters
Your request must include these parameters.
Parameter Description
product The REST resource for the product.
productLink The direct link to the product detail page.
Optional request parameters
Parameter Description
catalogID The manufacturer catalog ID for the product. If omitted, the default catalog that is
configured for this API key is used.
quantity How many of this product to add. Defaults to 1 if not included.
itemOptions Options that apply to the line item being added. In the preceding code, options include
values for color and size.
Add a Product to a Cart
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 8
Possible responses
The possible response codes are given here. Details on each response code follow.
Response Code Description
201 Created Item successfully added to cart. Includes a cartItemID for the item that was added.
403 Forbidden The specified API key does not exist.
400 Bad Request The included parameter was either not passed or was not a valid URL.
Success response
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. You will need this cartItemID to
get, update, or delete cart contents.
HTTP/1.1 201 Created
Location:
http://product.shopatron.com/cart/{cartID}/cartItems/{cartItemID}?api_key?={api_key
}
Content-Type: application/json
{"cartItemId":1234}
Error response: Invalid API key
If you enter an API key that does not exist, a 403 Forbidden response is returned. No action is taken.
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "Forbidden",
"additionalInfo": "Api_key: {api_key} is not valid”
}
Error response: Invalid product, product link, or cart ID
If the value you enter for the product, product link, or cart ID is not valid, a 404 Bad Request response
is returned. No action is taken.
HTTP/1.1 404 Bad Request
Content-Type: application/json
{
"error": "Bad Request",
"additionalInfo": "...”
}
Get Cart Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 9
Example
Request
To add a line item to a cart with cartID 4ee8e29d45851, using API key xmvhrhuw:
POST http://product.shopatron.com/cart/4ee8e29d45851/cartItems?api_key=xmvhrhuw
Accept: application/json
Content-Type: application/json
{
"catalogID": 1,
"quantity": 1,
"product":
"http://product.shopatron.com/product/100001?api_key=xmvhrhuw&catalogID=1",
"itemOptions": {
"color": "Red",
"size": "XL"
},
"productLink": "http://my.store.com/products/abc123"
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
Location:
http://product.shopatron.com/cart/4ee8e29d45851/cartItems/098765?api_key=xmvhrhuw
{
"cartItemID":"098765"
}
Get Cart Data
You can get data for all or part of a Shopatron cart, as follows:
GET http://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 you obtained from Shopatron
Request headers
Content-Type: application/json
Request data
None
Get Cart Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 10
Possible responses
The possible response codes are given here. Details on each response code follow.
Response Code Description
200 OK Success response, with cart data.
403 Forbidden API key does not exist.
404 Not Found Invalid fragment.
Success response
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.
Success response for complete cart
Success response for 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":
"http://product.shopatron.com/product/100090?api_key=9ktd32ij&catalogID=0",
"itemOptions": {
"192511": "200259",
"803881": "200404"
},
"productLink": "http://my.store.com/products/100090"
},
"8224ef50a37bc5954421e9e4826850dc": {
"catalogID": "0",
"quantity": 1,
"price": "49.99",
"product":
"http://product.shopatron.com/product/100110?api_key=9ktd32ij&catalogID=0",
"itemOptions": {
"192512": "200260",
"803881": "200405"
},
"productLink": "http://my.store.com/products/100110"
Get Cart Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 11
Success response for complete cart
}
}
}
Success response for partial cart
HTTP/1.1 200 OK
Content-Type: application/json
{
"catalogID":1,
"quantity":1,"price":"49.99",
"product":"http://product.shopatron.com/product/{partNumber}?api_key={api_Key}
&catalogID=1",
"itemOptions":{
"color":"Red",
"size":"XL"
},
"productLink":"http://www.shopatron.com/home/index/18.0/prod/100001"
}
Response fields
Parameter Description
catalogID The manufacturer catalog ID.
quantity The number of these items being added to the cart.
product The URL of the product being added to the cart.
itemOptions Options that apply to the line item being added.
price The total cost of the item. Includes option additional price if any.
productLink A link to the product detail page associated with this item.
Error response: Invalid API key
If you enter an API key that does not exist, 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"
}
Get CartItem Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 12
Error response: Non-existent fragment
If the value you enter for the cart ID or fragment 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: "The requested cart property:{fragment} does not exist in
cartID:{cartID}"
}
Get CartItem Data
You can get data for a specific cart item as follows:
GET
http://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 you added the product to the cart, and
is required only if a partial cart is being inquired about
api_key is the API key you obtained from Shopatron
Request headers
Content-Type: application/json
Request data
None
Possible responses
The possible response codes are given here. Details on each response code follow.
Response Code Description
200 OK Success response, with cart item data.
403 Forbidden The specified API key does not exist.
404 Not Found Invalid fragment.
Get CartItem Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 13
Success response
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":"http://product.shopatron.com/product/abc123?api_key={api_key}",
"catalogID":1,
"quantity":1,
"price":"1.00",
"image":"http://mediacdn.shopatron.com/...",
"itemOptions":{
"color":"Red",
"size":"XL",
},
"productLink":"http://lambo.cust.shopatron.com/products/abc123",
}
Response fields
Parameter Description
catalogID The manufacturer catalog ID.
quantity The number of these items being added to the cart.
product The URL of the product being added to the cart.
price The total cost of the item. Includes option additional price if any.
image An image of the product with the selected option.
itemOptions Options that apply to the line item being added.
productLink A link to the product detail page associated with this item.
Error response: Invalid API key
If you enter an API key that does not exist, 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"
}
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 14
Get Product Data
You can get data for a product in the cart by specifying its part number, as explained in detail below.
Request
GET
http://product.shopatron.com/product/{partNumber}?api_key={api_key}&catalogID=
{catalogID}
Where:
partNumber is the part number for the product for which you want to get information
api_key is the API key you obtained from Shopatron
Request headers
Accept: application/json
Request data
None
Possible responses
The possible response codes are given here. Details on each response code follow.
Response Code Description
200 OK Success response, with product data.
403 Forbidden API key does not exist.
404 Not Found Non-existent part number.
Success response
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",
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 15
"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":
"http://mediacdn.shopatron.com/media/mfg/2230/product_image/123f1abb0704fa5d6893cb6
4ada9e2ac.jpg?1330767605",
"images": [
{
"url":
"http://mediacdn.shopatron.com/media/mfg/2230/product_image/123f1abb0704fa5d6893cb6
4ada9e2ac.jpg?1330767605"
},
{
"name": "Front",
"url":
"http://mediacdn.shopatron.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": {
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 16
"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":
"http://mediacdn.shopatron.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c
b64ada9e2ac_793993_200258.jpg?1330767605"
},
"200390": {
"displayName": "White",
"description": null,
"additionalPrice": "0.00",
"rank": "2",
"image":
"http://mediacdn.shopatron.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c
b64ada9e2ac_793993_200390.jpg?1330767605"
},
"200392": {
"displayName": "Green",
"description": null,
"additionalPrice": "0.00",
"rank": "3",
"image":
"http://mediacdn.shopatron.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c
b64ada9e2ac_793993_200392.jpg?1330767605"
},
"200393": {
"displayName": "Blue",
"description": null,
"additionalPrice": "0.00",
"rank": "4",
"image":
"http://mediacdn.shopatron.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c
b64ada9e2ac_793993_200393.jpg?1330767605"
}
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 17
}
}
},
"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":
"http://mediacdn.shopatron.com/media/mfg/2230/spec_file/24148092.pdf?1307492349"
},
{
"name": "GlobalImageSpec",
"description": "BR flag (global image)",
"specType": "global_image",
"specResource":
"http://mediacdn.shopatron.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",
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 18
"specResource":
"http://mediacdn.shopatron.com/media/mfg/2230/spec_file/24041865.jpg?1307492349"
}
]
}
Response fields
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. Should not include currency
symbols.
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 19
Parameter Occurs Type Description
availability.code 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. Can be
preordered.
D (Discontinued). The item is
discontinued. We will attempt
to find it.
I (Digital Content). This item
is available for immediate
download.
S (Ship to Store Only). This
item is Ship to Store Only.
averageDealerMargin 1 An 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 An IETF locale
code
The locale for the product.
currency 1 ISO 4217 The currency codes for the
product.
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.
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 20
Parameter Occurs Type Description
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 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].
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.
Get Product Data
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 21
Parameter Occurs Type Description
productOptions[groupID].
optionChoices.options
[optionID].displayName
0-1 Any String Use this if the option value you
want to store differs from the
value you want 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].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.
optionSet 0-n selectedOption
elements
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 we are using weight based
shipping, we need to know the
weight of the product.
weight.value 1 A decimal number If we are using weight based
shipping, we need to know the
weight of the product.
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 Shopatron shipping
method ID.
Remove an Item from a Cart
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 22
Parameter Occurs Type Description
customFields 0-1 Anything Any custom data the client wants
to store with the product. When
products are coming from
Shopatron, specs will be
populated here.
Error response: Invalid API key
If you enter an API key that does not exist, 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"
}
Error response: Non-existent part number
If the value you enter 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.
Request
DELETE http://product.shopatron.com/cart/{cartID}/cartItems/{cartItemID}?api_key={api_key}
Where:
cartID is the ID of the cart from which you are removing the line item
cartItemID is the ID of the item you are removing, as returned by Add Item to Cart
api_key is the API key you obtained from Shopatron
Remove an Item from a Cart
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 23
Request headers
Content-Type: application/json
Request data
None
Possible responses
The possible response codes are given here. Details on each response code follow.
Response Code Description
204 No Content Item was removed as requested.
403 Forbidden API key does not exist.
Success response
When the item has been removed as requested, a 204 No Content response is returned.
HTTP/1.1 204 No Content
Error response: Invalid API key
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"
}
Example
Request
To remove a line item with item ID 200001 from a cart that has cart ID 12345 using API key xmvhrhuw:
DELETE http://product.shopatron.com/cart/12345/cartItems/200001?api_key=xmvhrhuw
Accept: application/json
Response
The 404 Not Found response informs you that the item does not exist the cart.
HTTP/1.1 404 Not Found
Update the Quantity of an Item in a Cart
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 24
Content-Type: application/json
{
"error": "Not Found",
"additionalInfo": "The requested cart property: {cartItemID} does not exist
in cartID: {cartID}"
}
Update the Quantity of an Item in a Cart
You can change the quantity for any line item in a cart, provided that you have the Cart ID and Item ID.
To update the quantity, you would use the PUT method, as follows:
Request
PUT
http://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 Shopatron-assigned item ID for the item, as returned by Add Item to Cart
api_key is the API key you obtained from Shopatron
Request headers
Content-Type: application/json
Request data
Your request should include the new quantity for the item. For example, you would include a 2, regardless
of the current quantity of that item.
2
Possible responses
The possible response codes are given here. Details on each response code follow.
Response Code Description
204 No Content Quantity was updated as requested.
403 Forbidden API key does not exist.
Proceed to Checkout
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 25
Success response
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
Error response: Invalid API key
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "Forbidden",
"additionalInfo": "Api_key: {api_key} is not valid"
}
Error response: Non-existent CartItemID
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}"
}
Example
Request
To change the quantity to 4 for a line item in cart 12345 with Cart Item ID 200001:
PUT
http://product.shopatron.com/cart/12345/cartItems/200001/quantity?api_key=xmvhrhuw
Accept: application/json
Content-Type: application/json
4
Response
A 204 No Content response tells you that the quantity update was successful:
HTTP/1.1 204 No Content
Proceed to Checkout
Use this call to load the cart into Shopatron 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.
Proceed to Checkout
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 26
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 Shopatron
checkout.
Request
POST http://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 you obtained from Shopatron
Request headers
Content-Type: application/json
Request data
Your request should include the quantity for the item. For example, you would include a 6, regardless of
the current quantity of that item.
{
"catalogID": 6
}
Possible responses
The possible response codes are given here. Details on each response code follow.
Response Code Description
201 Created Quantity was updated as requested.
403 Forbidden API key is not valid.
Success response
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://..."
}
Product Data Fields
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 27
Response fields
Parameter Description
checkoutOptions.
catalogID
This optional parameter can be used to override which checkout catalog the cart is
loaded into.
options.success Use the success function to override the default functionality of automatically
redirecting to checkout.
options.error If the request fails, provide some feedback to the user.
options.complete This could be used to remove some processing graphic whether the request was
successful or not.
Error response: Invalid API key
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:
Parameter Type Description
partNumber 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 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.
Product Data Fields
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 28
Parameter Type Description
price 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.
availability.code String 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. Can be
preordered.
D (Discontinued). The item is
discontinued. We will attempt
to find it.
I (Digital Content). This item
is available for immediate
download.
S (Ship to Store Only). This
item is Ship to Store Only.
averageDealerMargin An 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 An IETF locale code The locale for the product.
currency ISO 4217 The currency codes for the
product.
image A URL A URL pointing to the product
image.
Product Data Fields
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 29
Parameter Type Description
images 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 Any String A label for the image.
images[].url A URL An image resource.
description Any String A short description of the
product.
VATRate 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
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
Any String A description of the option group.
productOptions[groupID].
optionChoices.options
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]
An Option definition. The set of options available for
this group.
optionID 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.
Product Data Fields
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 30
Parameter Type Description
productOptions[groupID].
optionChoices.options
[optionID].displayName
Any String Use this if the option value you
want to store differs from the
value you want displayed.
productOptions[groupID].
optionChoices.options
[optionID].description
Any String A description of the optionID
choice.
productOptions[groupID].
optionChoices.options
[optionID].additionalPrice
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].rank
Any Integer An option rank that can be useful
when building UIs.
productOptions[groupID].
optionChoices.options
[optionID].image
A URL A URL pointing to an option
image.
optionSet selectedOption
elements
This defines a valid combination
of options. It can be used to
describe slaved options.
optionSets.selectedOptions An Object with
groupId-optionId pairs
The value of the selected option.
weight Object If we are using weight based
shipping, we need to know the
weight of the product.
weight.value A decimal number If we are using weight based
shipping, we need to know the
weight of the product.
weight.units Must be one of (lb|kg) Units for this product's weight.
Used for weight-based shipping.
shippingMethod A non-negative
Integer
This is a Shopatron shipping
method ID.
customFields Any value Any custom data the client wants
to store with the product. When
products are coming from
Shopatron, specs will be
populated here.
Cart Data Fields
ADD TO CART DEVELOPER’S GUIDE 11/11/13 | PAGE 31
Cart Data Fields
These values can be defined for a cart:
Parameter Type Description
cartID String A unique identifier for this cart.
createdDate String A date in ISO 8601 format indicating when the cart
was first created.
completedDate String A date in ISO 8601 format indicating when the cart
has 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, it passes
returns this value. 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
Int The catalog that this product is in.
cartItems[cartItemID].
quantity
Int 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.