CafePress API Documentation

Click here for code release changelists

Quick Links

Getting Started

API Reference

Uploading images with PHP

Universal Parameters

The following parameters apply to all API requests.

v - Required. The only valid version is 3.

location - Optional. The desired target location of the API results. This mainly affects the currency used for priced. Valid values are: US, GB, AU, CA for USA (default), Great Britain, Canada, and Australia respectively.

addComments - Optional. Adds documentation comments to any XML returned. This is useful to see an explanation of and XML attribute or element. The value true turns comments on. By default the value is false, and no comments are displayed.

fieldTypes - Optional. Limits the XMLre data returned by the API calls. Valid values are:
required (shows only the required attributes and elements for saving the XML),
writable (shows all required and writable elements and attributes, meaning values that will be acknowledged upon saving the XML.)
all (default, shows all data)
readonly (shows all values that cannot be edited, meaning they will not be acknowledged upon saving the XML.)

Example XML Objects - The following are returned as results and posted when saving or updating

Product (With Documentation) 
Minimum Product Definition For Saving

Design (With Documentation) 
Minimum Design Definition For Saving

SVG 

Store (With Documentation) 
Minimum Store Definition For Saving

Section (With Documentation)
Minimum Section Definition For Saving


Introduction

The CafePress API allows for programmatic access and manipulation of CafePress products, designs, and stores. You may write scripts and applications for your own CafePress data as well as those of other users who permit you access to their data. Additionally the API provides search functionality to all products in the CafePress marketplace.

The CafePress API uses HTTP requests and XML to fetch and write data. An example of a request is http://open-api.cafepress.com/product.create.cp?v=3&merchandiseId=3, which returns an uninitialized product, where v=3 indicates the API version number to use and merchandiseId=3 means create a product based on a particular merchandise (e.g. a white t-shirt.)
From here on out we'll refer to product.create.cp as a method and v=3 and merchandiseId=3 as parameters of the method, but keep in mind that they are really just HTTP GET or POST requests. Here is the XML returned by the method:

<?xml version="1.0"?>
<product id="0" name="White T-Shirt" merchandiseId="3" sellPrice="13.99" description="The most comfortable t-shirt ever! Our 100% cotton, Hanes Authentic Tagless T-Shirt is preshrunk, durable and guaranteed. &amp;#xD;&amp;#xA;&amp;lt;ul&amp;gt;&amp;lt;li&amp;gt;6.1 oz. 100% cotton&amp;lt;/li&amp;gt;&amp;#xD;&amp;#xA;&amp;lt;li&amp;gt;Standard fit&amp;lt;/li&amp;gt;&amp;lt;/ul&amp;gt;" memberId="0" storeId="" sectionId="0" defaultOrientation="Normal" defaultPerspective="Front" basePrice="13.99" shortCaption="White T-Shirt" defaultCaption="White T-Shirt" shortDescription="White T" categoryId="0" stockAvailability="In Stock." stockAvailabilityStatusId="1" merchandiseAvailability="All Stores | Permanent Item" merchandiseAvailabilityStatusId="3" defaultProductUri="http://images.cafepress.com/jitcrunch.aspx?load=blank,blank:2_F.jpg|load=L1,http://images.cafepress.com/image/-2147483648_400x400.png||scale=L1,170,170,White|compose=blank,L1,Add,155,125|cp=result,blank|scale=result,0,240,White|compression=93|">
  <size id="4" name="Small" default="false" />
  <size id="5" name="Medium" default="false" />
  <size id="6" name="Large" default="true" />
  <size id="7" name="X-Large" default="false" />
  <size id="35" name="2X-Large" default="false" />
  <size id="9" name="3X-Large" default="false" />
  <size id="10" name="4X-Large" default="false" />
  <perspective name="Front" pixelWidth="480" pixelHeight="480" label="F" wildcardProductUri="http://images.cafepress.com/jitcrunch.aspx?load=blank,blank:2_F.jpg|load=L1,http://images.cafepress.com/image/-2147483648_400x400.png||scale=L1,170,170,White|compose=blank,L1,Add,155,125|cp=result,blank|scale=result,0,240,White|compression=93|">
  <showsMediaRegion>FrontCenter</showsMediaRegion>
    <showsMediaRegion>FrontPocket</showsMediaRegion>
  </perspective>
  <perspective name="Back" pixelWidth="480" pixelHeight="480" label="B" wildcardProductUri="http://images.cafepress.com/jitcrunch.aspx?load=blank,blank:2_B.jpg|load=L0,http://images.cafepress.com/image/-2147483648_400x400.png||scale=L0,170,170,White|compose=blank,L0,Add,155,100|cp=result,blank|scale=result,0,240,White|compression=93|">
    <showsMediaRegion>BackCenter</showsMediaRegion>
    <showsMediaRegion>BackShoulder</showsMediaRegion>
  </perspective>
  <mediaConfiguration dpi="100" height="10" width="10" name="BackCenter" designId="0" />
  <mediaConfiguration dpi="100" height="10" width="10" name="FrontCenter" designId="0" />
</product>





In order to do something useful with the XML data, you'll need to customize values and save it back to the CafePress API. Some of the XML data is for reference only, such as the available sizes, while other values can be modified to create a unique product. For example, you'll need to specify a designId on one of the mediaConfigurations to show one of your designs, and you may want to modify the description and sellPrice. You may also want to specify the ids of a store and store section in which to sell the product. Your modified XML only needs to specify the values to be modified, and any unique identifiers. Here's an example:

&lt;?xml version="1.0"?&gt;
<product name="A great shirt" merchandiseId="2" sellPrice="16.00" description="This is the shirt you've been waiting for." storeId="myVeryBestProducts" sectionId="8888888">
  <mediaConfiguration dpi="100" height="10" width="10" name="BackCenter" designId="9999999" />
</product>




Notice that most of the read-only XML has been removed. This is optional, since it's often easier to modify the XML without removing the read-only values. You must leave the attributes that function as identifiers, such as merchandiseId and the mediaConfiguration name, so that the CafePress API knows what you're trying to modify. Most identifiers are numeric, unless something can be uniquely identified by a name, such as stores and mediaConfigurations. When you're ready to save the product, you need to POST the modified XML to a save method, such as http://open-api.cafepress.com/product.save.cp?v=3&appKey=XXXXXXXXXX&userToken=XXXXXXXXX&value=the xml. The second two parameters of this method are for authentication. The appKey gives your application permission to use the CafePress API, and the userToken gives you access to certain data of a particular CafePress user's account. We'll look at authentication in more detail later. The value parameter is the XML that we listed above. You must do an HTTP POST instead of GET, either by using an AJAX POST request or an HTTP form submission (see the sections on XML and JSON below for more details.) Upon successfully POSTing, you'll receive a response similar to the following:

&lt;?xml version="1.0"?&gt;
<product id="9999999999" memberId="9999999" name="A greate shirt" merchandiseId="3" sellPrice="16.00" description="This is the shirt you've been waiting for." storeId="myVeryBestProducts" sectionId="8888888" defaultOrientation="Normal" defaultPerspective="Front" basePrice="13.99" shortCaption="Great White T" defaultCaption="White T-Shirt" shortDescription="White T" categoryId="0" stockAvailability="In Stock." stockAvailabilityStatusId="1" merchandiseAvailability="All Stores | Permanent Item" merchandiseAvailabilityStatusId="3" defaultProductUri="http://images.cafepress.com/jitcrunch.aspx?load=blank,blank:2_F.jpg|load=L1,http://images.cafepress.com/image/-2147483648_400x400.png||scale=L1,170,170,White|compose=blank,L1,Add,155,125|cp=result,blank|scale=result,0,240,White|compression=93|">
  <size id="4" name="Small" default="false" />
  <size id="5" name="Medium" default="false" /f>
  <size id="6" name="Large" default="true" />
  <size id="7" name="X-Large" default="false" />
  <size id="35" name="2X-Large" default="false" />
  <size id="9" name="3X-Large" default="false" />
  <size id="10" name="4X-Large" default="false" />
  <perspective name="Front" pixelWidth="480" pixelHeight="480" label="F" wildcardProductUri="http://images.cafepress.com/jitcrunch.aspx?load=blank,blank:2_F.jpg|load=L1,http://images.cafepress.com/image/-2147483648_400x400.png||scale=L1,170,170,White|compose=blank,L1,Add,155,125|cp=result,blank|scale=result,0,240,White|compression=93|">
  <showsMediaRegion>FrontCenter</showsMediaRegion>
    <showsMediaRegion>FrontPocket</showsMediaRegion>
  </perspective>
  <perspective name="Back" pixelWidth="480" pixelHeight="480" label="B" wildcardProductUri="http://images.cafepress.com/jitcrunch.aspx?load=blank,blank:2_B.jpg|load=L0,http://images.cafepress.com/image/-2147483648_400x400.png||scale=L0,170,170,White|compose=blank,L0,Add,155,100|cp=result,blank|scale=result,0,240,White|compression=93|">
    <showsMediaRegion>BackCenter</showsMediaRegion>
    <showsMediaRegion>BackShoulder</showsMediaRegion>
  </perspective>
  <mediaConfiguration dpi="100" height="10" width="10" name="BackCenter" designId="9999999" />
  <mediaConfiguration dpi="100" height="10" width="10" name="FrontCenter" designId="0" />
</product>





All of the values in your modified XML have been saved, and additionally a new id has been issued for the product. You can also see that the memberId has been set, based on the user authenticated by the userToken. You're free to modify this XML again and update the product, as long as you maintain the product id so that the CafePress API knows that you are modifiying and existing product, and not creating a new one.

If you ever need to know which XML values can be modified, you can request documentation for the XML by adding addComments=true to your method (e.g. http://open-api.cafepress.com/product.create.cp?merchandiseId=3&v=3&addComments=true.)

Authentication

Any CafePress API method that accesses a user's data requires authentication. The CafePress API follows a model similar to other public APIs, requiring an application key to give your application access to the CafePress API methods and a user token to allow your application to access and modify the data of a particular user.  There are two ways of getting a userToken: You can submit a user's account email address and password, or temporarily redirect to the CafePress login page. The former is simple, call http://open-api.cafepress.com/authentication.getUserToken.cp?v=3&appKey=XXXX&email=XXXX&password=XXXX. If you provide a valid email and password with your application key, you will receive a userToken in XML as follows:

&lt;?xml version="1.0"?&gt;
<value>017c0cf7-4135-4037-8e82-cc19f061849e</value>




This method is convenient if you already know the email and password (such as your own CafePress user account) or if your application's users trust giving you there account authentication. Alternatively, you may redirect users to cafepress.com for authentication. First request a loginToken: http://open-api.cafepress.com/authentication.getLoginToken.cp?appKey=XXXX. This will return the loginToken in XML as follows:

&lt;?xml version="1.0"?&gt;
<value>278efe1f-b651-490c-8dbf-e961889c9744</value>




Next, redirect to the cafepress.com login page, passing along the loginToken and a redirect parameter:

https://www.cafepress.com/cp/members/login.aspx?
    loginToken=278efe1f-b651-490c-8dbf-e961889c9744&goto=http://my_api_application.com

Upon successful login, cafepress.com will redirect back to your redir URL with an appended userToken (e.g. http://my_api_application.com?userToken=017c0cf7-4135-4037-8e82-cc19f061849e.) You may include parameters in your goto URL if you need to maintain some kind of state, such as a session id, but be sure to encode the special characters to be a URL parameter value, namely ? to %3F, &  to %26, and = to %3D.

XML and JSON

Although the CafePress API only sends and receives data object in XML format, it is possible to work primarily in JSON (Javascript Object Notation) using our JQuery plugin. The plugin converts CafePress API XML to simple javascript objects that you can read and manipulate and post back to the CafePress API. The easiest way to get started is to try out our test script at http://open-api.cafepress.com/test/. This script makes use of our JQuery plugin and demonstrates most of the methods of the API. We recommend that you install Javascript debugging tools such as Firebug for Firefox or Fiddler for IE that allow you to view the AJAX requests to the CafePress API.

Here's some boilerplate HTML to get you started with your own script using our JQuery plugin:

<html>
    <head>
        <script type="text/javascript" src="http://api.cafepress.com/test/lib/jquery/jquery.js"></script>
        <script type="text/javascript" src="http://api.cafepress.com/test/lib/jquery/jquery.ajaxmanager.js"></script>
        <script type="text/javascript" src="http://api.cafepress.com/test/lib/jquery/jqXMLUtils.js"></script>
        <script type="text/javascript" src="http://api.cafepress.com/test/lib/jquery/jqXMLUtilsToXML.js"></script>
        <script type="text/javascript" src="http://api.cafepress.com/test/lib/jquery/jquery.cpajax.js"></script>
        <script>
            $.getCpMethods(function onSuccess(ajax) {
               // globalize our ajax methods (e.g. cp.product.find(id))
               window["cp"] = ajax;
               cp.merchandise.getExample(function (json, xml) {
                   // access the defaultBlankProductUrl using the json result
                   $('#main').append($('<img></img>').attr('src', json.defaultBlankProductUrl));
                   // show the complete XML by using the xml result
                   alert($.xmlToString(xml));
               });
            });
        </script>
   </head>
   <body>
       <div id="main"></div>
   </body>
</html>




You can see that our JQuery plugin, jquery.cpajax.js, requires several other plugins, and JQuery itself.

Before this script will work from your own computer, you'll need to solve the problem of making a cross-domain AJAX calls to open-api.cafepress.com. To learn why cross-domain AJAX calls are restricted, and what to do about them see: http://developer.yahoo.com/javascript/howto-proxy.html and http://www.xml.com/pub/a/2005/11/09/fixing-ajax-xmlhttprequest-considered-harmful.html. There are various ways to solve the cross-domain problem. One fairly simple way is to run an Apache web server on the server hosting your script, and instruct it to redirect certain requests from browsers to your server to api.cafepress.com.  If you have permission to modify your Apache httpd.conf file , you can simply append the following lines and restart your server:

# Pass the call from http://www.yourserver.com/*.cp[?params] to http://api.cafepress.com
RewriteEngine on
RewriteRule ^/(.*\.(cp$|cp\?.*)) http://api.cafepress.com/$1 [P]


This redirect solves the cross-domain problem, since all AJAX requests by a web browser will call your server and not api.cafepress.com. If you are unable to run or configure Apache, find out how your web server can be configured to handler cross-domain AJAX requests, or consider the options listed in the links above.

Image Upload

Special Note: If you experience problems uploading, try using the appKey=77888c76-60ac-44f1-8e88-207bc5a81234

Uploading rastering images requires getting a user token and then calling an upload method with a multi-part form post. Begin with one of the methods described above under Authentication, such as http://open-api.cafepress.com/authentication.getUserToken.cp?v=3&appKey=XXXX&email=XXXX&password=XXXX.
Once you have a userToken you can call multi-part POST to:

http://upload.cafepress.com/image.upload.cp?appKey=XXXX&userToken=XXXX&folder=ImageFoldName&cpFile1=image_file1&cpFile2=image_file2.

folder is the name of any image folder for the user authenticated by the userToken. To use the base image folder specify: Images

cpFile1,cpFile2,...,cpFile5 are 1 to 5 raster image files to upload.

goto is an optional parameter specifying where to redirect upon a successful or unsuccessful post. The server will redirect to the URL you specify for the "goto" parameter value, appending a "value=imageId1,imageId2,.." parameter to your URL where the number of ids returned corresponds to the number of image you posted. If an error occurs the server will instead redirect to your "goto" parameter value adding "error=error_type" where error_type may be AuthenticationError for bad authentication, or one of the other errors listed in http://api.cafepress.com/error.list.cp?v=3.

You cannot actually specify cpFile1,cpFile2,...,cpFileN in the URL since you need to upload the binary data for each image.

Therefore you must use a mulit-part POST. On a web browser this is quite easy:

            <form id="upload" name="upload" method="POST" enctype="multipart/form-data" action="http://upload.cafepress.com/image.upload.cp" >          
                    <input type="file" id="cpFile1" name="cpFile1"></input>
                    <input type="file" id="cpFile2" name="cpFile2"></input>
                    <input type="hidden" id="appKey" name="appKey"></input>
                    <input type="hidden" id="userToken" name="userToken"></input>
                    <input type="hidden" id="folder" name="folder"></input>
                    <input type="hidden" id="goto" name="goto"></input>
                    <input type="submit" value="Upload"></center>
                </form>

Output:

If you do not specify the "goto" parameter, the server will return an XML document that lists the uploaded image ids or an error code. The successful XML will appear as follows:

<values>
  <value>id1</value>
  <value>id2</value>
  ...
</values>

and the error case:
 <error key="SomeErrorCode">
       <arguments/>
       <parameters>
            <parameter key="userToken" value=""/>            
            <parameter key="appKey" value=""/>                
        </parameters>
  </error>

If you do specify a goto paramter, the redirect URL will be http://YOUR_GOTO_PARAMETER_URL?your_optional_paramters?value=id1,id2,...,id5
and for the error case 
http://YOUR_GOTO_PARAMETER_URL?your_optional_paramters?error=SomeErrorCode

If it is insufficient to use an HTML form to upload, you may perform multi-part POST using most programming and scripting languages. Search the web for multipart post examples for you language. Here's an example in Perl: http://developer.cafepress.com/docs/Example_Serverside_File_Upload_Code

If you would like to test the upload functionality visit:

http://api.cafepress.com/test/upload.htm?appKey=77888c76-60ac-44f1-8e88-207bc5a81234&folder=Images&userToken=YOUR_USER_TOKEN

This form specifies a goto parameter that simply redirects to the same page upon submission. (You can get YOUR_USER_TOKEN using http://api.cafepress.com/authentication.getUserToken.cp)

Documentation

All CafePress API methods are documented by making the API call http://open-api.cafepress.com/documentation.list.cp?v=3&[resource=xxx&[action=xxx]. The optional resource parameter lets you narrow the list down to those methods belonging to a certain resource, such as product or design. The optional action parameter can further be used to limit documentation to methods of a certain name. Thus, to get documentation for product.create.cp call http://open-api.cafepress.com/documentation.list.cp?v=3&resource=product&action=create, as shown below. If you ever call a nonexistent method or use the wrong parameters the documentation will likewise be fetched to help you find the method and parameters for which you're looking.

&lt;?xml version="1.0"?&gt;
<documentation>
  <resource name="design" comments="Handles all actions concerning loading and saving of designs.">
    <action type="POST" name="save" comments="Creates or updates the given design with the given SVG XML specified outside of the design definition. If the design does not specify a parent folder, it is stored or moved to the base image folder. Existing designs must belong to the current user.">
      <parameter name="appKey" comments="The unique key identifying an API application. Required to authenticate a user." />
      <parameter name="userToken" comments="The unique key giving an API application permission to access the data of a certain user." />
      <parameter name="value" comments="A design definition, which may or may not include its SVG XML." />
      <parameter name="svg" comments="An SVG XML string" />
    </action>
    <action type="POST" name="save" comments="Creates or updates the given design with the given SVG XML specified outside of the design definition. The design is created in or moved to the given subfolder of the base image folder. Existing designs must belong to the current user.">
      <parameter name="appKey" comments="The unique key identifying an API application. Required to authenticate a user." />
      <parameter name="userToken" comments="The unique key giving an API application permission to access the data of a certain user." />
      <parameter name="value" comments="A design definition, which may or may not include its SVG XML." />
      <parameter name="svg" comments="An SVG XML string" />
      <parameter name="folderName" comments="The name of a sub folder in the user's image folder." />
    </action>
  </resource>
</documentation>




As previously mentioned, you can learn about the XML of methods that return complex XML by adding the addComments=true parameter. This will explain what each element and attribute of the XML means,  whether it can be modified or not, and whether or not it can be omitted when saving the XML.

1 Comment

  1. pengcognito3 years ago

    I get a 403 here: http://open-api.cafepress.com/test/.

    Is this still supposed to work? Is any of this stuff current?

Please sign in to post a comment.