API documentation

You can get an API key by logging to your Cotton Cart account, and going to http://www.cottoncart.com/account/apikeys/.

If you encounter any problems, or if you have any questions please email support@CottonCart.com.


General

Cotton Cart uses a RESTFul API based at https://www.cottoncart.com/api/. Each API call has a corresponding URL. Each API URL follows the pattern:

$versionID/$method_group/$method.$format

where:

  • $versionID is a short string identifying the API version (e.g. 'v1')
  • $method_group is a word identifying the function group (e.g. 'catalogue)
  • $method is the API call name within the funciton group (e.g. 'stores')
  • $format is the desired response format either "xml" or "json"

Sample URLs:

https://www.cottoncart.com/api/v1/catalogue/stores.xml
https://www.cottoncart.com/api/v1/catalogue/stores.json

Authenticated calls

Certain API calls require authentication, while others are anonymous. Authenticated API calls must include auth_id, auth_ts and auth_sig parameters, discussed below. API calls without auth_id are anonymous, and even if they contain auth_ts and auth_sig, these parameters are not processed or verified.

Each Cotton Cart user can create and delete multiple API Keys through the web interface. Each key has is a lowercase alphanumeric ID, appended with '@' to the store ID (e.g. 'user123@mystore'), and a shared secret value (16char, mixedcase alphanum). Authentication is performed based on the API Key and the corresponding shared secret.

To be authenticated, each call must include 3 parameters:

  • The authentication id (auth_id, e.g.'user123@mystore')
  • The timestamp (auth_ts) of the time the request was generated. This is an integer value representing an accurate Unix Time
  • The computed authentication signature (auth_sig)

To generate a valid request, the client needs to do the following:

  • Create the signature base string, consisting of the API version identifier, followed by a slash character, followed by the API method group, followed by a slash character, followed by the API method, followed by a question mark character, followed by all parameters of the request except the "auth_sig" parameter, sorted by key in lexical order and formatted as a query string, but without any percentescaping performed on the parameters and without file attachment names/values .
    • Note: The requested format is NOT included in the signature.
    • Example signature base string: v1/catalogue/store_info?auth_id=user123@mystore&auth_ts=1329130234&store_id=some_store
  • Generate a hexadecimal SHA256 HMAC of the base string hashed together with the API_KEY (see PHP docs on HMAC). Sha256 must be used as a hashing function.
  • Append that hex value to the list of arguments as auth_sig. The final request would look like:
    catalogue/store_info?store_id=some_store&auth_id=user123mystore&auth_ts=1329130234

The above scheme allows secure, stateless communication between the server and the client.


General response format

HTTP Codes

The Cotton Cart API always returns a response with 200 OK HTTP code. Any errors are included as a part of the response body, without affecting the HTTP headers.

Success state and errors

Every response contains a success key which can be either "true" or "false" (as string values). If success is false, the response will contain information about the error:

JSON output
XML output
{
	"success": false,
	"errorCode": 400,
	"error": "Required parameter missing",
	"errorDetails": {
		"param": "store_id"
	}
}
<response>
	<success>false</success>
	<errorCode>400</errorCode>
	<error>Required parameter missing</error>
	<errorDetails>
		<param>store_id</param>
	</errorDetails>
</response>

The errorDetails key is optional and its contents vary on a pererror basis; it is intended for human debugging, not for automatic processing.

Pagination

Some requests support paginated response, using the count and start request parameters. By default, all available records are listed. count can be used without start (in which case the first count records are listed); however, if start is provided, count is required.

If a request asks for paginated response, the response will contain a pagination structure:

JSON output
XML output
{
	"success": true,
	"pagination": {
		"start": 0,
		"count": 10,
		"total": 150
		"pages": 15,
		"prev_page": null,
		"next_page": 10
	}
}
<response>
	<success>true</success>
	<pagination>
		<start>0</start>
		<count>10</count>
		<total>150</total>
		<pages>15</pages>
		<prev_page />
		<next_page>1</next_page>
	</pagination>
</response>
  • start - Marks the starting point of the pagination.
  • count - The number of items per page.
  • total - The total number of records available for listing.
  • pages - The number of available pages.
  • prev_page - The starting index of the previous page.
  • next_page - The starting index of the next page.

The start and count keys mirror the values from the request. total holds the total number of records available for listing, pages holds the number of available pages of count items per page, while prev_page and next_page hold the starting index of the previous and the next page respectively (a value to be used for the start request parameter, in order to display previous/next page). prev_page and next_page would be null if further navigation in the respective direction is not available.


API methods

Catalogue calls

The Catalogue calls do not require authentication. The main purpose of these calls is to allow public access to the merchandise in the various Cotton Cart stores.

catalogue/stores

Returns a list of stores with their essential properties.

Sample JSON Output
{
	"stores": [
		{
			"website": "http://www.cottoncart.com", 
			"num_products": 8, 
			"store_id": "cottoncart", 
			"rss_feed_url": "", 
			"store_url": "http://cottoncart.cottoncart.com", 
			"description": "This is the Cotton Cart shop on CottonCart.com. Confusing, huh? Anyway, you can buy merch with our logo on it here, and currently we're selling some great designs by guest designer Ruth Lucas - check out her website at http://www.ruthlucas.co.uk", 
			"twitter_id": "cottoncart", 
			"logo_url": "http://www.cottoncart.com/var/devmedia/shops/shop315/shop_logo/CottonCart_Logo_for_t_shirt.jpg", 
			"facebook_url": "http://facebook.com/cottoncart", 
			"name": "Cotton Cart"
		}
	], 
	"success": true
}
Parameter Value Type Status Description
count Integer Optional

Pagination control - restricts the number of returned results. Can be used without start, in which case the first count elements are returned.

start Integer Optional

Pagination control - starts the current page from the element with number start. Requires count.

JSON
XML

Request URL

Response Body

Request URL

Response Body

catalogue/store_info

Returns the full information about the requested store.

Sample JSON Output
{
	"website": "http://www.cottoncart.com", 
	"num_products": 1, 
	"name": "Cotton Cart", 
	"success": true, 
	"store_url": "http://cottoncart.cottoncart.com", 
	"facebook_url": "http://facebook.com/cottoncart", 
	"twitter_id": "cottoncart", 
	"rss_feed_url": "", 
	"products": [
		{
			"design_image_url": "http://www.cottoncart.com/var/devmedia/shops/shop315/original_designs/1347353245_607168_design.jpg", 
			"product_id": 16863, 
			"shipping_details": {
				"to_country": "gb", 
				"first_item_cost": 1, 
				"each_extra_item_cost": 0.5
			}, 
			"type_id": "5", 
			"process": {
				"process_id": "flex", 
				"name": "Flexible colour"
			}, 
			"product_image_url": "http://www.cottoncart.com/var/devmedia/shops/shop315/original_designs/1347353245_607168product_option_57_59.png", 
			"symbol": "&pound;", 
			"symbol_position": "0", 
			"product_url": "http://www.cottoncart.com/products/16863", 
			"currency": "GBP", 
			"type": "Tote bags", 
			"price": 5.99, 
			"name": "Cotton Cart Guest Design - Ruth Lucas"
		}
	], 
	"logo_url": "http://www.cottoncart.com/var/devmedia/shops/shop315/shop_logo/CottonCart_Logo_for_t_shirt.jpg", 
	"description": "This is the Cotton Cart shop on CottonCart.com. Confusing, huh? Anyway, you can buy merch with our logo on it here, and currently we're selling some great designs by guest designer Ruth Lucas - check out her website at http://www.ruthlucas.co.uk"
}
Parameter Value Type Status Description
store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

country String Optional

2-char ISO country code for price currency and shipping fees. Default value: gb

count Integer Optional

Pagination control - restricts the number of returned results. Can be used without start, in which case the first count elements are returned.

start Integer Optional

Pagination control - starts the current page from the element with number start. Requires count.

JSON
XML

Request URL

Response Body

Request URL

Response Body

catalogue/product_info

Returns the full information about a product.

The secondary key for colour records is included only for flexible colour prints; full colourprints don't have a single print color, thus no secondary colour is returned.

Sample JSON Output
{
	"success": "true",
	"store_id": "mystore",
	"name": "Tweety Clouds",
	"type": "Women's t-shirt",
	"process": {
		"process_id": "flex",
		"name": "Flexible colour"
	},
	"product_url": "http://...",
	"product_image_url": "http://...",
	"design_image_url" : "http://...",
	"currency": "GBP",
	"price": 14.99,
	"shipping": {
		"to_country": "gb",
		"first_item_cost": 1.5,
		"each_extra_item_cost": 0.75
	},
	"sizes" : ["S", "M", "XXL", "..."],
	"colours": [
		{
			"colour_id": 800009,
			"description": "Black on White",
			"base": "White",
			"secondary": "Black",
			"image_url": "http://..."
		}
	]
}
Parameter Value Type Status Description
product_id Integer Required

Numeric ID of the requested product.

country String Optional

2-char ISO country code for price currency and shipping fees. Default value: gb

JSON
XML

Request URL

Response Body

Request URL

Response Body

Order calls

All calls under this section require authentication. These calls can be used to order merchandise.

order/calculate

Returns the calculated prices, shipping fees and totals for a given order.

The indexing of the item#_* parameters does not have to be sequential, but for each index all four parameters are required. Example request:

order/calculate.json?auth_id=userid@storeid&item1_product_id=16361&item1_colour_id=3400002&item1_size=L&item1_quantity=3&item7_product_id=16360&item7_colour_id=300002&item7_size=L&item7_quantity=5

Sample JSON Output
{
	"success": true,
	"shipping_country": "gb",
	"currency": "GBP",
	"total_items": 1,
	"items": [
		{
			"description": "Foobar (Hoodies, Neon Green on Black, L)",
			"product": "Foobar",
			"type": "Hoodies",
			"colour": "Neon Green on Black",
			"size": "L",
			"store_id": "apishop",
			"product_id": 16361,
			"type_id": 3,
			"colour_id": 3400002,
			"quantity": 1,
			"unit_price": 24.99,
			"subtotal": 24.99,
			"shipping": 3,
			"shipping_details": {
				"first_item_cost": 3,
				"extra_items_quantity": 0,
				"each_extra_item_cost": 2
			}
		}
	],
	"subtotal": 24.99,
	"shipping": 3,
	"total": 27.99
}
Parameter Value Type Status Description
item#_product_id Integer Required

Numeric ID of the ordered product. Replace '#' with the item index from your order list.

item#_colour_id Integer Required

Numeric ID of the item colour. Replace '#' with the item index from your order list.

item#_size String Required

Alphabtical identifier of the item size.  Replace '#' with the item index from your order list.

item#_quantity Integer Required

Number of ordered items from this type.  Replace '#' with the item index from your order list.

country String Optional

2-char ISO country code for price currency and shipping fees. Default value: gb

JSON
XML

Request URL

Response Body

Request URL

Response Body

order/checkout

Validate an order, optionally accepting it and returning an order ID along with the URL, at which the customer should proceed to complete the payment.

After a successful payment, the customer should be redirected to return_url with two parameters appended: order_id=... and state=successful. If the customer cancels the payment, they will be redirected to the return_url including the order_id, but with state=cancelled instead.

The indexing of the item#_* parameters does not have to be sequential, but for each index all four parameters are required.

Example request:

order/checkout.json?auth_id=userid@storeid&item1_product_id=16352&item1_colour_id=15000016&item1_size=L&item1_quantity=3&item7_product_id=16360&item7_colour_id=300002&item7_size=L&item7_quantity=5&name=Foo+O%27Bar&address_1=Ffordd+Penmynydd&city=Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch&region=Anglesey&postcode=LL61&checkout=1

Sample JSON Output
{
	"success": true,
	"status": "accepted",
	"order_id": 5761,
	"checkout_url": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-3L8566287F316770K",
	"currency": "GBP",
	"total": 183.17
}
Parameter Value Type Status Description
name String Required

Full person name.

email String Required

Valid e-mail address.

Notifications will go there

address_1 String Required

First line of shipping address.

address_2 String Optional

Second line of shipping address.

city String Required

The City the address is in.

region String Required

Region, state or province.

postcode String Required

Postal code.

country String Optional

2-char ISO country code for price currency and shipping fees. Default value: gb

item#_product_id Integer Required

Numeric ID of the ordered product. Replace '#' with the item index from your order list.

item#_colour_id Integer Required

Numeric ID of the item colour. Replace '#' with the item index from your order list.

item#_size String Required

Alphabtical identifier of the item size.  Replace '#' with the item index from your order list.

item#_quantity Integer Required

Number of ordered items from this type.  Replace '#' with the item index from your order list.

return_url String Required

URL where the customer will be redirected to after the payment succeeds or is cancelled.

mobile Integer Optional

Boolean flag: if 1 , the returned checkout URL will point to the mobile PayPal site. If the value is 0, then the regular PayPal site is used.

Default = 0

checkout Integer Optional

Boolean flag: if the value is 1, the order will be actually accepted; otherwise it is a test validation.

Default = 0

JSON
XML

Request URL

Response Body

Request URL

Response Body

Manage calls

All calls under this section require authentication. These calls are used to manage your stores, products and users.

manage/my_stores

Return all stores that can be managed by the API client. The user_id key will be included only for stores owned by sub-users.

API keys restricted to a single store will return only that single store. Unrestricted API keys that have access to manage sub-users will return all stores of the API key holder and all stores of sub-user accounts (see the user_id parameter for filtering by sub-user). Unrestricted API keys with no access to manage sub-users will only return the stores of the API key holder.


Sample JSON Output
{
	"success": true,
	"stores": [
		{
			"user_id": 1491,
			"store_id": "foobar",
			"name": "Foobar Store",
			"website": "http://...",
			"logo_url": null,
			"description": "Lorem ipsum dolor sit amet",
			"twitter_id": null,
			"facebook_url": "http://facebook.com/...",
			"rss_feed_url": "http://...",
			"num_products": 97
		}
	]
}
Parameter Value Type Status Description
user_id Integer Optional

Numeric ID of the DizzyJam user.

Include sub-user stores if omitted; exclude sub-user stores if = 0.

count Integer Optional

Pagination control - restricts the number of returned results. Can be used without start, in which case the first count elements are returned.

start Integer Optional

Pagination control - starts the current page from the element with number start. Requires count.

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/store_options

Return metadata needed to create shops.


Sample JSON Output
{
	"success": true
}

None

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/create_store

Create a new Cotton Cart store.

At least one of the website, myspace_url, facebook_url or twitter_id options is required.

Sample JSON Output
{
	"success": true,
	"store": {
		"store_id": "foobar",
		"name": "Foobar Store",
		"website": "http://...",
		"logo_url": null,
		"description": null,
		"twitter_id": null,
		"facebook_url": null,
		"rss_feed_url": null,
		"num_products": 0
	}
}
Parameter Value Type Status Description
user_id Integer Optional

Numeric ID of the Cotton Cart user.

If omitted, the API key holder will be owner.

store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

name String Optional

Full person name.

description String Optional

Public descritpion. 

logo_file Uploaded file Optional

File upload of a logo.

website String Optional

Website URL.

facebook_url Integer Optional

Facebook URL.

twitter_id String Optional

Twitter Username.

rss_feed_url String Required

RSS feed URL.

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/edit_store

Edit store defailts. Returns the details of the updated store.

At least one of the website, myspace_url, facebook_url or twitter_id fields must remain in the store record after the update, i.e. if a store has only a website, a request to clear it will trigger an error.

Valid values for the clear parameter are description, website, myspace_url, facebook_url, rss_feed_url, twitter_id, logo and genres; if any of the corresponding parameters is included in the request, it is not allowed in the clear list (e.g. you cannot provide a new value for the website parameter and simultaneously request that the it to be cleared in the shop record).

Sample JSON Output
{
	"success": true,
	"store": {
		"store_id": "foobar",
		"name": "Foobar Store",
		"website": "http://...",
		"logo_url": null,
		"description": "",
		"twitter_id": null,
		"facebook_url": "http://facebook.com/...",
		"rss_feed_url": "http://...",
		"num_products": 97
	}
}
Parameter Value Type Status Description
store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

name String Optional

Full person name.

description String Optional

Public descritpion. 

logo_file Uploaded file Optional

File upload of a logo.

website String Optional

Website URL.

facebook_url Integer Optional

Facebook URL.

twitter_id String Optional

Twitter Username.

rss_feed_url String Optional

RSS feed URL.

clear String Optional

Comma-separated list of fields to clear.

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/delete_store

Deletes a store. Returns the deletion status.

Sample JSON Output
{
	"success": true,
	"deleted": {
		"store_id": "foobar"
	}
}
Parameter Value Type Status Description
store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/product_options

Return metadata needed to create products.

The secondary key for colour records is included only for flexible colour prints; full colour prints don't have a single print color, thus no secondary colour is returned.

Sample JSON Output
{
	"success": true,
	"designs": [
		{
			"design_id": 381080,
			"name": "Tweety Clouds",
			"image_url": "http://..."
		}
	],
	"product_types": [
		{
			"type_id": 1,
			"name": "Women's t-shirt",
			"image_url": "http://...",
			"sizes": [ "S", "M", "L", "XL" ],
			"processes": [
				{
					"process_id": "flex",
					"name": "Flexible colour",
					"colours": [
						{
							"colour_id": 15000016,
							"description": "White on Black",
							"base": "Black",
							"secondary": "White",
							"image_url": "http://..."
						}
					]
				},
				{
					"process_id": "full",
					"name": "Full colour",
					"colours": [
						{
							"colour_id": 16000015,
							"description": "White",
							"base": "White",
							"image_url": "http://..."
						}
					]
				}
			]
		}
	]
}
Parameter Value Type Status Description
store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/create_product

Create one or more products.

Sample JSON Output
{
	"success": true,
	"products": [
		{
			"product_id": 16521,
			"name": "Tweety Clouds",
			"type": "Women's t-shirt",
			"process": {
				"process_id": "flex",
				"name": "Flexible colour"
			},
			"product_url": "http://...",
			"product_image_url": "http://...",
			"design_image_url": "http://...",
			"currency": "GBP",
			"price": 14.99,
			"shipping": {
				"to_country": "gb",
				"first_item_cost": 1.5,
				"each_extra_item_cost": 0.75
			},
			"colours": [
				{
					"colour_id": "1000009",
					"description": "Red on Black",
					"base": "Black",
					"secondary": "Red",
					"image_url": "http://..."
				}
			],
			"featured_colour": {
				"colour_id": "1200009",
				"description": "Blue on Black",
				"base": "Black",
				"secondary": "Blue",
				"image_url": "http://..."
			}
		}
	]
}
Parameter Value Type Status Description
store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

product_type_id Integer Optional

Numeric product type ID or all to create all product types. Valid product types are available via  manage/product_options.

process String Required

full or flex  to create a product for one specific print process, or all to  create products for all print processes. Valid print process identifiers for each product type are available via manage/product_options.

colours String Optional

Comma-separated list of colour codes, or all  to create all colour combinations. V alid colours for each print process for each product type are available via manage/product_options.

featured_colour Integer Optional

Colour code of the featured product.

design_id Integer Optional

Numeric design ID. Valid designs are available via manage/product_options.

design_file Uploaded file Optional

File upload of a new design image.

name String Required

Product name.

scale Integer Optional

Scale of the image. V alid values are integers 5..100; unit is percentage of the maximum available print size.

horiz Integer Optional

Horizontal position of the image. V alid values are integers -100..100; -100 = leftmost, 0 = center, +100 = rightmost.

vert Integer Optional

Vertical position of the image. Valid values are integers -100..100; -100 = highest, 0 = center, +100 = lowest.

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/edit_product

Edit a product. Returns the details of the new product.

Sample JSON Output
{
	"success": true,
	"product": {
		"product_id": 16531,
		"name": "Foobar",
		"type": "Men's t-shirt",
		"process": {
			"process_id": "flex",
			"name": "Flexible colour"
		},
		"product_url": "http://...",
		"product_image_url": "http://...",
		"design_image_url": "http://...",
		"currency": "GBP",
		"price": 14.99,
		"shipping_details": {
			"to_country": "gb",
			"first_item_cost": 1.5,
			"each_extra_item_cost": 0.75
		},
		"colours": [
			{
				"colour_id": "1000009",
				"description": "Red on Black",
				"base": "Black",
				"secondary": "Red",
				"image_url": "http://..."
			}
		],
		"featured_colour": {
			"colour_id": "1200009",
			"description": "Blue on Black",
			"base": "Black",
			"secondary": "Blue",
			"image_url": "http://..."
		}
	}
}
Parameter Value Type Status Description
product_id Integer Required

Numeric ID of the requested product.

colours String Optional

Comma-separated list of colour codes, or all  to create all colour combinations. V alid colours for each print process for each product type are available via manage/product_options.

featured_colour Integer Optional

Colour code of the featured product.

name String Optional

Full person name.

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/delete_product

Deletes a product from the store based on its ID. Returns the deletion status.

Sample JSON Output
{
	"success": true,
	"deleted": {
		"product_id": 16519
	}
}
Parameter Value Type Status Description
product_id Integer Required

Numeric ID of the requested product.

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/my_users

Return all sub-user accounts created with the API key holder as their reseller account.

API keys with no access to manage sub-users will return an error.

Sample JSON Output
{
	"success": true,
	"users": [
		{
			"user_id": 1491,
			"email": "foobar@example.com",
			"name": "Foo O'Bar",
			"num_stores": 3
		}
	]
}
Parameter Value Type Status Description
count Integer Optional

Pagination control - restricts the number of returned results. Can be used without start, in which case the first count elements are returned.

start Integer Optional

Pagination control - starts the current page from the element with number start. Requires count.

JSON
XML

Request URL

Response Body

Request URL

Response Body

manage/create_user

Create a new sub-user account and set the API key holder as its reseller account. API keys with no access to manage sub-users will return an error.

Sample JSON Output
{
	"success": true,
	"user": {
		"user_id": 4261,
		"email": "foobar@example.com",
		"name": "Foo O'Bar",
		"num_stores": 0,
		"password": "fkWSoOa8"
	}
}
Parameter Value Type Status Description
email String Required

Valid e-mail address.

Used for login.

password String Optional

Desired password with a minimal length of 8 characters.

If omitted, a random password will be generated and returned in the response.

name String Optional

Full person name.

JSON
XML

Request URL

Response Body

Request URL

Response Body

Stats calls

All calls under this section require authentication. These calls are used to retrieve statistics about your sales.

stats/sales

Return number of items sold during the specified period (default: last 30 days)

Sample JSON Output
{
	"success": true,
	"quantity": "15",
	"period": {
		"start": "2012-10-29",
		"end": "2012-11-28"
	}
}
Parameter Value Type Status Description
start_date Date Optional

Format: yyyy-mm-dd

Start date of the period (default: 30 days before end_date)

end_date Date Optional

Format: yyyy-mm-dd

End date of the period (default: today)

JSON
XML

Request URL

Response Body

Request URL

Response Body

stats/store_sales

Return number of items from the specified store sold during the specified period (default: last 30 days)

Sample JSON Output
{
	"success": true,
	"quantity": "7",
	"period": {
		"start": "2012-10-29",
		"end": "2012-11-28"
	}
}
Parameter Value Type Status Description
store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

Alphanumeric ID of the store

start_date Date Optional

Format: yyyy-mm-dd

Start date of the period (default: 30 days before end_date)

end_date Date Optional

Format: yyyy-mm-dd

End date of the period (default: today)

JSON
XML

Request URL

Response Body

Request URL

Response Body

stats/product_sales

Return number of items sold for a specified product during the specified period (default: last 30 days)

Sample JSON Output
{
	"success": true,
	"quantity": "3",
	"period": {
		"start": "2012-10-29",
		"end": "2012-11-28"
	}
}
Parameter Value Type Status Description
product_id Integer Required

Numeric ID of the requested product.

Numeric ID of the product

start_date Date Optional

Format: yyyy-mm-dd

Start date of the period (default: 30 days before end_date)

end_date Date Optional

Format: yyyy-mm-dd

End date of the period (default: today)

JSON
XML

Request URL

Response Body

Request URL

Response Body

stats/top_sellers

Return top selleing items (in quantity of items sold) from a shop for the specified period (default: last 90 days)

Sample JSON Output
{
	"success": true,
	"products": [
		{
			"product_id": "16342",
			"quantity": "3"
		}
	],
	"period": {
		"start": "2012-08-30",
		"end": "2012-11-28"
	}
}
Parameter Value Type Status Description
store_id String Required

Alphanumeric ID of the requested store. E.g. "mystore123".

Alphanumeric ID of the store

start_date Date Optional

Format: yyyy-mm-dd

Start date of the period (default: 90 days before end_date)

end_date Date Optional

Format: yyyy-mm-dd

End date of the period (default: today)

JSON
XML

Request URL

Response Body

Request URL

Response Body

stats/balance

Return account balance in each currency

Sample JSON Output
{
	"success": true,
	"GBP": {
		"currency": {
			"code": "GBP",
			"symbol": "£",
			"position": "0"
		},
		"earned": 123.64,
		"paid": 123.64,
		"unpaid": 0
	}
}

None

JSON
XML

Request URL

Response Body

Request URL

Response Body