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 |