Sugarcoat is a flexible and powerful eCommerce solution that empowers businesses to take control of their sales channels. To find out more, head over to https://www.sugar-coat.io.
Most of the examples found in this API documentation are used in the Sugar Factory demo store which can be found at https://sugarfactory.sugar-coat.io.
Where authentication is required, API calls are authenticated using the Authorization
header. The Sugarcoat API supports 2 forms of authentication; API Keys and API Tokens.
Within the API Settings area of your console, you should have access to a Private Key
and a Public Key
. Both keys can be used within the Authorization
header to make API requests however each key has different persmissions and access scopes within the API.
If for any reason your API Keys are compromised, you should regenerate new ones via the API Settings and update your integration.
Private Keys have complete access to the API and therefore MUST be used over a secure connection and MUST NEVER be shared or visible in your application.
This can be used for server-to-server integrations between your application and the Sugarcoat API.
Public Keys can only access public API endpoints and will result in a 403
status code response if used to request data outside of that scope.
This can be used for client-to-server integrations between you application and the Sugarcoat API.
API Tokens give temporary access to API endpoints and can be generated via the token endpoint using either the, Private or Public API key. By default, API Tokens can only access public endpoints (the same as Public Keys) however they can be elevated to give permissions to certain resources or scopes e.g. a User.
NOTE: If an API Token is used to authenticate a login request, if it is successful then the token will be automatically be elevated to the user so the token can be used for future User actions.
Errors returned from the Sugarcoat API aim to be consistent and give the maximum flexability to the integrators to be able to handle them effectively. Any errors returned with be in an errors
node as an array of objects in the following format:
Response
Property | Type | Description |
---|---|---|
type | string | A specific code to the type of error which can be handled distinctly during integration. A list of potential error codes can be obtained via https://api.sugar-coat.io/v1/error-codes. |
code | integer | The http status code |
message | string | A human readable message of the error |
property | string | This is an optional key which will be returned in the case of input or validation errors |
The Sugarcoat API utilises page-based pagination thoughout and when calling list endpoints, the fields count
, current_page
,last_page
and interval
will be returned in the response allowing you to navigate through pages with the simple querystring filtering of ?page=<page_number>
, for example: /orders?page=3
. You can also pass in the pagination_interval
parameter for the items per page, for example /orders?page=3&pagination_interval=5
. When no more pages are available, the next_page
key will return null
.
Request
Parameter | Type | Description |
---|---|---|
page | string | integer | The page to retrieve |
pagination_interval | string | integer | The intervals between each page i.e. the size of each page |
Property | Type | Description |
---|---|---|
count | integer | The total count of records across all pages of results |
current_page | integer | The current page number of records returned |
last_page | integer | The last page of results returned |
interval | integer | The number of records returned per page |
Endpoints which are filterable or paginated can be sorted by an array of values. These are provided in the format products?sort[0][property]=name&sort[0][direction]=asc&sort[1][property]=created_at&sort[1][direction]=desc
Request
Parameter | Type | Description |
---|---|---|
sort[0][property] | string | The name of the property with which to sort the records |
sort[0][direction] | asc | desc | The direction with which to sort the records property defaulting to asc |
Endpoints which return collections of information can be filtered further by the properties returned. These are provided in the format products?filters[0][property]=name&filters[0][value]=test&filters[0][operator]=LIKE
Request
Parameter | Type | Description |
---|---|---|
filters[0][property] | string | The name of the property with which to filter the records |
filters[0][value] | string | array | integer | The value of the property with which to filter the records |
filters[0][operator] | = | >= | <= | where | whereIn | whereBetween | whereAnd | LIKE | The operator to apply to the value to filter the records defaulting to = |
Listing endpoints may return a compact response for a given collection to save on data transfer and increase performance. Further relational data can be obtained either from a subsequest request to that individual resource or by including additional the relationships in the listing response. These relationships can be added via the include
parameter with a comma seperate set of values e.g. products?include=tags,categoryOptions,images
{- "token": {
- "api_token": "abcdefg-hijklmno",
- "expiration": "2018-06-21 00:00:00"
}
}
Adds scopes to a token and returns a API Token
admin
) scopes required | object |
Token is Elevated
{- "scopes": {
- "user_id": 123
}
}
{- "token": {
- "api_token": "abcdefg-hijklmno",
- "expiration": "2018-06-21 00:00:00"
}
}
Record an analytic record in the form of an impression or an analytic hit with a redirect.
product_id required | integer <int32> The Product ID to log the analytic against |
origin | string The origin URL from which the analytic was created |
destination | string The optional URL to redirect the user to after recording the analytic |
type | string Enum: "standard" "product" "referral" The type of analytic |
The analytic was recorded
{- "analytic": {
- "id": 1,
- "product_id": 1,
- "type": "product",
- "ip_address": "127.0.0.1",
- "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
- "query_string": "string",
- "redirect": true,
- "redirect_status_code": 302
}
}
Record an analytic record in the form of an impression or an analytic hit with a redirect.
product_id required | integer <int32> The Product ID to log the analytic against |
origin | string The origin URL from which the analytic was created |
destination | string The origin URL from which the analytic was created |
type | string Enum: "standard" "product" "referral" The type of analytic |
The analytic was recorded
{- "product_id": 32,
- "type": "standard"
}
{- "analytic": {
- "id": 1,
- "product_id": 1,
- "type": "product",
- "ip_address": "127.0.0.1",
- "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
- "query_string": "string",
- "redirect": true,
- "redirect_status_code": 302
}
}
Manage the baskets that exist on your store with the ability to analyse and report on these baskets.
Create a basket
products | Array of objects |
delivery_type_id | integer <int32> Delivery type chosen for the basket, which takes priority over any delivery chosen at a product level |
Created basket is returned
{- "products": [
- {
- "product_id": 32,
- "quantity": 4,
- "delivery_type_id": 1
}
], - "delivery_type_id": 1
}
{- "basket": {
- "basket_reference": "c4ca4238a0b923820dcc509a6f75849b",
- "products": [
- {
- "quantity": 4,
- "product": {
- "id": 1,
- "title": "Haribo Terrific Turtles",
- "name": "Haribo Terrific Turtles",
- "slug": "haribo-terrific-turtles",
- "description": "The famous bubblegum flavoured terrific turtles.",
- "price": 7.49,
- "discount_price": 5.49,
- "code": "SF-001",
- "images": [
- {
- "name": "Haribo Terrific Turtle",
- "description": "Description of the image",
- "file_name": "image.jpg",
- "storage_name": "366b4f229583b1c7a48ed12df9e51bbd8da342fe",
- "mime_type": "image/jpeg",
- "size": "47422",
- "extension": "jpg",
- "iv": "3kFTvsq5B2HnpyHgvjHvbfRE9V/N3tfW",
}
], - "inventory": 0,
- "is_visible": true,
- "sku": "HAR-TT-123",
- "thumbnail": {
- "name": "Haribo Terrific Turtle",
- "description": "Description of the image",
- "file_name": "image.jpg",
- "storage_name": "366b4f229583b1c7a48ed12df9e51bbd8da342fe",
- "mime_type": "image/jpeg",
- "size": "47422",
- "extension": "jpg",
- "iv": "3kFTvsq5B2HnpyHgvjHvbfRE9V/N3tfW",
}, - "track_inventory": true,
- "weighting": 0,
- "delivery_types": [
- {
- "id": 1,
- "cost": 9.99,
- "name": "Mainland UK",
- "description": "Royal Mail 1st class.",
- "duration_lower": 2,
- "duration_upper": 5
}
], - "category_options": [
- {
- "id": 1,
- "name": "Bubblegum",
- "value": "bubblegum",
- "description": "Bubblegum flavour",
- "category": {
- "id": 1,
- "name": "Flavour",
- "title": "Flavour",
- "slug": "flavour",
- "description": "Choose your flavour...",
- "is_visible": true
}, - "thumbnail": {
- "name": "Haribo Terrific Turtle",
- "description": "Description of the image",
- "file_name": "image.jpg",
- "storage_name": "366b4f229583b1c7a48ed12df9e51bbd8da342fe",
- "mime_type": "image/jpeg",