API documentation

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

If you encounter any problems, or if you have any questions please email [email protected].


General

Dizzyjam uses a RESTFul API based at https://dizzyjam.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://dizzyjam.com/api/v1/catalogue/stores.xml
https://dizzyjam.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 Dizzyjam 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 Dizzyjam 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 Dizzyjam stores.

 

catalogue/stores

Returns a list of stores with their essential properties.

Sample JSON Output
{
  "stores": [
    {
      "website": "http://www.dizzyjam.com", 
      "genres": [
        "Rock", 
        "Dance", 
        "Electronica"
      ], 
      "num_products": 8, 
      "store_id": "dizzyjam", 
      "rss_feed_url": "", 
      "store_url": "http://dizzyjam.dizzyjam.com", 
      "description": "This is the Dizzyjam shop on Dizzyjam.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": "dizzyjam", 
      "myspace_url": "", 
      "logo_url": "http://www.dizzyjam.com/var/devmedia/shops/shop315/shop_logo/Dizzyjam Logo for t shirt.jpg", 
      "facebook_url": "http://facebook.com/dizzyjam", 
      "name": "Dizzyjam"
    }
  ], 
  "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.dizzyjam.com", 
  "genres": [
    "Rock", 
    "Dance", 
    "Electronica"
  ], 
  "num_products": 1, 
  "name": "Dizzyjam", 
  "success": true, 
  "store_url": "http://dizzyjam.dizzyjam.com", 
  "facebook_url": "http://facebook.com/dizzyjam", 
  "twitter_id": "dizzyjam", 
  "rss_feed_url": "", 
  "embed_shop_code": "<script type=\"text/javascript\" src=\"//www.dizzyjam.com/embed/js/foobar.js\"></script>",
  "embed_settings": {
    "show_logo": "yes",
    "show_products_filter": "yes",
    "show_shop_title": "yes",
    "shop_border_width": "1",
    "shop_border_colour": "#ffffff",
    "background_colour": "#ffffff",
    "product_background_colour": "#f2f2f2",
    "border_colour": "#b7b7b7",
    "buttons_colour": "#2d91cf",
    "font_family": "'Courier New', Courier, monospace",
    "text_colour": "#313131",
    "secondary_text_colour": "#858585",
    "link_colour": "#2d91d1",
    "link_hover_colour": "#ffffff"
  },
  "products": [
    {
      "design_image_url": "http://www.dizzyjam.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.dizzyjam.com/var/devmedia/shops/shop315/original_designs/1347353245_607168product_option_57_59.png", 
      "symbol": "&pound;", 
      "symbol_position": "0", 
      "product_url": "http://www.dizzyjam.com/products/16863", 
      "currency": "GBP", 
      "type": "Tote bags", 
      "price": 5.99, 
      "name": "Dizzyjam Guest Design - Ruth Lucas"
    }
  ], 
  "logo_url": "http://www.dizzyjam.com/var/devmedia/shops/shop315/shop_logo/Dizzyjam Logo for t shirt.jpg", 
  "myspace_url": "", 
  "description": "This is the Dizzyjam shop on Dizzyjam.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

embed_settings String Optional

Show embed store settings. Valid values are "yes" and "no". Default value: no

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 colour, 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.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

payment_processor String Optional

Payment processor which will be used to complete the payment. Valid values are "paypal" and "stripe".

Default value: paypal

stripe_method String Optional

A single use method that wraps the details of a credit card when the payment processor is set to "stripe".

Businesses in Europe should use Elements with the Payment Intents API instead of the Charges API to support SCA. Follow Using Payment Intents on Web to get started.

stripe_token String Optional

A single use token that wraps the details of a credit card when the payment processor is set to "stripe". The tokens are allowed for purchases outside the Europe.

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

 

Stripe payments integration:

To use Stripe payments you have to set the payment_processor parameter value to stripe in order/checkout method. Also you have to provide a valid stripe_token parameter value.

Please read the detailed tutorial how to building a custom payment form and provide a valid stripe_token here: https://stripe.com/docs/tutorials/forms

Remember to replace the test key with our live key: pk_live_YfYVyvV2qgtSi2nT5kLSAQP3

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.

 

 

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",
      "genres": [
        "Rock",
        "Hip Hop",
        "Indie",
        "Pop"
      ],
      "website": "http://...",
      "logo_url": null,
      "description": "Lorem ipsum dolor sit amet",
      "twitter_id": null,
      "facebook_url": "http://facebook.com/...",
      "myspace_url": "http://myspace.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,
  "genres": [
    {
      "genre_id": 1,
      "name": "Rock"
    }
  ]
}
 

None

JSON
XML
 

Request URL

Response Body

Request URL

Response Body

manage/create_store

Create a new Dizzyjam 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",
    "genres": [],
    "website": "http://...",
    "logo_url": null,
    "embed_shop_code": null,
    "description": null,
    "twitter_id": null,
    "facebook_url": null,
    "myspace_url": null,
    "rss_feed_url": null,
    "num_products": 0
  }
}
 
Parameter Value Type Status Description
user_id Integer Optional

Numeric ID of the Dizzyjam 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.

embed_shop String Optional

Create default embed shop settings. Valid values are "yes" and "no".

Default value: no

genres String Optional

Comma-separated list of genre IDs.

Valid genre IDs are available via manage/store_options.

website String Optional

Website URL.

myspace_url String Optional

MySpace 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",
    "genres": [
      "Rock",
      "Hip Hop",
      "Indie",
      "Pop"
    ],
    "website": "http://...",
    "logo_url": null,
    "embed_shop_code": null,
    "description": "",
    "twitter_id": null,
    "facebook_url": "http://facebook.com/...",
    "myspace_url": "http://myspace.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.

embed_shop String Optional

Create default embed shop settings. Valid values are "yes" and "no".

Default value: no

genres String Optional

Comma-separated list of genre IDs.

Valid genre IDs are available via manage/store_options.

website String Optional

Website URL.

myspace_url String Optional

MySpace 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/edit_embed_store

Edit embed store settings. Returns the details of the store and updated embed store settings.

All colours should be in hex format. For example: #f2f2f2, #313131, #2d91cf, etc.

Sample JSON Output
{
  "success": true,
  "store": {
    "store_id": "foobar",
    "name": "Foobar Store",
    "genres": [
      "Rock",
      "Hip Hop",
      "Indie",
      "Pop"
    ],
    "website": "http://...",
    "logo_url": null, 
    "embed_shop_code": "<script type=\"text/javascript\" src=\"//www.dizzyjam.com/embed/js/foobar.js\"></script>",
    "embed_settings": {
      "show_logo": "yes",
      "show_products_filter": "yes",
      "show_shop_title": "yes",
      "shop_border_width": "1",
      "shop_border_colour": "#ffffff",
      "background_colour": "#ffffff",
      "product_background_colour": "#f2f2f2",
      "border_colour": "#b7b7b7",
      "buttons_colour": "#2d91cf",
      "font_family": "'Courier New', Courier, monospace",
      "text_colour": "#313131",
      "secondary_text_colour": "#858585",
      "link_colour": "#2d91d1",
      "link_hover_colour": "#ffffff"
    },
    "description": "",
    "twitter_id": null,
    "facebook_url": "http://facebook.com/...",
    "myspace_url": "http://myspace.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".

show_logo String Required

Show shop logo.
Valid values are "yes" and "no".

show_products_filter String Required

Show products filter.
Valid values are "yes" and "no".

show_shop_title String Required

Show shop title.
Valid values are "yes" and "no".

shop_border_width Integer Required

Shop border width.

shop_border_colour String Required

Shop border colour.

background_colour String Required

Background colour.

product_background_colour String Required

Elements background colour.

border_colour String Required

Borders colour.

buttons_colour String Required

Buttons and accents colour.

font_family String Required

Font family which will be used.
Valid values are: "Arial, Verdana, sans-serif", "'Courier New', Courier, monospace", "Georgia, Courier, monospace", "Tahoma, Arial, sans-serif", "Verdana, Arial, sans-serif"

text_colour String Required

Text colour.

secondary_text_colour String Required

Elements text colour.

link_colour String Required

Links colour.

link_hover_colour String Required

Links hover text colour.

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 colour, 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/upload_design

Upload a new product design to the store based on its ID.

The values returned from the print array are needed for the correct display and calculation (maximum height and width) of the full-colour designs.

The design array returns information about the design file itself - its ID, the source image (design_image_url), image URLs for flex and full-colour printing (design_image_url_flex и design_image_url_full), the file extension and the file size.

Sample JSON Output
{
  "success": true,
  "print": {
    "inchw": 5.12,
    "inchh": 5.12
  },
  "design": {
    "design_id": "1285215",
    "design_image_url": "http://...",
    "design_image_url_flex": "http://...",
    "design_image_url_full": "http://... ",
    "extension": "png",
    "filesize": "348478"
  }
}
 
Parameter Value Type Status Description
store_id String Required

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

design_file Uploaded file Required

File upload of a new design image.

JSON
XML
 

Request URL

Response Body

Request URL

Response Body

manage/delete_design

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

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

Numeric ID of the requested product design.

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",
        "image_url_flex": "http://... ",
        "image_url_full": "http://... ",
        "inchw": "6.68",
        "inchh": "10.23"
      },
      "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. Valid 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

Full person name.

scale Integer Optional

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

horiz Integer Optional

Horizontal position of the image. Valid 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.

angle Integer Optional

Angle of the design within the available print area (optional: default: 0 (= normal); min: -180, max: 180)

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. Valid 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": "[email protected]",
      "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": "[email protected]",
    "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