Welcome SHOPATRON INTEGRATION TOOLSET Add to Cart ...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

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



Response fields ............................................................................................................... 13


Get Product Data ....................................................................................................... 14

Request ............................................................................................................................. 14

Request headers ............................................................................................................... 14

Request data ..................................................................................................................... 14



Response fields ............................................................................................................... 18


Error response: Non-existent part number ..................................................................... 22

Remove an Item from a Cart ..................................................................................... 22

Request ............................................................................................................................. 22

Request headers ............................................................................................................... 23

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




Error response: Non-existent CartItemID ........................................................................ 25

Example ............................................................................................................................. 25

Request ........................................................................................................................... 25

Response ........................................................................................................................ 25

Proceed to Checkout ................................................................................................ 25

Request ............................................................................................................................. 26

Request headers ............................................................................................................... 26

Request data ..................................................................................................................... 26



Response fields ............................................................................................................... 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}

http://product.shopatron.com/cart/%7bcartID%7d/cartItems?api_key=%7bapi_key%7d



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


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.



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


{

"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


{

"error": "Bad Request",

"additionalInfo": "...”

}

Get Cart Data


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



{

"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



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


Request headers


Request data

None

http://product.shopatron.com/cart/4ee8e29d45851/cartItems/098765?api_key=xmvhrhuw

Get Cart Data


Possible responses



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


HTTP/1.1 200 OK


{

"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



}

}

}

Success response for partial cart

HTTP/1.1 200 OK


{

"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


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.


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.



{


"additionalInfo": "Api_key: {api_key} is not valid"

}

Get CartItem Data


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


{

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


Request headers


Request data

None

Possible responses



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


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


{

"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


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.






{



}

Get Product Data


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


Request headers


Request data

None

Possible responses



200 OK Success response, with product data.


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


{

"partNumber": "100060",

"name": "Many slaved options",

"price": "49.99",

"availability": { "code": "M" },

"averageDealerMargin": "0.40",

"locale": "en-US",

Get Product Data


"currency": "USD",

"description": "Sizes: \nS (32BC-34B) \nM (34BC-36B) \nL (36BC-

38B) \nXL (38BC-40B) \nBody: 88% polyester / 12% Lycra® \nFront

Lining: 72% polyester / 21% Sorbtek®/ 7% spandex spacer fabric \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",


"additionalPrice": "0.00",

"rank": "1"

},

"200260": {

"displayName": "Medium",



"rank": "2"

},

"200389": {

"displayName": "Large",



"rank": "3"

}

}

}

},

"192503": {



"rank": 12,

"optionChoices": {

"options": {

"200259": {




"rank": "2"

},

"200260": {

Get Product Data


"displayName": "Medium",



"rank": "3"

},

"200389": {

"displayName": "Large",



"rank": "4"

},

"200391": {

"displayName": "Extra-Small",



"rank": "1"

}

}

}

},

"793993": {

"displayName": "Color",


"rank": 10,

"optionChoices": {

"options": {

"200258": {

"displayName": "Black",



"rank": "1",

"image":

"http://mediacdn.shopatron.com/media/mfg/2230/option_image/x2_123f1abb0704fa5d6893c

b64ada9e2ac_793993_200258.jpg?1330767605"

},

"200390": {

"displayName": "White",



"rank": "2",

"image":


b64ada9e2ac_793993_200390.jpg?1330767605"

},

"200392": {

"displayName": "Green",



"rank": "3",

"image":


b64ada9e2ac_793993_200392.jpg?1330767605"

},

"200393": {

"displayName": "Blue",



"rank": "4",

"image":


b64ada9e2ac_793993_200393.jpg?1330767605"

}

Get Product Data


}

}

},

"794203": {



"rank": 15,

"optionChoices": {

"options": {

"200259": {




"rank": "1"

}

}

}

}

},

"optionSets": [

{ "selectedOptions": { "192502": "200259", "793993": "200258" } },










{ "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


"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



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



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.


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.



[optionId]

1-n An option

definition


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





[optionID].displayName

0-1 Any String Use this if the option value you

want to store differs from the

value you want displayed.



[optionID].description

0-1 Any String A description of the optionID

choice.



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



[optionId].rank

1 Any Integer A ranking of the product with the

selected option.



[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



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



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: "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


{

error: "Not Found",

additionalInfo: "No such product:{partNumber}"

}


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




Request headers


Request data

None

Possible responses



204 No Content Item was removed as requested.


Success response

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.



{

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


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



{

"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}


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


Request headers


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



204 No Content Quantity was updated as requested.


Proceed to Checkout


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:





{



}

Error response: Non-existent CartItemID

HTTP/1.1 404 Not Found


{

"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



4

Response

A 204 No Content response tells you that the quantity update was successful:


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


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


Request headers


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



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:



Location: https://...

{

"checkoutLink": "https://..."

}

Product Data Fields


Response fields


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.




{



}

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



and multiple spaces

are not allowed.

The product name.

Product Data Fields



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



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.


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.


description

Any String A description of the option group.



An Object, where the

key is the option

name, and the value

is an option definition.


this group.



[optionId]

An Option definition. The set of options available for

this group.

optionID A String of at least

one character. Line

feeds, carriage



and multiple spaces

are not allowed.

The group name of the option.

Product Data Fields





[optionID].displayName

Any String Use this if the option value you

want to store differs from the

value you want displayed.



[optionID].description

Any String A description of the optionID

choice.



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



[optionId].rank

Any Integer An option rank that can be useful

when building UIs.



[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



weight.value A decimal number If we are using weight based



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


Cart Data Fields

These values can be defined for a cart:


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.


quantity

Int The quantity for this product.


price

String The price of the item in the cart, including additional

price of options selected.


product

String A URL that points to a product data REST resource.


itemOptions

Object A mapping of option names to selected values.


productLink

String A link to the product detail page for the product.

Documents

Welcome SHOPATRON INTEGRATION TOOLSET Add to Cart ...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