Freewebstore API Documentation

Menu

Getting Started

The Freewebstore API is a RESTful web service using JSON over HTTP. The only HTTP method available is GET, with more due to be added in future. Technical knowledge in this area is essential.

The first step to using the API is getting authorization 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.

How to Use the API

Authorization

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

Authentication is managed using a Header Token. You will use your API Key to authenticate. For example:

                  curl "https://api.freewebstore.com/orders" -H "x-api-key:XyxYxyXyxYxyXyxYxyXyxYxyXyxYxyXyx"
                

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

Requests

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

Here are some examples of resource URIs:
https://api.freewebstore.com/category
https://api.freewebstore.com/product
https://api.freewebstore.com/orders/123456

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

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

Rate limiting/throttling is on a per user, per method basis. If this reached you will receive a 429 Too Many Requests error.

Responses

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

                  HTTP/1.x 403 Forbidden
                  Date: Wed, 18 Decr 2019 11:01:36 GMT
                  {"statusCode":403,"error":"Forbidden","message":"User is not authorized to access this resource"}
                

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

                  HTTP/1.x 200 OK
                  
                    {
                      "products": [
                      {
                        "rrp": "2.99",
                        "option_ids": [
                        "12345",
                        "12346"
                        ],
                        "condition": "0",
                        "categoryId": "12345",
                        "disabled": false,
                        "featured": false,
                        "offer_price": 1.99,
                        "tax_rate": 1,
                        "tags": [],
                        "is_option_stock": false,
                        "hidden": false,
                        "formId": "-1",
                        "updatedon": "2019-10-16T11:03:20.137Z",
                        "id": "123456",
                        "name": "Product Name",
                        "image": "product_image.png",
                        "price": 1.99,
                        "sku": "PRODCODE1",
                        "created": "2010-03-31T15:18:47.78Z",
                        "stock": 4,
                        "rating": "75.0",
                        "weight": "0.0g",
                        "shipping": "-1.0",
                        "hits": 0,
                        "sold": 15,
                        "stars": "4.0",
                        "google_online": false,
                        "supplierId": "-1",
                        "brandId": "-1",
                        "offer": true
                      }
                      ]
                    }
                  

Resources

1. Category
1.1 List Categories

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

                      
                        {
                          "categories": [
                          {
                            "id": "12345",
                            "name": "Category One",
                            "parent": "0",
                            "sequence": "1",
                            "description": true,
                            "hidden": false,
                            "image": "category_one.png",
                            "seo": {
                              "custom_url": null,
                              "title": null,
                              "keywords": null,
                              "description": null
                            }
                          },
                          {
                            "id": "12346",
                            "name": "Category Two ",
                            "parent": "0",
                            "sequence": "2",
                            "description": true,
                            "hidden": false,
                            "image": "category_two.png",
                            "seo": {
                              "custom_url": "category-two",
                              "title": null,
                              "keywords": null,
                              "description": null
                            }
                          }
                          ]
                        }
                      
                    
2. Product
2.1 List Products

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

                      
                        {
                          "products": [
                          {
                            "rrp": "2.99",
                            "option_ids": [
                            "12345",
                            "12346"
                            ],
                            "condition": "0",
                            "categoryId": "12345",
                            "disabled": false,
                            "featured": false,
                            "offer_price": 1.99,
                            "tax_rate": 1,
                            "tags": [],
                            "is_option_stock": false,
                            "hidden": false,
                            "formId": "-1",
                            "updatedon": "2019-10-16T11:03:20.137Z",
                            "id": "12345",
                            "name": "Product One",
                            "image": "product_one.png",
                            "price": 1.99,
                            "sku": "PROD1",
                            "created": "2010-03-31T15:18:47.78Z",
                            "stock": 4,
                            "rating": "75.0",
                            "weight": "0.0g",
                            "shipping": "-1.0",
                            "hits": 0,
                            "sold": 15,
                            "stars": "4.0",
                            "google_online": false,
                            "supplierId": "-1",
                            "brandId": "-1",
                            "offer": true
                          }
                          ]
                        }
                      
                    

Optional parameters: per_page (int), sort (str - any attribute name), sort_order (str - 'asc'|'desc'), start (int), categoryId (int)

2.2 Get Product

Use GET /product/{id} to get the detail for a specific product

                      
                        {
                          "stock_alert_level": -1,
                          "attributes": [],
                          "storeId": "111111",
                          "avg_rating": 0,
                          "id": 11111111,
                          "name": "Product Name",
                          "created": "2020-01-27T16:39:33.7412157",
                          "code": "1",
                          "stock": 0,
                          "price": 0.01,
                          "brand": 0,
                          "condition": 0,
                          "featured": true,
                          "formId": -1,
                          "supplierId": 0,
                          "hidden": false,
                          "active": false,
                          "deleted": false,
                          "is_stock_option": false,
                          "is_image_option": false,
                          "is_option": false,
                          "live_price": 0.01,
                          "base_price": 0.01,
                          "postage": {
                            "type": "free",
                            "value": 0
                          },
                          "rating": {
                            "value": 40,
                            "explanation": "Google Shopping Rating HTML"
                          },
                          "weight": 0,
                          "weight_units": "g",
                          "wholesale_price": 0,
                          "has_bulkrules": false,
                          "google_eligible": {
                            "value": false,
                            "explanation": "Google Shopping Not Eligible Reason"
                          },
                          "is_dummy": false,
                          "description_length": -1,
                          "flag_desc": false,
                          "vat": {
                            "value": 30,
                            "type": "custom"
                          },
                          "category": {
                            "primary": 1111111,
                            "name": "",
                            "other": []
                          },
                          "discount": {
                            "type": "none",
                            "value": 0
                          },
                          "images": {
                            "primary": ""
                          },
                          "google_category": "",
                          "bulk_rules": [],
                          "seo": {
                            "title": "",
                            "keywords": [],
                            "description": ""
                          },
                          "notes": "",
                          "related": [],
                          "upi": {
                            "ean": "",
                            "mpn": "",
                            "isbn": "",
                            "upc": "",
                            "google_exempt": false
                          },
                          "search_tags": []
                        }
                      
                    
2.3 Create Product

Use POST to /product/ to create a new Product

Fields "name", "code", "price" and "category -> primary" are REQUIRED

                        
                          Request: {
                            "stock_alert_level": -1,
                            "attributes": [],
                            "avg_rating": 0,
                            "name": "Product Name", //REQUIRED
                            "created": "2020-01-27T16:39:33.7412157",
                            "code": "1", //REQUIRED
                            "stock": 0,
                            "price": 0.01, //REQUIRED
                            "brand": 0,
                            "condition": 0,
                            "featured": true,
                            "formId": -1,
                            "supplierId": 0,
                            "hidden": false,
                            "active": false,
                            "deleted": false,
                            "is_stock_option": false,
                            "is_image_option": false,
                            "is_option": false,
                            "live_price": 0.01,
                            "base_price": 0.01,
                            "postage": {
                              "type": "free",
                              "value": 0
                            },
                            "rating": {
                              "value": 40,
                              "explanation": "Google Shopping Rating HTML"
                            },
                            "weight": 0,
                            "weight_units": "g",
                            "wholesale_price": 0,
                            "has_bulkrules": false,
                            "google_eligible": {
                              "value": false,
                              "explanation": "Google Shopping Not Eligible Reason"
                            },
                            "is_dummy": false,
                            "description_length": -1,
                            "flag_desc": false,
                            "vat": {
                              "value": 30,
                              "type": "custom"
                            },
                            "category": {
                              "primary": 1111111, //REQUIRED
                              "name": "",
                              "other": []
                            },
                            "discount": {
                              "type": "none",
                              "value": 0
                            },
                            "images": {
                              "primary": ""
                            },
                            "google_category": "",
                            "bulk_rules": [],
                            "seo": {
                              "title": "",
                              "keywords": [],
                              "description": ""
                            },
                            "notes": "",
                            "related": [],
                            "upi": {
                              "ean": "",
                              "mpn": "",
                              "isbn": "",
                              "upc": "",
                              "google_exempt": false
                            },
                            "search_tags": []
                          }
                        
                      
                        
                          200: {
                            "message":"Product Created",
                            "productId":11111111
                          }
                          
                          400: {
                            "errors":[{
                              "message":"The property [price] does not exist"
                            },
                            {
                              "message":"The property [category.primary] does not exist"
                            }],
                            "type":"ProductValidationException",
                            "count":2
                          }
                          
                          403: {
                            "Forbidden - "
                          }
                        
                      
2.4 Update Product

Use PUT to /product/{id} to update an existing Product

All Fields Are Optional

                        
                          Request: {
                            "stock_alert_level": -1,
                            "attributes": [],
                            "avg_rating": 0,
                            "name": "Product Name",
                            "created": "2020-01-27T16:39:33.7412157",
                            "code": "1",
                            "stock": 0,
                            "price": 0.01,
                            "brand": 0,
                            "condition": 0,
                            "featured": true,
                            "formId": -1,
                            "supplierId": 0,
                            "hidden": false,
                            "active": false,
                            "deleted": false,
                            "is_stock_option": false,
                            "is_image_option": false,
                            "is_option": false,
                            "live_price": 0.01,
                            "base_price": 0.01,
                            "postage": {
                              "type": "free",
                              "value": 0
                            },
                            "rating": {
                              "value": 40,
                              "explanation": "Google Shopping Rating HTML"
                            },
                            "weight": 0,
                            "weight_units": "g",
                            "wholesale_price": 0,
                            "has_bulkrules": false,
                            "google_eligible": {
                              "value": false,
                              "explanation": "Google Shopping Not Eligible Reason"
                            },
                            "is_dummy": false,
                            "description_length": -1,
                            "flag_desc": false,
                            "vat": {
                              "value": 30,
                              "type": "custom"
                            },
                            "category": {
                              "primary": 1111111,
                              "name": "",
                              "other": []
                            },
                            "discount": {
                              "type": "none",
                              "value": 0
                            },
                            "images": {
                              "primary": ""
                            },
                            "google_category": "",
                            "bulk_rules": [],
                            "seo": {
                              "title": "",
                              "keywords": [],
                              "description": ""
                            },
                            "notes": "",
                            "related": [],
                            "upi": {
                              "ean": "",
                              "mpn": "",
                              "isbn": "",
                              "upc": "",
                              "google_exempt": false
                            },
                            "search_tags": []
                          }
                        
                      
                        
                          200: {
                            "message":"Product Updated",
                            "productId":11111111
                          }
                          
                          400: {
                            "errors":[{
                              "message":"The property [price] does not exist"
                            },
                            {
                              "message":"The property [category.primary] does not exist"
                            }],
                            "type":"ProductValidationException",
                            "count":2
                          }
                          
                          403: {
                            "Forbidden - "
                          }
                        
                      
3. Order
3.1 List Orders

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

                        
                          "orders": [
                          {
                            "id": "12345",
                            "created": "2013-08-15T13:40:06.997Z",
                            "orderno": "1001",
                            "status": 1,
                            "method": "PayPal",
                            "deliveryname": "",
                            "tags": [
                            ""
                            ],
                            "net": "2.8405",
                            "discount": "0.0",
                            "tax": "0.0",
                            "postage": "1.0",
                            "postagetax": "0.0",
                            "total": "3.84",
                            "trackingcodes": [
                            ""
                            ],
                            "deleted": false,
                            "customerId": "12345",
                            "isnew": false,
                            "isstarred": null,
                            "isuploadedtokashflow": false,
                            "isdispatched": false,
                            "updatedon": null,
                            "flux": null
                          }
                          ]
                        
                      

Optional parameters: limit (int), status (str - "all"|"open"|"closed"|"problem"|"openproblem"|"new"|"starred"|"cart"), sort (str - "created"|"createddesc"|"orderno"|"ordernodesc"), tags (str - comma separated list), startdate (str - Zulu format timestamp), enddate (str - Zulu format timestamp), offset (int), fields (str - comma separated list of optional fields - valid values: "customer","tags")
eg. /orders/?offset=0&limit=10&status=new

3.2 Show Order Details

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

                          
                            {
                              "storeid": "12345",
                              "id": "12345",
                              "customerId": "12345",
                              "email": "user@domain.com",
                              "orderNo": 1001,
                              "created": "2013-08-15T13:40:06.997+00:00",
                              "net": 2.8405,
                              "tax": 0,
                              "postage": 1,
                              "postage_tax": 0,
                              "discount": 0,
                              "tax_rate": 0,
                              "paybyotherid": -1,
                              "paymentmethod": "PayPal",
                              "reference": "abcdefg123",
                              "ip": "1.2.3.4",
                              "order_status": 1,
                              "order_details": [
                              {
                                "productId": "12345",
                                "productName": "Product One",
                                "sku": "PROD1",
                                "description": "Product One Description",
                                "net": 2.8405,
                                "tax": 0,
                                "quantity": 1,
                                "options": [
                                {
                                  "choiceId": "12345",
                                  "net": 0,
                                  "tax": 0
                                }
                                ]
                              }
                              ],
                              "postage_audit": {
                                "ruleId": -1,
                                "method": 0,
                                "totalWeight": 0,
                                "net": 0,
                                "tax": 0
                              }
                            }
                          
                        
4. Customer
4.1 List Customers

Use GET /customers/ to retrieve a full list of Customers.

                          
                            {
                              "customers": [
                              {
                                "shopkeeper": 12345,
                                "id": 1234567,
                                "email": "user1@domain.com",
                                "forename": "FirstName",
                                "surname": "Surname",
                                "account_type": 0,
                                "created": "2019-03-26T08:03:18.988Z",
                                "lastlogin": "0001-01-01T00:00:00+00:00",
                                "companyname": "COMPANY_NAME",
                                "deleted": 0,
                                "total_order_count": 1,
                                "total_order_value": 15,
                                "addresses": null,
                                "orders": null,
                                "reviews": null,
                                "messages": null,
                                "newsletter": null,
                                "paypalInfo": null,
                                "mash": null,
                                "notes": null
                              },
                              {
                                "shopkeeper": 12345,
                                "id": 1234568,
                                "email": "#####@#######.###",
                                "forename": "########",
                                "surname": "########",
                                "account_type": 0,
                                "created": "0001-01-01T00:00:00.000Z",
                                "lastlogin": "0001-01-01T00:00:00+00:00",
                                "companyname": "########",
                                "deleted": 0,
                                "total_order_count": 0,
                                "total_order_value": 0,
                                "addresses": null,
                                "orders": null,
                                "reviews": null,
                                "messages": null,
                                "newsletter": null,
                                "paypalInfo": null,
                                "mash": null,
                                "notes": null
                              }
                              ]
                            }
                          
                        

Optional parameters:
limit (int) default 100,
includedeleted (str - true (default) | false)
sort (str - "created" | "createddesc" | "companyname" | "companynamedesc" | "email" | "emaildesc" | "forename" | "forenamedesc" | "surname" | "surnamedesc" | "total_orders" | "total_ordersdesc" | "total_sales" | "total_salesdesc"),

eg. /customers/?limit=10&sort=createddesc&includedeleted=false

4.2 Get Customers

Use GET /customers/{customerID} to retrieve a single Customer.

                          
                            {
                              "shopkeeper": 12345,
                              "id": 1234567,
                              "email": "user@domain.com",
                              "forename": "FirstName",
                              "surname": "Surname",
                              "account_type": 0,
                              "created": "2017-05-22T16:13:34.315Z",
                              "lastlogin": "0001-01-01T00:00:00+00:00",
                              "companyname": null,
                              "deleted": 0,
                              "total_order_count": 1,
                              "total_order_value": 112.99,
                              "addresses": [
                              {
                                "id": 1234567,
                                "tag": null,
                                "country_id": 27,
                                "forename": "FirstName",
                                "surname": "Surname",
                                "primary_billing": false,
                                "primary_delivery": true,
                                "created": "2017-05-22T16:13:34.393+00:00",
                                "city": "City",
                                "address1": "Address Line 1",
                                "region_id": -1,
                                "postcode": "12345",
                                "county": "County",
                                "telephone": "1234567890",
                                "mobile": "",
                                "address2": "Address Line 2",
                                "companyname": "",
                                "deleted": false,
                                "country": "-1",
                                "region": "-1",
                                "lat": "",
                                "lng": "",
                                "formatted_address": ""
                              }
                              ],
                              "orders": null,
                              "reviews": [],
                              "messages": [],
                              "newsletter": [],
                              "paypalInfo": {
                                "id": null,
                                "clientid": null,
                                "customerid": null,
                                "surname": null,
                                "forename": null,
                                "add1": null,
                                "add2": null,
                                "add3": null,
                                "city": null,
                                "county": null,
                                "country": null,
                                "postcode": null,
                                "telephone": null,
                                "orderid": null,
                                "deliverynotes": null,
                                "verified": null,
                                "postcodev2": null
                              },
                              "mash": null,
                              "notes": null
                            }
                          
                        

Optional parameters: None

4.3 Create Customer

Use POST /customers/ to create a Customer.

                          
                            {
                              "email" : "user@domain.com",
                              "forename" : "bob",
                              "surname" : "jim",
                              "companyname": "bob&jim"
                            }
                          
                        

Optional parameters: None

4.4 Update Customer

Use POST /customers/{customerID} to update an existing Customer.

                          
                            {
                              "email" : "user1@domain1.com",
                              "forename" : "Bob",
                              "surname" : "Jim",
                              "companyname": "Bob&Jim"
                            }
                          
                        

Optional parameters: None

4.5 Delete Customer

Use DELETE /customers/{customerID} to update an existing Customer.

Optional parameters: None

5. Samples

PHP
5.1 GET Request

PHP sample to get categories from the API, loop through them, and display them in paragraph tags;

                          
                            <?php
                            $api_key = "YOUR_API_KEY";
                            $url = "https://api.freewebstore.com/category";
                            
                            //Init curl
                            $ch = curl_init();
                            
                            //Set the URL to call
                            curl_setopt($ch, CURLOPT_URL, $url);
                            
                            //Set the API key as a header
                            curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                            "x-api-key:$api_key"
                            ));
                            
                            //Make sure the result is assigned to the variable as a string
                            curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                            
                            //Make the call
                            $output = curl_exec($ch);
                            
                            //Parse the JSON result
                            $result = json_decode($output);
                            
                            //Loop through the category array
                            foreach ($result->categories as $category) {
                              echo "<p>$category->name</p>"; //echo out as HTML
                            }
                            
                            //Close the connection
                            curl_close($ch);
                          
                        
5.2 POST Request

PHP sample to create a new product with the minimum data required;

                          
                            <?php
                            $api_key = "YOUR_API_KEY";
                            $url = "https://api.freewebstore.com/product";
                            
                            $data = json_encode(
                            array(
                            'name' => "My Product (1)",
                            'code' => "MY_PRODUCT_1",
                            'price' => "10.00",
                            'category' => array(
                            'primary' => 1111111
                            )
                            )
                            );
                            
                            //Init curl
                            $ch = curl_init();
                            
                            //Set the URL to call
                            curl_setopt($ch, CURLOPT_URL, $url);
                            
                            //Set the POST data
                            curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
                            
                            //Set the API key as a header
                            curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                            "x-api-key:$api_key"
                            ));
                            
                            //Make sure the result is assigned to the variable as a string
                            curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                            
                            //Make the call
                            $output = curl_exec($ch);
                            
                            //Parse the JSON result
                            $result = json_decode($output);
                            print_r($result);
                            
                            //Close the connection
                            curl_close($ch);
                            
                          
                        
PUT Request

PHP sample to update an existing product;

                          
                            <?php
                            $api_key = "YOUR_API_KEY";
                            $url = "https://api.freewebstore.com/product/11111111";
                            
                            $data = json_encode(
                            array(
                            'name' => "My Product (2)",
                            'code' => "MY_PRODUCT_2",
                            'price' => "10.01",
                            'category' => array(
                            'primary' => 3821636
                            )
                            )
                            );
                            
                            //Init curl
                            $ch = curl_init();
                            
                            //Set the URL to call
                            curl_setopt($ch, CURLOPT_URL, $url);
                            
                            //Set as a PUT request
                            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
                            
                            //Set the POST data
                            curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
                            
                            //Set the API key as a header
                            curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                            "x-api-key:$api_key"
                            ));
                            
                            //Make sure the result is assigned to the variable as a string
                            curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                            
                            //Make the call
                            $output = curl_exec($ch);
                            
                            //Parse the JSON result
                            $result = json_decode($output);
                            print_r($result);
                            
                            //Close the connection
                            curl_close($ch);
                            
                          
                        
DELETE Request

PHP sample to delete an existing customer record

                          
                            <?php
                            $api_key = "YOUR_API_KEY";
                            $url = "https://api.freewebstore.com/customers/1111111";
                            
                            //Init curl
                            $ch = curl_init();
                            
                            //Set the URL to call
                            curl_setopt($ch, CURLOPT_URL, $url);
                            
                            //Set as a DELETE request
                            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
                            
                            //Set the API key as a header
                            curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                            "x-api-key:$api_key"
                            ));
                            
                            //Make sure the result is assigned to the variable as a string
                            curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                            
                            //Make the call
                            $output = curl_exec($ch);
                            
                            //Parse the JSON result
                            $result = json_decode($output);
                            print_r($result);
                            
                            //Close the connection
                            curl_close($ch);
                            
                          
                        

Appendix

Resource and URI Reference
URI Method Resource Operation
/category/ GET Category Retrieves list of categories
/product/?parameter={parameter} GET Product Retrieves list of product IDs. Optional parameters: per_page, sort, sort_order, start, category
/orders/?parameter={parameter} GET Orders Retrieves list of orders. Optional parameters: status, sort, tags, startdate, enddate, offset, fields
/order/{orderID} GET Order Retrieves  order details for single order