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>