Freewebstore API Documentation

Menu

Status

API Keys Are Currently Only Available In Control Panel v1

December 2019 - We're launching a new JSON based API soon, and this API will be decommissioned. If you're using this API, we'll be in touch about moving to the new release, once available. Watch this space !

Getting Started

The Freewebstore API is a RESTful web service using XML over HTTP. The HTTP methods used are GET, POST and DELETE. Therefore, technical knowledge in this area is essential.

The first step to using the API is getting authorisation from Freewebstore. Simply login to your Control Panel and navigate to Settings > Store API and select the "Generate API Key" button. You will then be supplied with an API Key and Client ID.

How to Use the API

Authorization

All API requests should be made via HTTP using the Freewebstore API URL: https://api.freewebstore.org

Authentication is managed using HTTP Basic Authentication. You will use your Client ID and API Key to authenticate. For example:

                                curl -u clientid:apikey -H 'Content-Type: application/xml' \
    https://api.freewebstore.org/category/
                                    

Every request sent to the Freewebstore API must be in XML format. This means the Content-Type header must be set to application/xml.

Requests

The base URL for the Freewebstore API is: https://api.freewebstore.org/

Here are some examples of resource URIs:
https://api.freewebstore.org/category/
https://api.freewebstore.org/product/123456
https://api.freewebstore.org/shop/domain

See the Resource and URI Reference for all the possible requests URIs and HTTP verbs for the API resources.

Ensure all required nodes are present and in the correct order as set out in this section.

All requests are validated against an XML schema, which may be subject to change. The schema can be viewed at https://api.freewebstore.org/{resource}/{resource}.xsd in order to check that POSTed XML data is valid. For example https://api.freewebstore.org/product/product.xsd or https://api.freewebstore.org/category/category.xsd.

Only one record can be POSTed in any single request. In other words, only add and update one product / category / domain at a time.

There is a limit of 2500 requests per hour. Rate limiting is on a per user or per application basis. If this reached you will receive a 503 - Service Unavailable error.

Responses

If an API request fails, the error information will be returned with the HTTP status code together with an XML response. For example, if you supply incorrect API Key details, you will get a 401 Unauthorized response:

                                HTTP/1.x 401 Unauthorized
Date: Thu, 20 Mar 2011 11:28:23 GMT

<error>
    <date>Thu, 20 Oct 2011 11:28:23</date>
    <status>401 - Unauthorized</status>
    <message>Invalid API Key</message>
</error>
                                    

If a request adds new records, for example when a new product is added, the response will use a 201 Created status and XML with the new details will be displayed.

                                HTTP/1.x 201 Created
Date: Thu, 20 Oct 2011 11:45:02 GMT

<shop>
    <name>Test Store</name>
</shop>
                                    

Any other successful operation will return the 200 OK status code, together with relevant response XML:

                                HTTP/1.x 200 OK
Date: Thu, 20 Oct 2011 11:45:02 GMT

<categories>
    <category>
        <id>933818</id>
        <name>Category 1</name>
        <shopkeeper>1234</shopkeeper>
        <parentID>0</parentID>
        <description>Description of category</description>
        <imageURL>image.gif</imageURL>
        <sequence>4</sequence>
        <visible>0</visible>
    </category>
</categories>
                                    

Resources

1. Category
1.1 List Categories

Use GET /category/ to retrieve a full list of Category IDs.

                                <categories>
    <category>
        <id>933818</id>
        <Name>Category 1</Name>
        <ParentID>0</ParentID>
    </category>
    <category>
        <id>933819</id>
        <Name>Category 2</Name>
        <ParentID>0</ParentID>
    </category>
</categories>
                                        

Optional parameters: offset (int), limit (int), visible (bool), parentID (int) eg. /category/?offset=0&limit=10&visible=1

2. Product
2.1 List Products

Use GET /product/ to retrieve a full list of products.

                                <products>
    <product>
        <id>3777977</id>
        <productName>Product 1</productName>
    </product>
    <product>
        <id>12345678</id>
        <productName>Product 2</productName>
    </product>
</products>
                                        

Optional parameters: offset (int), limit (int), category (int), visible (bool), featured (bool), fields (str)
NB: All product fields apart from 'extraImages' and 'additionalCategories' can be added to a comma seperated list for the fields parameter.
eg. /product/?category=1454&visible=1&fields=id,sku,productName,category,brand

3. Order
3.1 List Orders

Use GET /order/ to retrieve a full list of Orders.

                                <orders>
    <order>
        <id>481320</id>
        <customer>481320</customer>
        <creationdate>19-05-2012 10:36</creationdate>
        <total>1518.5</total>
        <status>2</status>
        <isnew>0</isnew>
        <paymentmethod>PayPal</paymentmethod>
        <dispatched>1</dispatched>
        <shopkeeper_orderno>1001</shopkeeper_orderno>
    </order>
    <order>
        <id>481325</id>
        <customer>4545</customer>
        <creationdate>25-04-2012 18:45</creationdate>
        <total>1518.5</total>
        <status>2</status>
        <isnew>0</isnew>
        <paymentmethod>PayPal</paymentmethod>
        <dispatched>1</dispatched>
        <shopkeeper_orderno>1002</shopkeeper_orderno>
    </order>
</orders>
                                        

Optional parameters: offset (int), limit (int), isnew (bool), status(int) ( 0 - payment not processed, 1 - payment processed, 2 - closed, 3 - problem)
eg. /order/?offset=0&limit=10&isnew=1&status=1

3.2 Show Order Details

Use GET /order/{orderID} to obtain the details for a specific order.

                                <orders>
    <order>
        <id>521965</id>
        <shopkeeper_orderno>1001</shopkeeper_orderno>
        <customer>528870</customer>
        <creationdate>Oct 17 2011 01:03:53:557PM</creationdate>
        <reference>1bn0b445h1q2lmuz1hvmm255</reference>
        <net>22.99</net>
        <vat>5.0233</vat>
        <deductions>2.99</deductions>
        <order>
            <discount>
                <couponcode>DFR456</couponcode>
                <discount>2.99&</discount>
                <couponID>7458</couponID>
            </discount>
        </order>
        <status>0</status>
        <isnew>1</isnew>
        <postage>0.59</postage>
        <postage_method>UK Second Class: For baskets whose total weight is between 101g and 250g</postage_method>
        <paymentmethod>PayPal </paymentmethod>
        <instructions/>
        <errors/>
        <kashflow_synch>0</kashflow_synch>
        <order>
            <billing_address>
                <surname>Smith</surname>
                <forename>Anthony</forename>
                <companyname>Test Company</companyname>
                <add1>3 Test Street</add1>
                <add2></add2>
                <add3></add3>
                <city>Test City</city>
                <county>Test County</county>
                <postcode>SK3 7GH</postcode>
                <telephone>045896 4587896</telephone>
                <mobile>07789582696</mobile>
            </billing_address>
        </order>
        <order>
            <delivery_address>
                <surname>Smith</surname>
                <forename>Christine</forename>
                <companyname></companyname>
                <add1>10 Test Road</add1>
                <add2></add2>
                <add3></add3>
                <city>Test City</city>
                <county>Test County</county>
                <postcode>SK4 6NG</postcode>
                <telephone>045896 4587896</telephone>
                <mobile>07789582696</mobile>
            </delivery_address>
        </order>
        <postage_tax>0</postage_tax>
        <dispatched>0</dispatched>
        <paybyotherid>-1</paybyotherid>
        <ip>81.168.44.121 </ip>
        <wheredidyouhearid>-1</wheredidyouhearid>
        <items>
            <id>775434</id>
            <headerID>521965</headerID>
            <productID>4084620</productID>
            <description>lorem ipsum</description>
            <net>22.99</net>
            <vat>5.0233</vat>
            <qty>1</qty>
            <formID>-1</formID>
            <options>
                <option_271080>
                <id>271080</id>
                <orderDetailsID>775434</orderDetailsID>
                <optionid>763217</optionid>
                <optionCost>100</optionCost>
                <optionVAT>17.5</optionVAT>
                <customText>txt 1</customText>
                </option_271080>
            <option_271081>
                <id>271081</id>
                <orderDetailsID>775434</orderDetailsID>
                <optionid>763242</optionid>
                <optionCost>0</optionCost>
                <optionVAT>0</optionVAT>
                <customText>text 2</customText>
            </option_271081>
            </options>
        </items>
    </order>
</orders>
                                        
3.3 Show New Orders

Use GET /order/new to return the number of new orders.

Appendix

Resouce and URI Reference
URI Method Resource Operation
/category/?parameter={parameter} GET Category Retrieves list of category IDs. Optional parameters: visible, parentID, offset, limit
/product/?parameter={parameter} GET Product Retrieves list of product IDs. Optional parameters: category, visible, featured, offset, limit, fields
/order/?parameter={parameter} GET Order Retrieves list of orders. Optional parameters: offset, limit, isnew, status
/order/{orderID} GET Order Retrieves  order details for single order
/order/new GET Order Bring back amount of new orders

Example Code

To help get you started, download a simple working example in your preferred language.

Change Log
  • 10 September 2013 - API KEY RESOURCE
    Improved: Made improvements to the API Key generator, users will need to generate a new API Key to connect to the API.

  • 19 August 2013 - Customer Resource
    Improved: Removed address details from customer resource, Address now has its own resource.

  • 19 August 2013 - Customer Resource
    Improved: Can use GET /customer/?all=1 to bring out all customers instead of customers that have an order associated with it.

  • 19 August 2013 - Order Resource
    Added: Can now POST orders

  • 19 August 2013 - Customer Resource
    Added: Can now POST customers.

  • 19 August 2013 - Customer Resource
    Added: Can now DELETE customer.

  • 19 August 2013 - Countries & Regions Resource
    Added: Added a new Countries & Regions resource.

  • 19 August 2013 - Address Resource
    Added: Added a new address resource.

  • 19 August 2013 - Order Resource
    Improved: 'discounts' have been added to the GET /order/{orderid} results

  • 19 August 2013 - Order Resource
    Improved: GET /order/ now brings out all orders regardless of payment status, prevously brought back only orders where payment was processed. Use the 'status' parameter instead.

  • 13 May 2013 - Order Resource
    Added: Included optional parameters: isnew (bool).

  • 15 Nov 2012 - Image Resource
    Added: Included new Image resource to manage product Images.

  • 07 Nov 2012 - Product Resource
    Removed: Removed GET /product/category/{categoryID}. Use /product/?cat={catID} instead.

  • 07 Nov 2012 - Product Resource
    Improved: Ability to specify fields when returning list of products. eg. GET /product/?fields=id,category,producName,productImageURL

  • 07 Nov 2012 - Product Resource
    Improved: Included Additional Categories and Extra Images for a product.

  • 25 Oct 2012 - Brand Resource
    Added: Added new Brand resource.

  • 25 Oct 2012 - Order Resource
    Added: Added new field 'postage_method' to Order resource.

  • 03 Oct 2012 - Product Resource
    Improved: Renamed field 'ClientsCode' to 'sku'.

  • 27 Sept 2012 - Product Resource
    Deprecated: GET /product/category/{categoryID} to be removed. Use /product/?cat={catID} instead.