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
                      }
                      ]
                    }
                  

Webhooks

Create Webhooks

Webhooks can be managed via the API section of your freewebstore control panel. Simply add a new webhook, select the event you wish to subscribe to (more events coming) and provide the URL you wish us to notify. All data will be posted in JSON format.

You can view the active webhooks along with a log of recent webhook notifications and their outcome. There is also an option to resend specific webhook events.

Example
Example Webhook

Here is an example post for a NewOrder Webhook.

                
                {
		"id": "VzMbt3C",
		"orderNo": "5454",
		"date": "2024-01-24T22:00:53.272Z",
		"localTime": "2024-01-24T22:00:52.837Z",
		"testMode": false,
		"customerId": "123456789",
		"customerName": "David Ward",
		"customerEmail": "wardy@outlook.com",
		"account_type": 0,
		"address": "Cardigan, Ceredigion, , SA43 1AF, UK",
		"lat": "52.090306",
		"lng": "-4.65674",
		"country": "United Kingdom",
		"state": "Ceredigion",
		"total": 15,
		"currency": "GBP",
		"checkout": "PPCPCARD",
		"cartId": "dae0aed6-2866-477c-8664-53a4833b90a5-383483",
		"paybyotherid": null,
		"items": [
			{
				"productId": "15604963",
				"productName": "Membership - for renewals and new members.",
				"variantId": "x7r43",
				"variantName": "Gold Membership",
				"sku": "Memb",
				"qty": 1,
				"options": [
					"Choose type of Membership : Electronic (download PDF)"
				]
			}
		]
	}
                
                
Errors / Retries
Errors and retries

Any errors such as network problems will be re-attempted automatically. There will be an exponential backoff of 5 attempts before the notification is marked as failed.

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": {
						   "found": 10,
						   "nextToken": "20330401", //pass in URL to page through the results
						   "list": [
							{
								"id": "8329129",
								"productType": "physical",
								"sku": "XF2702004",
								"name": "Grand Prix .177 used TT Racecar",
								"abstract": "Short description here - plaintext only. 100 to 1500 characters",
								"created": "2020-02-27T13:37:10.405Z",
								"updated": "2023-06-28T13:15:08.999Z",
								"condition": "used",
								"image": {
									"filename": "1582810553015_img_20200227_132824.jpg"
								},
								"price": 25,
								"categoryId": "4666041",
								"pricing": {
									"baseprice": 25
								},
								"brand": "Brocock",
								"published": true,
								"locked": false,
								"score": 85,
								"sold": 1,
								"stock": 0
							},
							...
							]								
                        }
                      
                    

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

                      
                        {
  "core": {
    "id": "45258783",
    "productType": "physical",
    "sku": "IFJoAKW",
    "name": "T-Shirt",
    "abstract": "Colourful t-shirts to brighten the day of everyone in your office. Dazzle new customers with your go-to wardrobe item for the summer. Shine on! My money don't jiggle, jiggle. It folds honey!",
    "created": "2023-04-05T14:45:18.694Z",
    "updated": "2023-06-21T13:35:25.05Z",
    "condition": "new",
    "image": {
      "filename": "red_1680705873605.jpg"
    },
    "price": 6.99,
    "categoryId": "272237",
    "pricing": {
      "baseprice": 9.99,
      "discount": {
        "type": "price",
        "value": 6.99
      }
    },
    "url": "t-shirtv1",
    "seo": {
      "title": "T-Shirt",
      "desc": "Colourful t-shirts to brighten the day of everyone in your office. Dazzle new customers with your go-to wardrobe item for the summer. Shine on!",
      "keywords": [
        "T-Shirt",
        "T-Shirts"
      ]
    },
    "brand": "Bond Street",
    "published": true,
    "featured": true,
    "weight": {
      "value": 80.0,
      "weightType": "oz"
    },
    "width": {
      "value": 0.0,
      "lengthType": "mm"
    },
    "height": {
      "value": 0.0,
      "lengthType": "mm"
    },
    "depth": {
      "value": 0.0,
      "lengthType": "mm"
    },
    "stock": 40,
    "score": 130.0,
    "variant_count": 12,
    "sold": 0,
    "offer_type": "price",
    "minQty": 1,
    "maxQty": -1,
    "countryOfOrigin": "China",
    "randomId": "is_gPPfOD"
  },
  "variants": [
    {
      "uvid": "720ZxR",
      "key": "Color:Green;#Size:Large;",
      "sku": "g33qH3t",
      "image": {
        "filename": "green_1680705873574.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "g"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 8,
      "label": "Color:Green;#Size:Large;"
    },
    {
      "uvid": "KX9jTq",
      "key": "Color:Green;#Size:Medium;",
      "sku": "PybJbzr",
      "image": {
        "filename": "green_1680705873574.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "g"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 7,
      "label": "Color:Green;#Size:Medium;"
    },
    {
      "uvid": "ssbwww",
      "key": "Color:Green;#Size:Small;",
      "sku": "U69Hocp",
      "image": {
        "filename": "green_1680705873574.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "oz"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 6,
      "label": "Color:Green;#Size:Small;"
    },
    {
      "uvid": "qgim2U",
      "key": "Color:Purple;#Size:Large;",
      "sku": "qHR97zG",
      "image": {
        "filename": "purple_1680705873599.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "oz"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 5,
      "label": "Color:Purple;#Size:Large;"
    },
    {
      "uvid": "OVjKAc",
      "key": "Color:Purple;#Size:Medium;",
      "sku": "9mGVTAd",
      "image": {
        "filename": "purple_1680705873599.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "oz"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 4,
      "label": "Color:Purple;#Size:Medium;"
    },
    {
      "uvid": "IRfGSJ",
      "key": "Color:Purple;#Size:Small;",
      "sku": "Pk0xiTd",
      "image": {
        "filename": "purple_1680705873599.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "oz"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 3,
      "label": "Color:Purple;#Size:Small;"
    },
    {
      "uvid": "xJdzV7",
      "key": "Color:Red;#Size:Large;",
      "sku": "v3wW5Cj",
      "image": {
        "filename": "red_1680705873605.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "g"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 2,
      "label": "Color:Red;#Size:Large;"
    },
    {
      "uvid": "sUN4Go",
      "key": "Color:Red;#Size:Medium;",
      "sku": "7HMmN3K",
      "weight": {
        "value": 0.0,
        "weightType": "g"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 1,
      "label": "Color:Red;#Size:Medium;"
    },
    {
      "uvid": "enqXYH",
      "key": "Color:Red;#Size:Small;",
      "sku": "IPHupPD",
      "weight": {
        "value": 0.0,
        "weightType": "oz"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 0,
      "label": "Color:Red;#Size:Small;"
    },
    {
      "uvid": "vCzXPf",
      "key": "Color:Yellow;#Size:Large;",
      "sku": "5wy40oV",
      "image": {
        "filename": "yellow_1680705873612.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "g"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "price": 2.5,
      "stock": 5,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 11,
      "label": "Color:Yellow;#Size:Large;"
    },
    {
      "uvid": "CojZbF",
      "key": "Color:Yellow;#Size:Medium;",
      "sku": "LFNg6ml",
      "image": {
        "filename": "yellow_1680705873612.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "g"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "price": 2.5,
      "stock": 5,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 10,
      "label": "Color:Yellow;#Size:Medium;"
    },
    {
      "uvid": "plzzhz",
      "key": "Color:Yellow;#Size:Small;",
      "sku": "nS54tJM",
      "image": {
        "filename": "yellow_1680705873612.jpg"
      },
      "weight": {
        "value": 0.0,
        "weightType": "oz"
      },
      "width": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "height": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "depth": {
        "value": 0.0,
        "lengthType": "mm"
      },
      "price": 2.5,
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 9,
      "label": "Color:Yellow;#Size:Small;"
    }
  ],
  "extraimages": [
    {
      "filename": "purple_1680705873599.jpg",
      "alt": "null"
    },
    {
      "filename": "green_1680705873574.jpg",
      "alt": ""
    },
    {
      "filename": "yellow_1680705873612.jpg",
      "alt": ""
    }
  ],
  "extracategories": [
    {
      "categoryId": "853431"
    }
  ],
  "google": {
    "google_eligible": 1
  }
}
                      
                    
2.3 Create Product

Use POST to /product/ to create a new Product

Category can now be set at Create time. This slows the call down if categories need to be created on the fly. If you pass a category at the top level then omit it from core.categoryId or you will get an error. If you need to use ">" in a category name then simply encode it to ">"

                        
{
  "description" : "Rich text HTML content here",
  "category": "TopLevel>Level1>Leve2",
  "core": {
    "productType": "physical",
    "sku": "IFJoAKW",
    "name": "T-Shirt",
    "abstract": "Colourful t-shirts to brighten the day of everyone in your office. Dazzle new customers with your go-to wardrobe item for the summer. Shine on! My money don't jiggle, jiggle. It folds honey!",
    "created": "2023-04-05T14:45:18.694Z",
    "updated": "2023-06-21T13:35:25.05Z",
    "condition": "new",
    "image": {
      "filename": "red_1680705873605.jpg"
    },
    "price": 6.99,
    "categoryId": "272237",
    "pricing": {
      "baseprice": 9.99,
      "discount": {
        "type": "price",
        "value": 6.99
      }
    },
    "url": "t-shirtv1",
    "seo": {
      "title": "T-Shirt",
      "desc": "Colourful t-shirts to brighten the day of everyone in your office. Dazzle new customers with your go-to wardrobe item for the summer. Shine on!",
      "keywords": [
        "T-Shirt",
        "T-Shirts"
      ]
    },
    "brand": "Bond Street",
    "published": true,
    "featured": true,
    "stock": 40,
    "score": 130.0,
    "variant_count": 12,
    "sold": 0,
    "offer_type": "price",
    "minQty": 1,
    "maxQty": -1,
    "countryOfOrigin": "China",
    "randomId": "is_gPPfOD"
  },
  "variants": [
    {
      "key": "Color:Green;#Size:Large;",
      "sku": "g33qH3t",
      "image": {
        "filename": "green_1680705873574.jpg"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 8,
      "label": "Color:Green;#Size:Large;"
    },
    {
      "key": "Color:Green;#Size:Medium;",
      "sku": "PybJbzr",
      "image": {
        "filename": "green_1680705873574.jpg"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 7,
      "label": "Color:Green;#Size:Medium;"
    },
    {
      "key": "Color:Green;#Size:Small;",
      "sku": "U69Hocp",
      "image": {
        "filename": "green_1680705873574.jpg"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 6,
      "label": "Color:Green;#Size:Small;"
    },
    {
      "key": "Color:Purple;#Size:Large;",
      "sku": "qHR97zG",
      "image": {
        "filename": "purple_1680705873599.jpg"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 5,
      "label": "Color:Purple;#Size:Large;"
    },
    {
      "key": "Color:Purple;#Size:Medium;",
      "sku": "9mGVTAd",
      "image": {
        "filename": "purple_1680705873599.jpg"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 4,
      "label": "Color:Purple;#Size:Medium;"
    },
    {
      "key": "Color:Purple;#Size:Small;",
      "sku": "Pk0xiTd",
      "image": {
        "filename": "purple_1680705873599.jpg"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 3,
      "label": "Color:Purple;#Size:Small;"
    },
    {
      "key": "Color:Red;#Size:Large;",
      "sku": "v3wW5Cj",
      "image": {
        "filename": "red_1680705873605.jpg"
      },
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 2,
      "label": "Color:Red;#Size:Large;"
    },
    {
      "key": "Color:Red;#Size:Medium;",
      "sku": "7HMmN3K",
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 1,
      "label": "Color:Red;#Size:Medium;"
    },
    {
      "key": "Color:Red;#Size:Small;",
      "sku": "IPHupPD",
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 0,
      "label": "Color:Red;#Size:Small;"
    },
    {
      "key": "Color:Yellow;#Size:Large;",
      "sku": "5wy40oV",
      "image": {
        "filename": "yellow_1680705873612.jpg"
      },
      "price": 2.5,
      "stock": 5,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 11,
      "label": "Color:Yellow;#Size:Large;"
    },
    {
      "key": "Color:Yellow;#Size:Medium;",
      "sku": "LFNg6ml",
      "image": {
        "filename": "yellow_1680705873612.jpg"
      },
      "price": 2.5,
      "stock": 5,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 10,
      "label": "Color:Yellow;#Size:Medium;"
    },
    {
      "key": "Color:Yellow;#Size:Small;",
      "sku": "nS54tJM",
      "image": {
        "filename": "yellow_1680705873612.jpg"
      },
      "price": 2.5,
      "stock": 3,
      "low_stock_level": 0,
      "condition": "New",
      "sequence": 9,
      "label": "Color:Yellow;#Size:Small;"
    }
  ],
  "extraimages": [
    {
      "filename": "purple_1680705873599.jpg",
      "alt": "null"
    },
    {
      "filename": "green_1680705873574.jpg",
      "alt": ""
    },
    {
      "filename": "yellow_1680705873612.jpg",
      "alt": ""
    }
  ],
  "extracategories": [
    {
      "categoryId": "853431"
    }
  ]
  }
                        
                      
                        
                          200: {
                            "message":"Product Created",
                            "productId":11111111
                          }
                          
                          400: {
                            "errors":[{
                              "message":"The property [price] does not exist"
                            },
							...
                            ],
                            "type":"ProductValidationException",
                            "count":2
                          }
                          
                          403: {
                            "Forbidden - "
                          }
                        
                      
2.4 Update Product

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

If you pass a new category path then it will slow the call down a little.

You can pass in a new description here also

All Fields Are Optional. Send just the data you wish to change

If you wish to update a collection such as VARIANTS, RELATEDPRODUCTS, ADDITIONALIMAGES then you must pass ALL items of the collection in the update call.

                        
                          Request: {
                             "category" : "Boots>Leather>Motorcycle"
                             "description": "rich text updated here",
                             "core" : {  "stock" : 125, "sku" : "ABC001"  }
                          }
                        
                      
                        
                          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"|"canceled"|"cancelled"), 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);
                            
                            if (curl_error($ch)) {
								echo curl_error($ch);
							} else {
								//Parse the JSON result
								$result = json_decode($output);

								echo "Store Product Categories 

"; foreach ($result->categories as $category) { echo $category->{'id'}; //category id echo " -> "; echo $category->{'name'}; //category name echo "
"; } } //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(
							'core' => array(
								'name' => "My Product API Test",
								'sku' => "API_TEST",
								'stock' => "250",
								'image' =>  array(
									'filename' => "my_product_image.png",
								),
								'pricing' =>  array(
									'baseprice' => "9.00",
								)
								)
							)
							);
                            
                            //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(
							'core' => array(
								'stock' => 113,
								'image' =>  array(
									'filename' => "myproductimage2.png",
								),
								'pricing' =>  array(
									'baseprice' => "13.00",
								)
								)
							)
							);
                            
                            //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
Freewebstore uses cookies to provide necessary site functionality and improve your experience. By using our website, you agree to our terms & conditions and privacy policy.
OK