Shopping Cart REST API Doc

Table of Contents
Overview
Required Parameters
Commands for interacting with the cart
Commands for Affiliate/Referral products
Commands for changing a cart's master settings
Returned Data and Status Messages

<< Back to Developer Lab Home

Overview
The REST API enables you to retrieve a specific shopping cart and display its contents in your app. If no cart is specified, a new empty cart is returned for use. By adding optional 'command' variables, items can be added, updated, or removed. The Shopping Cart REST service enables you to build a completely custom shopping cart system for any type of application rapidly without having to build any complex code or install any server side shopping cart software. Fully functional example code can be downloaded here.

This REST service accepts both GET and POST requests. Data can be returned in either XML or JSON depending on your needs.

Construct a URL as follows
https://api.payvment.com/rest/?[parameter name=value]

Example URL
https://api.payvment.com/rest/?apiKey=727272&cartID=39393&output=XML

Required Parameters (to be include in all API calls)

Param Name	Details	Values	Default	Required
apiKey	Your API Key is available from the Payvment dashboard.	String		Yes
cartID	Used to request your customers cart. See tutorial.	String		Yes
mode	This specifies what type of cartID is being used. "Web" = Cookie or Session "Facebook" = A Facebook UserID	Web Facebook	Web	No
command	This tells the cart what you would like to do such as add, update or remove and item. If no command is passed, the cart's contents will be returned without any modification.	addStoreItem updateStoreItem deleteStoreItem addAffiliateItem deleteAffiliateItem updateCartCurrency		No
currency	This sets a new cart to a default currency type of your choosing. If a consumer's cart already exists, the parameter is ignored. The consumer's default currency type can be changed using the 'updateCartCurrency' command.	AUD CAD CZK DKK EUR HKD HUF ILS JPY MXN NOK NZD PHP PLN GBP SGD SEK CHF TWD THB USD	USD	No
output	Format of the returned data.	String (XML or JSON)	XML	No
callback	If the output parameter is set as JSON this parameter is the name of a Javascript function you'd like to call with the return of the JSON object.			No

Commands for interacting with the shopping cart

"addStoreItem"
This command is used to add a new item to the cart. Parameters need to be URL Encoded.

Param Name	Details	Values	Default	Required
payvmentID	This variable is your Payvment ID. You can get your Payvment ID from the dashboard.	Int		Yes
itemID	This variable is your product's ID for your own reference. Example: tshirt001	String		Yes
itemName	This variable is the name of the item. Example: Polo Shirt	String		Yes
itemCurrency	This variable is the currency of your item's pricing and shipping.	AUD CAD CZK DKK EUR HKD HUF ILS JPY MXN NOK NZD PHP PLN GBP SGD SEK CHF TWD THB USD	USD	No
itemPrice	This variable should contain the sale price of the item. Example: 16.99	Decimal		Yes
itemQty	This variable is the quantity of the item.	Int	1	No
itemShipping	This variable should contain the amount you would like to add for shipping & handling. Example: 1.50	Decimal	0.00	No
itemShipping2	This variable should contain the amount you would like to add for shipping & handling when additional quantity is added. If this variable is not added, shipping will be charged at a flat rate set with 'itemShipping'. Example: 1.25	Decimal	0.00	No
itemNoShip	This variable can be used if your item does not require shipping such as a music download or donation. The variable will disable Quantity for the item and if all items in a cart have a 'noShip' setting, checkout will not require a shipping address. Use like this: itemNoShip=1	Int	0	No
itemUrl	This is the URL of the web page where this item was added to the cart. It is important to use the exact URL since it will be available from the Checkout if a customer needs to return to the item's web page.	URL		No
itemOption1	This optional variable is used to specify a product's option. Example: Black	String		No
itemOption2	This optional variable is used to specify a product's option. Example: X-Large	String		No
itemOption3	This optional variable is used to specify a product's option.	String		No
itemOption4	This optional variable is used to specify a product's option.	String		No

"updateStoreItem"
This command is used to update the quantity of an item in the cart. Parameters need to be URL Encoded.

Param Name	Details	Values	Default	Required
itemID	This is the Product ID of the item you would like to update	String		Yes
itemQty	This is the new updated quantity	Int		Yes
retailerID	The RetailerID of the item.	Int		Yes
itemOption1	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to update based on the product option	String		No
itemOption2	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to update based on the product option	String		No
itemOption3	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to update based on the product option	String		No
itemOption4	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to update based on the product option	String		No

"deleteStoreItem"
This command is used to delete an item from the cart. Parameters need to be URL Encoded.

Param Name	Details	Values	Default	Required
itemID	This is the Product ID of the item you would like to delete	String		Yes
retailerID	The RetailerID of the item.	Int		Yes
itemOption1	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to delete based on the product option	String		No
itemOption2	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to delete based on the product option	String		No
itemOption3	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to delete based on the product option	String		No
itemOption4	This variable can be passed when multiple items with the same 'itemID' are in the cart - This helps specify which one to delete based on the product option	String		No

Commands for Affiliate/Referral products

"addAffiliateItem"
This command is used to add an Affiliate/Referral link to the cart. Parameters need to be URL Encoded.

Param Name	Details	Values	Default	Required
payvmentID	This variable is your Payvment ID. You can get your Payvment ID from the dashboard.	Int		Yes
itemName	This variable is the name of the item that will appear in the cart.	String		Yes
itemRetailer	This variable is the name of the retailer the Affiliate/Referral link belongs to.	String		Yes
itemURL	This variable is the Affiliate/Referral link URL	URL		Yes
itemUrlType	This variable specifies if the URL adds the item to the retailer's cart or if the URL is a referral link to the retailer's product page. 1=Add to Cart URL 2=Product Page URL	Int		Yes

"deleteAffiliateItem"
This command is used to remove an Affiliate/Referral link from the cart. Parameters need to be URL Encoded.

Param Name	Details	Values	Default	Required
itemID	This variable is the ID of the item to be removed from the cart.	Int		Yes

Commands for changing a cart's master settings

"updateCartCurrency"
This command is used to change a cart's default currency type so your customer can view their cart in the currency of their choosing.

Param Name	Details	Values	Required
cartCurrency	This is the currency type that the cart should display in. This command lets the consumer change and view their cart in any supported currency they choose. When a new currency is chosen for a cart, all item prices in the cart automatically update using the latest foreign exchange rates. Currency conversion is also ran when new items are added. Items in the cart are recalculated every 4 hours in order to be current with latest exchange rates. A final exchange rate calculation is made upon checkout for safety.	AUD CAD CZK DKK EUR HKD HUF ILS JPY MXN NOK NZD PHP PLN GBP SGD SEK CHF TWD THB USD	Yes

Returned Data and Status Messages

Successful XML Output Example

Payload value descriptions

Node	Definition
status
StatusCode	Displays status/error code (see status codes & messages)
StatusMessage	Displays status/error message (see status codes & messages)
Command	Displays the command sent with the REST call if any. Commands are used to modify the cart such as adding and removing items.
results
CartID	The ID identifying the cart. This needs to be stored in a cookie to retrieve a user's specific cart using "cartID=" in your REST calls. See tutorial.
CartCurrency	The currency the cart is being displayed in (change via updateCartCurrency command).
CurrencyConversion	Displays how many items required currency conversion to the latest foreign exchange rate when the REST call was made. If currency conversions was not needed, returns "False". Currency Conversions are made when an item currency differs from the cart's selected currency view.
AllItemsCount	Total number of items in the cart (Store items + Affiliate items)
StoreItemsCount	Total 'Store' items in cart
AffiliateItemsCount	Total 'Affiliate' items in cart
SubTotal	Subtotal amount
ShippingTotal	Total shipping amount
GrandTotal	Grand Total amount
CheckoutURL	URL to launch checkout
items->storeitems->item
ItemID	Product's ID
ItemName	Product's name
ItemQty	Quantity of the item in cart
ItemPrice	Price of the item
ItemQtyPrice	Total item price with quantity (ItemPrice x ItemQty)
ItemShipping	Item's shipping cost
ItemQtyShipping	Total item shipping cost with quantity (ItemShipping x ItemQty)
ItemOption1	An option chosen by the purchaser
ItemOption2	An option chosen by the purchaser
ItemOption3	An option chosen by the purchaser
ItemOption4	An option chosen by the purchaser
ItemURL	Location the item was added to cart
ItemNoShip	If no shipping is set for the item - Returns "1"
RetailerID	The product's retailer ID
RetailerName	The name of the product's retailer
RetailerSupportEmail	The retailer's support contact email
ItemTimestamp	The date/time the item was added to the cart
items->affiliateitems->item
ItemID	The item's ID
ItemName	The name of the item
ItemRetailer	The retailer the product belongs to
ItemLink	The Affiliate/Referral URL
ItemLinkType	Specifies if the URL adds the item to the retailer's cart or if the URL is a referral link to the retailer's product page. 1=Add to Cart URL 2=Product Page URL
ItemTimestamp	The date/time the item was added to the cart

Status Codes & Messages

Status Code	Status Message
200	OK
304	Error: {Reason for error}
401	Invalid API Key
403	You have exceeded your REST request limit