Sugarcoat API

Sugarcoat: [email protected] License: MIT


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.

Authentication

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.

api_key

Security Scheme Type API Key
Header parameter name: Authorization

api_token

Security Scheme Type bearer

API Keys

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

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

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

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

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

Pagination

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

Response
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

Sorting

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

Filtering

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 =

Includes

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

Authentication

Generate Token

Generates and returns a API Token

Authorizations:

Responses

201

Token generated

get /auth/token
https://api.sugar-coat.io/v1/auth/token

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token":
    {
    }
}

Get Token

Returns a API Token

Authorizations:

Responses

200

Token is Returned

get /auth/token/{token}
https://api.sugar-coat.io/v1/auth/token/{token}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token":
    {
    }
}

Elevate Token

Adds scopes to a token and returns a API Token

Authorizations:
api_key (admin)
Request Body schema: application/json
scopes
required
object

Responses

200

Token is Elevated

post /auth/token/{token}/elevate
https://api.sugar-coat.io/v1/auth/token/{token}/elevate

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scopes":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token":
    {
    }
}

Analytics

Analyics allow you track and report on metrics that matter to your business.

Record analytic

Record an analytic record in the form of an impression or an analytic hit with a redirect.

Authorizations:
query Parameters
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

Responses

201

The analytic was recorded

get /analytics
https://api.sugar-coat.io/v1/analytics

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "analytic":
    {
    }
}

Record analytic

Record an analytic record in the form of an impression or an analytic hit with a redirect.

Authorizations:
Request Body schema: application/json
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

Responses

201

The analytic was recorded

post /analytics
https://api.sugar-coat.io/v1/analytics

Request samples

Content type
application/json
Copy
Expand all Collapse all
{}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "analytic":
    {
    }
}

Baskets

Manage the baskets that exist on your store with the ability to analyse and report on these baskets.

Create a Basket

Create a basket

Authorizations:
Request Body schema: application/json
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

Responses

201

Created basket is returned

post /baskets
https://api.sugar-coat.io/v1/baskets

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "products":
    [
    ],
  • "delivery_type_id": 1
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "basket":
    {