Fetch API Documentation

The Fetch API is implemented as RESTful (using all four verbs GET/POST/PUT/DELETE) XML over HTTP. Every resource, like Orders and Items, has its own URL and is manipulated in isolation. The API is also usable by non-RESTful platforms as well using GET and POST only by adding on the appropriate command to the URI (see below).

Authentication

All requests require basic authentication. To make a proper request, you must set the authorization header of your request and supply the generated string. The string is your personal key and token with a colon ("demokey:demotoken") converted to a base-64 string. For example, "demokey:demotoken".to_base64 is ZGVtb2tleTpkZW1vdG9rZW4=

Then, place the string into the authorization header of your HTTP requests:

GET /api/orders HTTP/1.1
Host: demo.fetchapp.com
Authorization: Basic ZGVtb2tleTpkZW1vdG9rZW4=

Content-Type: application/xml

Alternatively you may send your key and token inline with the request URL.

http://demokey:demotoken@demo.fetchapp.com/api/orders

All URI's are also accessible via your browser by appending .xml to the request:

http://demokey:demotoken@demo.fetchapp.com/api/orders.xml

Account

GET information about your account:

/api/account
/api/account.xml

Example result:

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <id>4334</id>
  <name>Warner Brothers</name>
  <email>bugs@bunny.com</email>
  <billing_email>daffy@duck.com</billing_email>
  <shopify_address>wb.myshopify.com</shopify_address>
  <url>warner.fetchapp.com</url>
  <paypal_address></paypal_address>
  <order_expiration_in_hours>240</order_expiration_in_hours>
  <download_limit_per_item>3</download_limit_per_item>
  <api_key>bugs</api_key>
  <api_token>carrots</api_token>
</account>

GET a new API token (this replaces your existing one):

/api/new_token
/api/new_token.xml

Example result:

<?xml version="1.0" encoding="UTF-8"?> 
<message>abcdef6fdas</message>

Downloads

GET a list of your downloads:

/api/downloads
/api/downloads.xml
/api/downloads.xml?per_page=25&page=2

Example result:

<?xml version="1.0" encoding="UTF-8"?>
<downloads type="array">
  <download>
	  <id>433</id>
	  <filename>myfile.txt</filename>
	  <item_sku>BILL-WAX</item_sku>
	  <order_id>1002</order_id>
	  <ip_address>127.0.0.1</ip_address>
	  <downloaded_at type="datetime">2009-04-23T14:03:27-04:00</downloaded_at>
	  <size_bytes type="float">314559</size>
  </download>
  <download>  (lack of order_id indicates that this download was from a permalink)
	  <id>434</id>
	  <filename>myfile.txt</filename>
	  <item_sku>BILL-WAX</item_sku>
	  <ip_address>127.0.0.1</ip_address>
	  <downloaded_at type="datetime">2009-04-23T14:03:16-04:00</downloaded_at>
	  <size_bytes type="float">314559</size>
  </download>
</downloads>

Items

List all your items:

/api/items
/api/items.xml
/api/items.xml?per_page=25&page=2

<?xml version="1.0" encoding="UTF-8"?>
<items type="array">
	<item>
	...        
	</item>
	<item>
	...        
	</item>
</items>

List details of a specified item:

/api/items/:sku
/api/items/:sku.xml
<?xml version="1.0" encoding="UTF-8"?>
<item>
  <sku>BILL-WAX</sku>
  <name>Quality Bill Wax</name>
  <order_count type="integer">4</order_count>
  <download_count type="integer">5</download_count>
  <guid>yuurud</guid>
  <permalink>/permalink/yuurud</permalink>
  <created_at type="datetime">2008-11-10T22:54:32+00:00</created_at>
  <filename>BILL-WAX.zip</filename>
  <size_bytes type="integer">98129942</size_bytes>
  <content_type>application/zip</content_type>
  <downloads type="array">
	<download>                       
	  <id>233</id>
	  <item_sku>BILL-WAX</item_sku>
	  <ip_address>127.0.0.1</ip_address>
	  <downloaded_at type="datetime">2009-04-27T04:13:09+00:00</downloaded_at>
	  <size_bytes type="float">87088</downloaded_at>
	</download>
	<download>
	  <id>433</id>
	  <order_id>1002</order_id>
	  <item_sku>BILL-WAX</item_sku>
	  <ip_address>127.0.0.1</ip_address>
	  <downloaded_at type="datetime">2009-04-28T10:33:09+00:00</downloaded_at>
	  <size_bytes type="float">332088</downloaded_at>
	</download>
  </downloads>
</item>

Delete a specified item:

/api/items/:sku/delete
/api/items/:sku/delete.xml

This will also remove the item from any existing orders.

POST to create a specified item:

/api/items/create
/api/items/create.xml
<?xml version="1.0" encoding="UTF-8"?>
<item>
	<sku>1</sku>
	<name>Carrot Juice</name>
</item>

PUT to update a specified item:

/api/items/:sku/items
/api/items/:sku/items.xml
<?xml version="1.0" encoding="UTF-8"?>
<item>
	<sku>2</sku>
	<name>Tomato Juice</name>
</item>

The item's SKU can be changed if necessary.

GET to list all the downloads for an item:

/api/items/:sku/downloads
/api/items/:sku/downloads.xml
<downloads type="array">
	<download>                       
	  <id>233</id>             
	  <item_sku>BILL-WAX</item_sku>
	  <order_id>1001</order_id>
	  <ip_address>127.0.0.1</ip_address>
	  <downloaded_at type="datetime">2009-04-27T04:13:09+00:00</downloaded_at>
	  <size_bytes type="float">87088</downloaded_at>
	</download>
	<download>
	  <id>433</id>
	  <item_sku>BILL-WAX</item_sku>
	  <ip_address>127.0.0.1</ip_address>
	  <downloaded_at type="datetime">2009-04-28T10:33:09+00:00</downloaded_at>
	  <size_bytes type="float">332088</downloaded_at>
	</download>
  </downloads>

No order_id indicates a direct download of the item via the permalink.

Orders

GET a list of all your orders:

/api/orders
/api/orders.xml
/api/orders.xml?filter=<type>&per_page=25&page=2

*Type can be current, manual, or expired


<?xml version="1.0" encoding="UTF-8"?>
<orders type="array">
	<order>
	...
	</order>
</orders>
<orders>
	<order> 
	...
	</order>
</orders>

GET details of a specified order:

/api/orders/:id
/api/orders/:id.xml

Example result:


<?xml version="1.0" encoding="UTF-8"?>
<order>
  <id>1001</id>
  <title>Order #1001</title>
  <first_name>Donald</first_name>
  <last_name>Duck</last_name>
  <email>donald@duck.com</email>
  <item_count type="integer">1</item_count>
  <download_count type="integer">1</download_count>
  <expiration_date type="datetime">2008-12-28T18:47:56+00:00</expiration_date>
  <download_limit type="integer">3</download_limit>
  <created_at type="datetime">2008-11-28T18:47:56+00:00</created_at>
  <order_items>
	<order_item>
	  <sku>BILL-WAX</sku>
	  <item_name>Quality Bill Wax</item_name>
	  <order_id>1001</order_id>
	  <guid>tydjdje</guid>
	  <download_count type="integer">1</download_count>
	  <link>/get/tydjdje</link>
	  <downloads_remaining type="integer"></downloads_remaining>
	  <created_at type="datetime">2008-11-28T18:47:56+00:00</created_at>
	  <downloads type="array">
		<download>
		  <order_id>1001</order_id>
		  <ip_address>127.0.0.1</ip_address>
		  <downloaded_at type="datetime">2009-04-27T04:13:09+00:00</downloaded_at>
		  <size type="float">37088</downloaded_at>
		</download>
		<download>
		  <order_id>1001</order_id>
		  <ip_address>127.0.0.1</ip_address>
		  <downloaded_at type="datetime">2009-04-28T10:33:09+00:00</downloaded_at>
		  <size type="float">877088</downloaded_at>
		</download>
	  </downloads>
	</order_item>  
  </order_items>
</order>

DELETE a specified order:

/api/orders/:id/delete 
/api/orders/:id/delete.xml

POST to expire a specified order:

/api/orders/:id/expire
/api/orders/:id/expire.xml

POST to send download email of a specified order:

/api/orders/:id/send_email
/api/orders/:id/send_email.xml

NOTE: reset_expiration is optional, and defaults to true if not present. If "true", the expiration date will be set to whatever is selected in Settings → General. expiration_date is optional, and if present, overrides the "reset_expiration" option.

POST to create an order:

/api/orders/create
/api/orders/create.xml

NOTE: send_email is optional, and defaults to "true" if not present. expiration_date is optional, and the default is the setting in Settings → General if not present. download_limit is optional, and the default is the setting in Settings → General if not present. downloads_remaining is optional and serves as an override. If not present, the default is whatever the order's download_limit is set to.

<?xml version="1.0" encoding="UTF-8"?>
<order>
	<send_email>true</send_email>
	<id>1</id>
	<title>Order for Bugs</title>
	<first_name>Bugs</first_name>
	<last_name>Bunny</last_name>
	<email>bugs@bunny.com</email>
	<expiration_date type="datetime">2010-07-24T01:47:30+00:00</expiration_date>
	<download_limit type="integer">5</download_limit>
	<order_items type="array">
		<order_item>
			<sku>1</sku>
			<downloads_remaining type="integer">4</downloads_remaining>
		</order_item>
	</order_items>
</order>

PUT to update a specified order:

/api/orders/:id/update
/api/orders/:id/update.xml

NOTE: send_email is optional, and defaults to "false" if not present. All fields can be changed including the order ID.

<?xml version="1.0" encoding="UTF-8"?>
<order>
	<send_email>false</send_email>
	<id>1</id>
	<title>Order for Bugs</title>
	<first_name>Bugs</first_name>
	<last_name>Bunny</last_name>
	<email>bugs@bunny.com</email>
	<expiration_date type="datetime">2010-07-24T01:47:30+00:00</expiration_date>
	<download_limit type="integer">5</download_limit>
	<order_items type="array">
		<order_item>
			<sku>1</sku>
			<downloads_remaining type="integer">4</downloads_remaining>
		</order_item>
	</order_items>
</order>

Uploads

GET a list of your uploads:

/api/uploads
/api/uploads.xml
/api/uploads.xml?per_page=25&page=2

Example result:

<?xml version="1.0" encoding="UTF-8"?>
<uploads type="array">
  <upload>
	  <id>433</id>
	  <filename>myfile.txt</filename>
	  <ip_address>127.0.0.1</ip_address>
	  <uploaded_at type="datetime">2009-04-23T14:03:27-04:00</uploaded_at>
	  <size_bytes type="float">314559</size>
  </upload>
  <upload>
	  <id>434</id>
	  <filename>myotherfile.txt</filename>
	  <ip_address>127.0.0.1</ip_address>
	  <uploaded_at type="datetime">2009-04-23T14:03:16-04:00</uploaded_at>
	  <size_bytes type="float">314559</size>
  </download>
</downloads>
Resources
Open Source Libraries
Developers Wanted

We need talented people to write open-source code for popular languages and applications (PHP, Volusion, Wordpress, Drupal, and more).

Contact us if you're interested!