Help

Help API2 August 06 2012

API Documentation

The FetchApp API is implemented as RESTful (using all four verbs GET/POST/PUT/DELETE) XML over HTTP.  URIs are given with the RESTful option first, followed by alternative paths.

Every resource, like orders and products, 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.

The following open-source libraries are available:

(.NET and Python libraries pending update to be compatible with version 2.0 of our API)

Navigation

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/v2/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'. **

Connectivity

GET the time to test connectivity...

GET /api/v2/time
/api/v2/time.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<time>2013-06-13T10:29:55-05:00</time>

Account

GET information about your account...

/api/v2/account
/api/v2/account.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<account>
    <id type="integer">4334</id>
    <name>Warner Brothers</name>
    <email>bugs@bunny.com</email>
    <url>warner.fetchapp.com</url>
    <billing_email>daffy@duck.com</billing_email>
    <order_expiration_in_hours type="integer">240</order_expiration_in_hours>
    <download_limit_per_item type="integer">3</download_limit_per_item>
    <currency>USD</currency>
    <created_at type="datetime">2008-12-28T18:47:56+00:00</created_at>
    <api_key>bugs</api_key>
    <api_token>carrots</api_token>
</account>

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

/api/v2/new_token
/api/v2/new_token.xml

Example result...

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

Downloads

GET a list of your downloads...

/api/v2/downloads
/api/v2/downloads.xml
/api/v2/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>
        <product_sku>BILL-WAX</product_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="integer">314559</size_bytes>
    </download>
    <download>
        <id>434</id>
        <filename>myfile.txt</filename>
        <product_sku>BILL-WAX</product_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="integer">314559</size_bytes>
    </download>
</downloads>

NOTE: A nil order_id indicates that the download was from a permalink.

Files

GET a list of your files...

/api/v2/files
/api/v2/files.xml
/api/v2/files.xml?per_page=25&page=2

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<files type="array">
    <file>
        <id type="integer">101551</id>
        <filename>ebook_collection.zip</filename>
        <size_bytes type="integer">5652920</size_bytes>
        <content_type>binary/octet-stream</content_type>
        <permalink href="http://demo.fetchapp.com/permalink/abcdef">/permalink/abcdef</permalink>
        <url nil="true"></url>
        <type>file</type>
    </file>
    <file>
        <id type="integer">148782</id>
        <filename>Movie Magic Video</filename>
        <size_bytes nil="true"></size_bytes>
        <content_type nil="true"></content_type>
        <permalink href="http://demo.fetchapp.com/permalink/ghijkl">/permalink/ghikjl</permalink>
        <url>http://your.cdn.com/link/to/file</url>
        <type>url</type>
   </file>
</files>

Orders

GET a list of all your orders...

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

Status can be open or expired. If not specified then all orders (open and expired) will be returned. Example result...

<?xml version="1.0" encoding="UTF-8"?>
<orders type="array">
    <order>
        <id>1001</id>
        <vendor_id>1554898798</vendor_id>
        <first_name>Donald</first_name>
        <last_name>Duck</last_name>
        <email>donald@duck.com</email>
        <total type="float">44.50</total>
        <currency>USD</currency>
        <status>open</status>
        <product_count type="integer">1</product_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>
        <custom_1 nil="true"></custom_1>
        <custom_2 nil="true"></custom_2>
        <custom_3 nil="true"></custom_3>
        <created_at type="datetime">2008-11-28T18:47:56+00:00</created_at>
        <link href="http://demo.fetchapp.com/get/tydjdje">/get/tydjdje</link>
        <order_items_uri>https://demo.fetchapp.com/api/v2/orders/1001/order_items</order_items_uri>
        <downloads_uri>https://demo.fetchapp.com/api/v2/orders/1001/downloads</downloads_uri>
    </order>
    <order>
        <id>1002</id>
        <vendor_id>1554898799</vendor_id>
        <first_name>Bugs</first_name>
        <last_name>Bunny</last_name>
        <email>bugs@bunny.com</email>
        <total type="float">12.99</total>
        <currency>GBP</currency>
        <status>open</status>
        <product_count type="integer">2</product_count>
        <download_count type="integer">5</download_count>
        <expiration_date nil="true"></expiration_date>
        <download_limit type="integer">3</download_limit>
        <custom_1 nil="true"></custom_1>
        <custom_2 nil="true"></custom_2>
        <custom_3 nil="true"></custom_3>
        <created_at type="datetime">2008-11-28T18:47:56+00:00</created_at>
        <link href="http://demo.fetchapp.com/get/tydjdje">/get/tydjdje</link>
        <order_items_uri>https://demo.fetchapp.com/api/v2/orders/1002/order_items</order_items_uri>
        <downloads_uri>https://demo.fetchapp.com/api/v2/orders/1002/downloads</downloads_uri>
    </order>
</orders>

GET details of the specified order...

/api/v2/orders/:id
/api/v2/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>
    <total type="float">44.50</total>
    <currency>USD</currency>
    <status>open</status>
    <product_count type="integer">1</product_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>
    <custom_1 nil="true"></custom_1>
    <custom_2 nil="true"></custom_2>
    <custom_3 nil="true"></custom_3>
    <created_at type="datetime">2008-11-28T18:47:56+00:00</created_at>
    <link href="http://demo.fetchapp.com/get/tydjdje">/get/tydjdje</link>
    <order_items_uri>https://demo.fetchapp.com/api/v2/orders/1001/order_items</order_items_uri>
    <downloads_uri>https://demo.fetchapp.com/api/v2/orders/1001/downloads</downloads_uri>
</order>

POST to create an order...

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

For example...

<?xml version="1.0" encoding="UTF-8"?>
<order>
    <id>1</id>
    <vendor_id>1554898798</vendor_id>
    <first_name>Bugs</first_name>
    <last_name>Bunny</last_name>
    <email>bugs@bunny.com</email>
    <currency>USD</currency>
    <custom_1>Optional</custom_1>
    <custom_2>Custom</custom_2>
    <custom_3>Values</custom_3>
    <expiration_date type="datetime">2010-09-07T15:08:02+00:00</expiration_date>
    <download_limit type="integer">5</download_limit>
    <send_email>true</send_email>
    <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 the specified order...

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

For example...

<?xml version="1.0" encoding="UTF-8"?>
<order>
    <id>1</id>
    <first_name>Bugs</first_name>
    <last_name>Bunny</last_name>
    <email>bugs@bunny.com</email>
    <currency>USD</currency>
    <custom_1>Optional</custom_1>
    <custom_2>Custom</custom_2>
    <custom_3>Values</custom_3>
    <expiration_date type="datetime">2010-09-07T15:08:02+00:00</expiration_date>
    <download_limit type="integer">5</download_limit>
    <send_email>false</send_email>
    <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.

DELETE the specified order...

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

Example result...

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

GET to list all downloads for the specified order...

/api/v2/orders/:id/downloads
/api/v2/orders/:id/downloads.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<downloads type="array">
    <download>
        <id>233</id>
        <filename>photo.jpg</filename>
        <product_sku>BILL-WAX</product_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>
        <filename>ebook.pdf</filename>
        <product_sku>BILL-WAX</product_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>

GET to expire the specified order...

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

Example result...

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

POST to send download email for the specified order...

/api/v2/orders/:id/send_email?reset_expiration=false

/api/v2/orders/:id/send_email?expiration_date=2011-03-07T15:08:02+00:00&download_limit=10

/api/v2/orders/:id/send_email.xml?expiration_date=2011-03-07T15:08:02+00:00&download_limit=10

Example result...

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

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/v2/orders/:id/stats
/api/v2/orders/:id/stats.xml

For example...

<?xml version="1.0" encoding="UTF-8"?>
<order>
    <id>1001</id>
    <vendor_id>1554898798</vendor_id>
    <download_count type="integer">1</download_count>
    <product_count type="integer">1</product_count>
    <total type="float">44.50</total>
    <currency>USD</currency>
</order>

Order Items

GET a list of all order items for the specified order...

/api/v2/orders/:id/order_items
/api/v2/orders/:id/order_items.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<order_items type="array">
  <order_item>
    <id type="integer">821431</id>
    <sku>BILL-WAX</sku>
    <order_id>1001</order_id>
    <product_name>Quality Bill Wax</product_name>
    <price type="float">5.00</price>
    <download_count type="integer">2</download_count>
    <custom_1 nil="true"></custom_1>
    <custom_2 nil="true"></custom_2>
    <custom_3 nil="true"></custom_3>
    <license_key nil="true"></license_key>
    <created_at type="datetime">2012-08-01T15:54:06Z</created_at>
    <files_uri>https://demo.fetchapp.com/api/v2/orders/1001/order_items/821431/files</files_uri>
    <downloads_uri>https://demo.fetchapp.com/api/v2/orders/1001/order_items/821431/downloads</downloads_uri>
  </order_item>
</order_items>

GET details of the specified order item...

/api/v2/orders/:order_id/order_items/:id
/api/v2/orders/:order_id/order_items/:id.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<order_item>
  <id type="integer">821431</id>
  <sku>BILL-WAX</sku>
  <order_id>1001</order_id>
  <product_name>Quality Bill Wax</product_name>
  <price type="float">5.00</price>
  <download_count type="integer">2</download_count>
  <custom_1 nil="true"></custom_1>
  <custom_2 nil="true"></custom_2>
  <custom_3 nil="true"></custom_3>
  <license_key nil="true"></license_key>
  <created_at type="datetime">2012-08-01T15:54:06Z</created_at>
  <files_uri>https://demo.fetchapp.com/api/v2/orders/1001/order_items/821431/files</files_uri>
  <downloads_uri>https://demo.fetchapp.com/api/v2/orders/1001/order_items/821431/downloads</downloads_uri>
</order_item>

GET to list all files for the specified order item...

/api/v2/orders/:order_id/order_items/:id/files
/api/v2/orders/:order_id/order_items/:id/files.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<files type="array">
    <file>
        <id>123</id>
        <filename>Part1.zip</filename>
        <size_bytes type="integer">9774173559</size_bytes>
        <content_type>binary/octet-stream</content_type>
        <permalink href="http://demo.fetchapp.com/permalink/yuurud">/permalink/yuurud</permalink>
        <url nil="true"></url>
    </file>
    <file>
        <id>432</id>
        <filename>External File Name</filename>
        <size_bytes nil="true"></size_bytes>
        <content_type nil="true"></content_type>
        <permalink href="http://demo.fetchapp.com/permalink/werwa">/permalink/werwa</permalink>
        <url>http://your.cdn.com/link/to/file</url>
    </file>
</files>

For files stored in FetchApp, the url will be nil. For files stored externally the size_bytes and content_type will be nil since this information isn't available.

GET to list all downloads for the specified order item...

/api/v2/orders/:order_id/order_items/:id/downloads
/api/v2/orders/:order_id/order_items/:id/downloads.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<downloads type="array">
    <download>
        <id>233</id>
        <filename>photo.jpg</filename>
        <product_sku>BILL-WAX</product_sku>
        <order_id>1001</order_id>
        <order_item_id>821431</order_item_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>
        <filename>ebook.pdf</filename>
        <product_sku>BILL-WAX</product_sku>
        <order_id>1001</order_id>
        <order_item_id>821431</order_item_id>
        <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>

GET to expire the specified order item...

/api/v2/orders/:order_id/order_items/:id/expire
/api/v2/orders/:order_id/order_items/:id/expire.xml

Example result...

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

Products

GET a list all your products...

/api/v2/products
/api/v2/products.xml
/api/v2/products.xml?per_page=25&page=2
Example result...
<?xml version="1.0" encoding="UTF-8"?>
<products type="array">
    <product>
        <id>BILL-WAX</id>
        <sku>BILL-WAX</sku>
        <name>Quality Bill Wax</name>
        <price type="float">5.00</price>
        <order_count type="integer">4</order_count>
        <download_count type="integer">5</download_count>
        <paypal_add_to_cart_link href="http://demo.fetchapp.com/sell/abcdef/ppc">/sell/abcdef/ppc</paypal_add_to_cart_link>
        <paypal_buy_now_link href="http://demo.fetchapp.com/sell/jshahsai">/sell/abcdef</paypal_buy_now_link>
        <paypal_view_cart_link href="http://demo.fetchapp.com/cart/pp">/cart/pp</paypal_view_cart_link>
        <created_at type="datetime">2008-11-10T22:54:32+00:00</created_at>
        <files_uri>https://demo.fetchapp.com/api/v2/products/BILL-WAX/files</files_uri>
        <downloads_uri>https://demo.fetchapp.com/api/v2/products/BILL-WAX/downloads</downloads_uri>
    </product>
    <product>
        <id>FEATHER-DUSTER</id>
        <sku>FEATHER-DUSTER</sku>
        <name>Duck Feather Duster</name>
        <price type="float">3.00</price>
        <order_count type="integer">2</order_count>
        <download_count type="integer">2</download_count>
 <paypal_add_to_cart_link href="http://demo.fetchapp.com/sell/jklmno/ppc">/sell/jklmno/ppc</paypal_add_to_cart_link>
        <paypal_buy_now_link href="http://demo.fetchapp.com/sell/jklmno">/sell/jklmno</paypal_buy_now_link>
        <paypal_view_cart_link href="http://demo.fetchapp.com/cart/pp">/cart/pp</paypal_view_cart_link>
        <created_at type="datetime">2008-11-10T22:54:32+00:00</created_at>
        <files_uri>https://demo.fetchapp.com/api/v2/products/FEATHER-DUSTER/files</files_uri>
        <downloads_uri>https://demo.fetchapp.com/api/v2/products/FEATHER-DUSTER/downloads</downloads_uri>
    </product>
</products>

GET details of the specified product...

/api/v2/products/:sku
/api/v2/products/:sku.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<product>
    <id>BILL-WAX</id>
    <sku>BILL-WAX</sku>
    <name>Quality Bill Wax</name>
    <price type="float">5.00</price>
    <order_count type="integer">4</order_count>
    <download_count type="integer">5</download_count>
 <paypal_add_to_cart_link href="http://demo.fetchapp.com/sell/abcdef/ppc">/sell/abcdef/ppc</paypal_add_to_cart_link>
        <paypal_buy_now_link href="http://demo.fetchapp.com/sell/jshahsai">/sell/abcdef</paypal_buy_now_link>
        <paypal_view_cart_link href="http://demo.fetchapp.com/cart/pp">/cart/pp</paypal_view_cart_link>
    <created_at type="datetime">2008-11-10T22:54:32+00:00</created_at>
    <files_uri>https://demo.fetchapp.com/api/v2/products/BILL-WAX/files</files_uri>
    <downloads_uri>https://demo.fetchapp.com/api/v2/products/BILL-WAX/downloads</downloads_uri>
</product>

POST to create the specified product...

/api/v2/products
/api/v2/products/create
/api/v2/products/create.xml

For example...

<?xml version="1.0" encoding="UTF-8"?>
<product>
    <sku>1</sku>
    <name>Carrot Juice</name>
    <price type="float">10.00</price>
    <files type="array">
        <id>4443443</id>
        <id>4443444</id>
    </files>
</product>

PUT to update the specified product...

/api/v2/products/:sku
/api/v2/products/:sku/update
/api/v2/products/:sku/update.xml

For example...

<?xml version="1.0" encoding="UTF-8"?>
<product>
    <sku>2</sku>
    <name>Tomato Juice</name>
    <price type="float">10.0</price>
    <files type="array">
        <id>4443443</id>
        <id>4443444</id>
    </files>
</product>

The SKU can be changed if necessary.

Delete the specified product...

/api/v2/products/:sku
/api/v2/products/:sku/delete
/api/v2/products/:sku/delete.xml

This will also remove the product from any existing orders. 

Example result...

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

GET statistics about a product...

/api/v2/products/:sku/stats
/api/v2/products/:sku/stats.xml

For example...

<?xml version="1.0" encoding="UTF-8"?>
<product>
    <id>0001</id>
    <sku>0001</sku>
    <price type="float">0.01</price>
    <currency>USD</currency>
    <download_count>14</download_count>
    <order_count>14</order_count>
</product>

GET to list all files for the specified product...

/api/v2/products/:sku/files
/api/v2/products/:sku/files.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<files type="array">
    <file>
        <id>123</id>
        <filename>Part1.zip</filename>
        <size_bytes type="integer">9774173559</size_bytes>
        <content_type>binary/octet-stream</content_type>
        <permalink href="http://demo.fetchapp.com/permalink/yuurud">/permalink/yuurud</permalink>
        <url nil="true"></url>
    </file>
    <file>
        <id>432</id>
        <filename>External File Name</filename>
        <size_bytes nil="true"></size_bytes>
        <content_type nil="true"></content_type>
        <permalink href="http://demo.fetchapp.com/permalink/werwa">/permalink/werwa</permalink>
        <url>http://your.cdn.com/link/to/file</url>
    </file>
</files>

For files stored in FetchApp, the url will be nil. For files stored externally the size_bytes and content_type will be nil since this information isn't available.

GET to list all downloads for the specified product...

/api/v2/products/:sku/downloads
/api/v2/products/:sku/downloads.xml

Example result...

<?xml version="1.0" encoding="UTF-8"?>
<downloads type="array">
    <download>
        <id>233</id>
        <filename>photo.jpg</filename>
        <product_sku>BILL-WAX</product_sku>
        <order_id>1001</order_id>
        <order_item_id>821431</order_item_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>
        <filename>ebook.pdf</filename>
        <product_sku>BILL-WAX</product_sku>
        <order_id nil="true"></order_id>
        <order_item_id nil="true"></order_item_id>
        <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>

A nil order_id or order_item_id indicates a direct download of the product via the permalink.

 

Help API November 02 2010

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

Help November 02 2010

Register for an Account

To begin using FetchApp you'll first need to register for an account. This is quickly achieved by completing the form on the sign-up page. An email with login instructions will be immediately sent to the address you enter.

If the free plan is chosen you don't even need to enter credit card information to begin using FetchApp. This is a completely risk-free way to see if FetchApp meets your needs.

Account Confirmation & Setup

After registering for a FetchApp account you'll receive an email that provides instructions on how to login. Click the unique confirmation link in the email and complete the online form to finish registration, then login to your own FetchApp admin.

Fetch Account Confirmation

Once logged in all your information (name, email, address, etc.) can be updated from the users page. This information can then be viewed by other account users.

Connect Carts & Payments

To start receiving orders you'll first need to connect FetchApp with your carts and/or payment processors such as PayPal, Goodsie, BigCommerce, or Shopify.

Fetch Carts & Payments

From the carts and payments setting page simply provide the requested information for each service you want to connect FetchApp with. Integration typically only requires a single email address or URL provided by your cart or payment processor.

Since payments aren't processed by FetchApp, you'll need to setup accounts with the supported carts or processors before they can be integrated with Fetch.

Create Products

Now that you've created a FetchApp account and connected it with your carts and/or payment processors, it's time to create some products and upload your digital files.

Fetch Products

Go to the products section of your FetchApp admin and click the add product button to begin building your inventory. If you're using Shopify or BigCommerce you may import all products from your store by clicking the import button on the products page.

Provide a title, SKU, and price to each product, then upload one (or several) files from your computer. All files previously uploaded will also be available to attach to any products.

Start Accepting Orders

After you've created products and associated files with each, you're ready to begin selling. It's all automated from here on out!

Fetch Orders

Either use the FetchApp-provided buttons (if using an payment processor like PayPal) or your cart to place orders. Once an order is received it will automatically show in your FetchApp admin and the time-sensitive links will be emailed to your customer.