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 [email protected].
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
}
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": "£",
"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"
}
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://..."
}
]
}
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
}
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®ion=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
}
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
}
]
}
manage/store_options
Return metadata needed to create shops.
- Sample JSON Output
{
"success": true
}
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
}
}
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
}
}
manage/delete_store
Deletes a store. Returns the deletion status.
- Sample JSON Output
{
"success": true,
"deleted": {
"store_id": "foobar"
}
}
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://..."
}
]
}
]
}
]
}
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://..."
}
}
]
}
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://..."
}
}
}
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
}
}
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": "[email protected]",
"name": "Foo O'Bar",
"num_stores": 3
}
]
}
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": "[email protected]",
"name": "Foo O'Bar",
"num_stores": 0,
"password": "fkWSoOa8"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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
}
}