!!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>