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 "code", "price" and "category -> primary" are REQUIRED

                        
                          Request: {
                            "stock_alert_level": -1,
                            "attributes": [],
                            "avg_rating": 0,
                            "name": "Product Name",
                            "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

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