Enstore API Documentation

• Introduction
• Constants
• Settings
• Sales resources
  • Products
  • Orders
  • Customers
  • Payment Methods
  • Shipping Methods
• Webstore resources
  • Menus
  • Templates
  • Pages

Introduction Back to top

Some examples of what you can do with the API are:

• Integrate an existing retail management or accounting application with Enstore, similar to how Checkout integrates with Enstore.
• Build your own custom web store front-end, ranging from a website to a full-blown desktop application.
• Create your own application to manage Enstore, similar to the Enstore Admin web-app.
• Create short scripts to programmatically control Enstore features.

Intended Audience

This document is intended for anyone who wants to understand how to use the Enstore API. Its purpose is to make you familiar with the architecture of the Enstore API. After reading you'll be able to build your own custom solution that can fetch, update and delete resources.

Requirements

The things you need before you can get started:

• Knowledge of a programming language that lets you parse JSON and issue HTTP requests.
• Basic knowledge of the GET, PUT, POST and DELETE requests in HTTP, as well as HTTP's and REST's concept of a resource.
• An Enstore API account. To get one, sign up for a new store and join the early access program at the top of this page.

Transport Protocol

The Enstore API uses the HTTP protocol for default transport and the HTTPS protocol for secure transport.

Endpoint URIs Back to top

URI Syntax

The Enstore API works with uniquely identifiable resources. Every resource is identified by it's universal resource locator (url). The following url is the default base url to identify which store and API version you are using. Resources in the API can be identified in two ways; 1) a single specific resource and 2) a collection of resources.

There is a difference between a url with and without a trailing slash. The Enstore API does not support urls with a trailing slash.

Parameters

Most resources take optional GET parameters. These can used to for example filter or sort a resource. Specific parameters are described in the resource documentation.

Methods

HTTP GET is used to retrieve resources, DELETE is used to delete resources and PUT is used for requests that add a new or modify an existing resource.

A resource does not have to implement every HTTP method supported. For example: The settings resource cannot be deleted. Requesting a resource using an unsupported method will result in a 400 error. Consult resource specific documentation to learn which HTTP methods are supported by that resource.

Getting the response Back to top

Response types

All successful requests, except PUT requests, will result in a '200 OK' response. A PUT request will result in a '201 Created' response. The type of unsuccessful responses depends on the type of error.

An error made by the user will return 400 Bad Response, 401 Unauthorized or 404 Not Found. The response body will always contain a detailed description of the error. The response body matches the format supplied with the FORMAT parameter. A user error response could look like:

HTTP/1.1 400 Bad Request
{
    errorCode1: errorMessage,
    errorCode2: errorMessage
}

Note: These errors are meant for debugging purposes. It is advised to not display these errors to your end-users directly.

The Enstore API returns a 500 Internal Server Error response when a request cannot be handled. In most cases this means that the URI is malformed. The body for an Internal Server Error response contains a general error string.

Constants Back to top

Data Types

Data Format

Enstore supports different data formats for text data and binary data (like images). The Enstore API uses UTF-8 encoding for text and prefers UNIX-style LF (U+000A) linebreaks.

JSON

JSON, short for JavaScript Object Notation is a lightweight computer data interchange format. It is a text-based, human-readable format for representing simple data structures and associative arrays (called objects). The JSON format is often used for serialization and transmitting structured data over a network connection. Its main application is in Ajax web application programming, where it serves as an alternative to the XML format.

You can learn more about JSON at the Wikipedia page, or at it's official homepage. There are JSON implementations available in many languages, and you can check syntax with JSON Lint.

Because JSON only supports primitive data types by default, Enstore handles more advanced data types by expressing them in simple data types.

JSONP

JSONP (or padded-JSON) is a format that makes it possible to use it through ajax directly in a web browser, even if the request is cross domain. The only difference in formatting is that the data is wrapped in a callback function for security. By default this is callback, but it can be set by setting the GET callback variable in a request. For example: GET /[store-handle]/api/v2/products.jsonp?callback=customFunction.

Images

Enstore supports the most popular image formats on the web. Image formats are detected based on their extension. All extensions will be converted to lower case.

Settings Resource Back to top

URL Endpoints

Data Structure

Settings can contain specific application settings under the key applications

Products Resource Back to top

URL Endpoints

URL Parameters

Although you can only page through the results by at most 80 items at a time, you can get the total count of items for the given query by sending the exact same GET parameters to /[store-handle]/api/v2/webstore/products/count.json. For example /[store-handle]/api/v2/webstore/products/count.json will return the total count for all products, and /[store-handle]/api/v2/webstore/products/count.json?tags=bike will return the count for all products with tag bike. Counting does not work in combination with revision and query parameters.

Data Structure

Products describe items in your webstore including names, pricing description etc.

Product Variations Resource Back to top

URL Endpoints

Data Structure

Data structure of variation products is identical to regular products.

Orders Resource Back to top

URL Endpoints

URL Parameters

Data Structure

Orders are documents that connect ordered goods to customers.

Customers Resource Back to top

URL Endpoints

URL Parameters

Although you can only page through the results by at most 80 items at a time, you can get the total count of items for the given query by sending the exact same GET parameters to /[store-handle]/api/v2/webstore/customers/count.json. For example /[store-handle]/api/v2/webstore/customers/count.json will return the total count for all customers, and /[store-handle]/api/v2/webstore/customers/count.json?tags=wholesale will return the count for all products with tag wholesale. Counting does not work in combination with revision and query parameters.

Data Structure

Customers are contact records that hold name, address and shipping information. They can be organized with tags. Orders hold immutable copies of customer records. They can only be sorted on lastName.

Payment Methods Resource Back to top

URL Endpoints

Data Structure

Shipping Methods Resource Back to top

URL Endpoints

Data Structure

Price Ranges

Custom shipping methods can be weight-based or price-based, determined by the carrierCodes "weight" or "price". If it's set to either one of these, Enstore will look up the shipping price for a product line by either the weight or price.

Menus Resource Back to top

URL Endpoints

Data Structure

The menus in the menu resource are named collections of structured menus. They can go multiple levels deep, but please note that some of the templates only render the menus up to two levels of depth. The correct urls for the menu items will be generated when rendering the template, for example the url "tags:man,bikes" could become /store-name/shop/browse/man,bikes/1.

Templates Resource Back to top

URL Endpoints

Data Structure

Template resources hold information about their pages and assets and the author. Templates are used for the visual representation of your webstore.

Template Assets Resource Back to top

URL Endpoints

Data Structure

Templates assets can be sent the raw file data of the asset. Supported asset formats are: png, jpg, gif, css, js, htc. Format is detected based on file extension.

Template Pages Resource Back to top

URL Endpoints

Data Structure

Templates pages can be sent the raw template data. The base format is html with template logic. For more information about template capabilities see the custom template documentation.

Pages Resource Back to top

URL Endpoints

Data Structure

If the url /store-name/shop/page/agreement would be requested, a page would be looked up by the handle agreement and rendered using the template defined by the page property, passing the content dictionary to the template context.