!!This is the old version!!
We have released a new version (2.0) of the API. Version 1.0) is deprecated. Click here for details.
API Documentation
The FetchApp 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.
Use the open-source Ruby, Python, or .NET code libraries for quick integration.
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: app.fetchapp.com Authorization: Basic ZGVtb2tleTpkZW1vdG9rZW4= Content-Type: application/xml
** Please make sure to set the Content-Type header to 'application/xml'.
Alternatively you may send your key and token inline with the request URL...
http://demokey:demotoken@app.fetchapp.com/api/orders
All URI's are also accessible via your browser by appending .xml to the request...
http://demokey:demotoken@app.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_bytes>
</download>
<download>
<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_bytes>
</download>
</downloads>
NOTE: The lack of an order_id indicates that the download was from a 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. Example result...
<?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>
<vendor_id>1554898798</vendor_id>
<first_name>Donald</first_name>
<last_name>Duck</last_name>
<email>donald@duck.com</email>
<link>/get/tydjdje</link>
<link_full>http://demo.fetchapp.com/get/tydjdje</link_full>
<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>
<price type="float">Quality Bill Wax</price>
<order_id>1001</order_id>
<guid>tydjdje</guid>
<download_count type="integer">1</download_count>
<downloads_remaining type="integer"></downloads_remaining>
<created_at type="datetime">2008-11-28T18:47:56+00:00</created_at>
<files type="array">
<filename>file-1.txt</filename>
<guid>abcdef</guid>
<download_count type="integer">1</download_count>
<link>/files/abcdef</link>
<link_full>http://demo.fetchapp.com/files/abcdef</link_full>
<downloads_remaining>type="integer 1</downloads_remaining>
<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</size>
</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</size>
</download>
</downloads>
</files>
<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</size>
</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</size>
</download>
</downloads>
</order_item>
</order_items>
</order>
DELETE a specified order...
/api/orders/:id/delete /api/orders/:id/delete.xml
GET 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?reset_expiration=false
/api/orders/:id/send_email?expiration_date=2011-03-07T15:08:02+00:00&download_limit=10
/api/orders/:id/send_email.xml?expiration_date=2011-03-07T15:08:02+00:00&download_limit=10
NOTE: reset_expiration is an optional boolean, and defaults to true if not present. If true, the expiration date will be set to whatever is selected in Settings → General or provided by the param expiration_date and the download limit will be set to whatever is selected in Settings → General or download_limit if present. Both expiration_date and download_limit are optional and if present override the default values option.
GET statistics about an order...
/api/orders/:id/stats /api/orders/:id/stats.xml
For example...
<?xml version="1.0" encoding="UTF-8"?>
<stats>
<download_count>14</download_count>
</stats>
POST to create an order...
/api/orders/create /api/orders/create.xml
For example...
<?xml version="1.0" encoding="UTF-8"?>
<order>
<send_email>true</send_email>
<id>1</id>
<vendor_id>1554898798</vendor_id>
<first_name>Bugs</first_name>
<last_name>Bunny</last_name>
<email>bugs@bunny.com</email>
<expiration_date type="datetime">2010-09-07T15:08:02+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>
<price type="float">4.99</price>
</order_item>
</order_items>
</order>
NOTE: price is optional and defaults to the price set in the UI if not present. 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.
PUT to update a specified order...
/api/orders/:id/update /api/orders/:id/update.xml
For example...
<?xml version="1.0" encoding="UTF-8"?>
<order>
<send_email>false</send_email>
<id>1</id>
<first_name>Bugs</first_name>
<last_name>Bunny</last_name>
<email>bugs@bunny.com</email>
<expiration_date type="datetime">2010-09-07T15:08:02+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>
<price type="float">4.99</price>
</order_item>
</order_items>
</order>
NOTE: price is optional and defaults to the price set in the UI if not present. send_email is optional and defaults to false if not present. All fields can be changed including the order ID.
GET to import orders (Shopify only)...
/api/orders/import /api/orders/import.xml
Example result...
<?xml version="1.0" encoding="UTF-8"?> <message>Import results message...</message>
NOTE: An email describing the results will be sent to the account owner.
Products
List all your products...
/api/items /api/items.xml /api/items.xml?per_page=25&page=2
Example result...
<?xml version="1.0" encoding="UTF-8"?>
<items type="array">
<item>
...
</item>
<item>
...
</item>
</items>
List details of a specified product...
/api/items/:sku /api/items/:sku.xml
Example result...
<?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>
<price type="float">5.00</price>
<created_at type="datetime">2008-11-10T22:54:32+00:00</created_at>
<files type="array">
<file>
<filename>part-1.zip</filename>
<size_bytes type="integer">9774173559</size_bytes>
<content_type>binary/octet-stream</content_type>
<permalink>/permalink/yuurud</permalink>
<permalink_full>http://pixellent.fetchapp.com/permalink/yuurud</permalink_full>
</file>
<file>
<filename>part-2.zip</filename>
<size_bytes type="integer">4544173559</size_bytes>
<content_type>binary/octet-stream</content_type>
<permalink>/permalink/werwa</permalink>
<permalink_full>http://pixellent.fetchapp.com/permalink/werwa</permalink_full>
</file>
</files>
<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
</size_bytes></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
</size_bytes></download>
</downloads>
</item>
item.guid, item.permalink, item.permalink_full, item.filename, item.size_bytes, and item.content_type are depreciated. They will return the values for the first file in the files array, but will eventually be removed.
Delete a specified product...
/api/items/:sku/delete /api/items/:sku/delete.xml
This will also remove the product from any existing orders.
GET statistics about a product...
/api/items/:sku/stats /api/items/:sku/stats.xml
For example...
<?xml version="1.0" encoding="UTF-8"?>
<stats>
<download_count>14</download_count>
<order_count>14</order_count>
</stats>
POST to create a specified product...
/api/items/create /api/items/create.xml
For example...
<?xml version="1.0" encoding="UTF-8"?>
<item>
<sku>1</sku>
<name>Carrot Juice</name>
<price type="float">10.00</price>
</item>
PUT to update a specified product...
/api/items/:sku/update /api/items/:sku/update.xml
For example...
<?xml version="1.0" encoding="UTF-8"?>
<item>
<sku>2</sku>
<name>Tomato Juice</name>
<price type="float">10.0</price>
</item>
The SKU can be changed if necessary.
GET to list all files for a specified product...
/api/items/:sku/files /api/items/:sku/files.xml
Example result...
<?xml version="1.0" encoding="UTF-8"?>
<files type="array">
<file>
<filename>Part1.zip</filename>
<size_bytes type="integer">9774173559</size_bytes>
<content_type>binary/octet-stream</content_type>
<permalink>/permalink/yuurud</permalink>
<permalink_full>http://pixellent.fetchapp.com/permalink/yuurud</permalink_full>
</file>
<file>
<filename>Part2.zip</filename>
<size_bytes type="integer">4544173559</size_bytes>
<content_type>binary/octet-stream</content_type>
<permalink>/permalink/werwa</permalink>
<permalink_full>http://pixellent.fetchapp.com/permalink/werwa</permalink_full>
</file>
</files>
No order_id indicates a direct download of the item via the permalink.
GET to list all downloads for a specified product...
/api/items/:sku/downloads /api/items/:sku/downloads.xml
Example result...
<?xml version="1.0" encoding="UTF-8"?>
<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
</size_bytes></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
</size_bytes></download>
</downloads>
No order_id indicates a direct download of the item via the permalink.
GET to import products (Shopify only)...
/api/items/import /api/items/import.xml
Example result...
<?xml version="1.0" encoding="UTF-8"?> <message>Import results message...</message>
An email describing the results will be sent to the account owner. An optional parameter of send_email=false can be specified to prohibit the sending of the results email.
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_bytes>
</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_bytes>
</upload>
</uploads>