Warning: This documentation describes the API of a Beta version of sellmate.com, the API may change in an incompatible way before the final release of Sellmate.

Overview

The Sellmate HTTP API follows the common REST API principles, supports JSON data format (application/json content-type) and all 4 HTTP verbs (GET/POST/PUT/DELETE) in a way consistent with the HTTP protocol and REST API best practices. Each resource (e.g. Products, Collections, Orders) has its own URL scheme and is manipulated in isolation.

The Sellmate REST API is implemented in JSON format for all 4 verbs (GET/POST/PUT/DELETE). Each resource (e.g. Products, Collections, Orders) has its own URL scheme and is manipulated in isolation.

We provide a convenient testing tool to work with both Auth and API endpoints to simplify the debugging of API usage:
REST Console

HTTP Verbs

The general meaning of HTTP verbs for Sellmate API is:

  • GET - Get a resource or a list of resources
  • DELETE - Delete existing resource
  • POST - Create a new resource
  • PUT - Change/update existing resource

Authentication & Authorization

Sellmate REST API uses OAuth2 flow to provide authentication and authorization. The initial OAuth2 exchange is done over SSL via the auth URL (https://auth.sellmate.com), subsequent REST API calls are done over plain http (http://api.sellmate.com) and need to contain an

"Authorization": "Mac XXXXXXXXXXX"
HTTP header. Sellmate API uses combination of http protocol + one time calculated Mac tokens to protect against abuse.

Before you can start using the REST API, you will need to finish couple registration steps:

  • Signup for a Developer Account on the Developer Signup page and log in.
  • Create an Application, which will provide you with Client ID and Client Secret that uniquely identify your application, and give you the general ability to make the REST API calls.
  • (optionally) Install the Application for a specific Shop. This will enable you client/application to access data in a specific shop. If you are just getting started with your app, just use the Install button on top of your Application edit page in the Developer Center, and install the app for the Sandbox (sample store that comes with every Developer account). If you do not install the app, the OAuth2 authentication flow will contain the selection of the shop to allow the access to.

Here are the steps needed for obtaining the necessary credentials to make the calls to the REST API:

1

Request an Authorization Grant code by directing the user to the following URL (link in a browser app or embedded WebView for mobile devices):

https://auth.sellmate.com/oauth2/auth?response_type=code&client_id=1234

Attribute Required Example value Description
response_type x code Response type must be code or token for Implicit Grant (see below).
client_id x 1234 The Id of the Application.
redirect_uri o http://example.com/callback The redirect URI registered with your Application. If provided, it must match the one registered.
shop o sample-shop The id of the shop that you're trying to access. If not provided, a prompt will ask the user to select one of his shops during the OAuth process (if he has more then one).
state --- xyz An opaque value used by the client to maintain state between the request and the callback. The authorization server includes this value when redirecting the user-agent back to the client.

The user is asked to authenticate and select a store to access and the result is a call to the registered redirect URI like this:

http://example.com/callback?code=QF1r5biAVz&state=xyz&shop=sample-shop

where the code parameter is the Authorization grant code and the shop parameter the handle of the selected shop.

Note: The Authorization Grant expires after 5min and becomes invalid once used (requested an Access Token with it).
2

Request an Access and Refresh tokens by issuing a POST request to the token endpoint

https://auth.sellmate.com/oauth2/token

Header must contain an Authorization, calculated from your Client Id and Client Secret, and Content-Type such as:

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
                      
Content-Type: application/x-www-form-urlencoded

Example Java code to calculate the authorization key value:

String auth_header = "Basic " + new String(Base64.encodeBase64((client_id+":"+client_secret).getBytes()));

Body payload comes in 2 variants:

  1. When requesting a new access + refresh tokens:


    grant_type=authorization_code&code={authorization-grant-code}&shop={shop-handle}&redirect_uri={redirect-uri}

    Attribute Required Example value Description
    grant_type x authorization_code It must be set to authorization_code .
    code x SplxlOBeZQQYbYS6WxSbIA The The Authorization Grant Code received from the authorization server.
    shop x sample-shop The id of the shop that you're trying to access.
    redirect_uri x http://example.com/callback The redirect URI registered with your Application.
  2. When requesting a new access token, using the refresh token:


    grant_type=refresh_token&refresh_token={refresh-token}&shop={shop-handle}&redirect_uri={redirect-uri}

    Attribute Required Example value Description
    grant_type x refresh_token It must be set to refresh_token .
    refresh_token x P4xv2UOgfJTxQcTBeZyF05moNPt2VN The The Refresh Token initially received with the first Token Request.
    shop x sample-shop The id of the shop that you're trying to access.
    redirect_uri x http://example.com/callback The redirect URI registered with your Application.

Response is a JSON which contains all the necessary data to calculate the Mac tokens to use in the next step to access the REST endpoints:

{
    "mac_algorithm": "hmac-sha-256",
    "mac_key": "B5y5Rah4H4GqPCThWY1p",
    "expires_in": 3600,
    "token_type": "mac",
    "refresh_token": "P4xv2UOgfJTxQcTBeZyF05moNPt2VN",
    "access_token": "H2kgGYmN6Hylj3F0XKvjUYdB5m4SQA"
}
Note: The Access Token expires after 1h from the time the response was generated.
3

Make a REST Call by issuing a GET/POST/PUT/DELETE request to

http://api.sellmate.com/<shop-handle>/rest/<resource>

Each HTTP request to the REST endpoints needs to include a HTTP Authorization Header and a Content-Type such as:

Authorization: Mac id=ksynNsJ67xNs3BB8vgIlXl65qnhMwu,ts=1343842942,nonce=LgLZugNat3Qt,mac=B+BsVY7wU0rh4Lk3p/mWaygAoK5GmZWW+jC7UGgAed8="
Content-Type: application/json

The Mac token has the following format:

Mac id={access_token},
ts={timestamp in sec (unix epoch time)},
nonce={a random alphanumeric string},
mac={Base64 encoded result of Mac algorithm applied on a normalized encoded string}

The normalized encoded string is built this way:

timestamp\n
nonce\n
method\n
target_url\n
host\n
port\n
\n

The value is calculated from the credentials obtained in the previous step

Here is a sample Java code to calculate the Mac token from the credentials:

Show code
import java.net.URL;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Date;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Base64;
import org.apache.commons.lang.RandomStringUtils;

public class SellmateClient {
  private final static String MAC_ALGORITHM = "HmacSHA256";

  public static void main (String[] args) {

  String mac_key = ""; // {mac_key};
  String access_token = ""; // {access_token};
  String requestURL = ""; // {requestURL to rest resource};
  String method = ""; // {GET,POST,PUT,DELETE};

  // Get the timestamp in seconds
  Long timestamp = Long.valueOf(new Date().getTime() / 1000);

  // Set port
  URL targetURL = new URL(requestURL);
  int port = 80;
  if (targetURL.getPort() != -1)
  	port = targetURL.getPort();

  // Define a random nonce
  String nonce = RandomStringUtils.randomAlphanumeric(12);

  // Create the normalized string:
  // timestamp\n
  // nonce\n
  // method\n
  // target_url\n
  // host\n
  // port\n
  // \n
  StringBuffer normalized = new StringBuffer();
  normalized.append(timestamp).append("\n").append(nonce).append('\n').append(method).append('\n')
  	.append(targetURL.getPath()).append('\n').append(targetURL.getHost()).append('\n').append(port)
  	.append("\n");

  // Create the request mac
  SecretKeySpec signingKey = new SecretKeySpec(mac_key.getBytes(), MAC_ALGORITHM);
  String mac_string = "";
  try {
  	Mac mac = Mac.getInstance(MAC_ALGORITHM);
  	mac.init(signingKey);
  	byte[] rawHmac = mac.doFinal(normalized.toString().getBytes());
  	mac_string = Base64.encodeBase64String(rawHmac);
  } catch (NoSuchAlgorithmException e) {
  	e.printStackTrace();
  } catch (InvalidKeyException e) {
  	e.printStackTrace();
  }

  // Build the MAC header string
  // id
  // ts
  // nonce
  // mac
  String authHeader = " Mac id=\"" + access_token + "\"," + "ts=\"" + timestamp + "\"," + "nonce=\"" + nonce
  	+ "\"," + "mac=\"" + mac_string + "\"";
  }
}

Error Handling

REST calls or Token requests may result in an error. In that case error responses are provided as follow:

1

When requesting the Authorization Grant Code, an error response (with HTTP status 400) is sent to the Application redirect URI with query string error parameters appended to it:

http://example.com/callback?error=invalid_request&error_description=Wrong%20redirect_uri

Content-Type: application/x-www-form-urlencoded

2

When requesting the Access Token, an error response (with HTTP status 400) is sent as a JSON String containing the error type and description:

Content-Type: application/json

{
    "error": "invalid_grant",
    "error_description": "grant code is expired, you need to request a new one"
}

If the Client Id sent is invalid, the response HTTP status will be 401 with the following header

WWW-Authenticate: Basic realm="/oauth/token"
3

When making a REST call a JSON string is sent with the response containing the HTTP status code and a status description. Examples:

{
    "statusCode": 400,
    "statusMessage": "The request could not be understood by the server due to malformed syntax."
}
{
    "statusCode": 404,
    "statusMessage": "No Product found"
}
{
    "statusCode": 405,
    "statusMessage": "Method Not Allowed. The method specified in the request is not allowed for the resource identified by the request URI"
}

The error messages are according to OAuth2 specification:

Attribute Required Example value Description
error x invalid_request The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed.
x invalid_client Client authentication failed (e.g. unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported.
x invalid_grant The provided authorization grant (e.g. authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
x unauthorized_client The client is not authorized to request an authorization code using this method.
x access_denied The resource owner or authorization server denied the request.
x unsupported_response_type The authorization server does not support obtaining an authorization code using this method.
x unsupported_grant_type The authorization grant type is not supported by the authorization server.
x invalid_scope The requested scope is invalid, unknown, or malformed.
x server_error The authorization server encountered an unexpected condition which prevented it from fulfilling the request.
x temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
error_description x Wrong%20redirect_uri A human-readable UTF-8 encoded text providing additional information, used to assist the client developer in understanding the error that occurred.
state --- xyz if a state parameter was present in the client authorization request. The exact value received from the client.

Application Approval Process

For any application that requests to access Sellmate data for regular merchant accounts (which will be the case for vast majority of applications), it needs to be approved by the Sellmate team as a last step. If you create a new Application in the Developer Center, it only has an access to the Sandbox store and any stores owned by you (as the developer user). This will allow you to develop the application against the sandbox or real shop with a fully functioning REST API.

Once the application is finished, you can request the approval on the Application page in the Developer Center - this will notify the Sellmate team, which will review the application and enable it to be installed for any shop. The approval process is in place to prevent abuse and/or malicious applications to be able to access the real stores.

A separate step will allow to request the Application to be listed in the Sellmate App Store. Details for this will be published later.

Shop

Summary: Read access to the metadata and settings of the shop the application accesses

Supported methods: GET

Request patterns:

  GET    /<shop-handle>/rest/shop          to get shop info and settings

Shop Resource properties:

Attribute Type Example value Description
handle Number sample-store Resource id
created_at String Sat, 28 Apr 2012 19:24:06 UTC Resource create date
updated_at String Tue, 31 Jul 2012 17:01:45 UTC Resource last update date or null if it has not been updated yet
name String My great store The shop (human-friendly) name
currency String USD Currency setting of the shop
locale String en Locale setting of the shop
isSandbox boolean true true for Sandbox shops, false for regular shops
locked boolean false If true, the shop is locked and not accessible
showAddress boolean false Show Address preference of the shop
customDomain String shop.example.com Custom domain setting for the shop, empty string if not set or null if not specified
address Object Address of the shop
first_name String John First name of the shop owner
last_name String Doe Last name of the shop owner
company String Example Corp. Company name
address1 String 42 My Street Address line 1
address2 String Address line 2 or null if not specified
city String New York City
zip String 10000 ZIP code
province String NY Province/State or null if not specified
country String USA Country
country_code String us 2-letter ISO 3166-1 country code
phone String 615-123-4567 Phone number
logo Object Shop logo or null if not specified
id Number 11 Resource id
created_at String Sat, 28 Apr 2012 19:24:06 UTC Resource create date
updated_at String null Resource last update date or null if it has not been updated yet
name String logo.png The name of the image
url String http://lh5.ggpht.com/JeuOabgSa7SOpPug... Image url (GET only). Default max size is 512px.
original_size_url String http://lh5.ggpht.com/JeuOabgSa7SOpPug...=s0 Image url (GET only) at original size (by appending the =s0 parameter)
type String image/png The content-type string with the image type
html_snippet String My <b>great<b> store! The HTML snippet of the rich text shop description

Examples:

200 GET /<shop-handle>/rest/shop

Show code
{
    "handle": "sample-store",
    "created_at": "Sat, 28 Apr 2012 19:24:06 UTC",
    "updated_at": "Tue, 31 Jul 2012 17:01:45 UTC",
    "name": "My great store",
    "currency": "USD",
    "locale": "en",
    "isSandbox": false,
    "locked": false,
    "showAddress": false,
    "customDomain": "shop.example.com",
    "address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "Example Corp.",
        "address1": "42 My Street",
        "address2": "",
        "city": "New York",
        "zip": "10000",
        "province": "NY",
        "country": "USA",
        "country_code": "us",
        "phone": "615-123-4567"
    },
    "logo": {
        "id": 11,
        "created_at": "Tue, 31 Jul 2012 17:01:45 UTC",
        "updated_at": null,
        "name": "logo.png",
        "url": "http://lh5.ggpht.com/eoc_kFpwewhjv6lNQlWijpv2TTSgH-wNsCOXC_3D9a5cgHtblJyBPLZa0sUqawEtSUyh3uYmf2xneW4VtBq9K20",
        "original_size_url": "http://lh5.ggpht.com/eoc_kFpwewhjv6lNQlWijpv2TTSgH-wNsCOXC_3D9a5cgHtblJyBPLZa0sUqawEtSUyh3uYmf2xneW4VtBq9K20=s0",
        "type": "image/png"
    },
    "html_snippet": "My great store"
}

User

Summary: Read access to the metadata about the user using the app (the authenticated user using the application)

Supported methods: GET

Request patterns:

GET    /<shop-handle>/rest/user          to get (currently authenticated) user info and settings

User Resource properties:

Attribute Type Example value Description
id Number 1 Resource id
created_at String Sat, 28 Apr 2012 19:24:05 UTC Resource create date
updated_at String Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
email String john.doe@example.com User email
first_name String John User first name
last_name String Doe User last name
roles Array of Strings ["merchant", "developer"] The set of roles of the user (current possible values: merchant, developer)
shop_handles Array of Strings ["sample-store", "another-store"] A list of the resource ids of shops the user owns (can be empty)
sandbox_id String ids4h5sd8e The resource id of the associated Sandbox shop
locale String en Locale preference of the user

Examples:

200 GET /<shop-handle>/rest/user

Show code
{
    "id": 1,
    "created_at": "Sat, 28 Apr 2012 19:24:05 UTC",
    "updated_at": "Mon, 14 May 2012 10:49:52 UTC",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "roles": [
        "merchant",
        "developer"
    ],
    "shop_handles": [
        "sample-store",
        "another-store"
    ],
    "sandbox_id": "ids4h5sd8e",
    "locale": "en"
}

Products

Summary: Read/Write access to products within a shop

Supported methods: GET, POST, PUT, DELETE

Request patterns:

GET    /<shop-handle>/rest/products          to get list of all products in the shop
GET    /<shop-handle>/rest/products/count    to get the count of all products in the shop
POST   /<shop-handle>/rest/products          to create a new product
GET    /<shop-handle>/rest/products/<id>     to get a specific product
PUT    /<shop-handle>/rest/products/<id>     to modify an existing product
DELETE /<shop-handle>/rest/products/<id>     to delete an existing product

Common URL query parameters

Query parameters can be used to fetch specific Products (they can be combined together). GET /products only.

Parameter Example Description
limit .../products?limit=50 amout of results (default: 25, maximum: 100)
page .../products?page=3 page to show (default: 1)
collection .../products?collection=1001 filter by Collection Id
fields .../products?fields=id,title,vendor,featured_image comma-separated list of fields to include in the response
query .../products?query=published=true;stock>10 semi-column-separated list of filters (using operators ><=)

Product Resource properties:

Attribute Type Required Example value Description
id Number o 1 Resource Id. Must be given when updating the Product.
created_at String --- Sat, 28 Apr 2012 19:24:05 UTC Resource create date
updated_at String --- Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
published_at String --- Mon, 14 May 2012 10:49:52 UTC Product last publish date ( GET only)
published Boolean x true true if the product is published, false otherwise or null if not specified
title String x Adidas T-Shirt Product title or null if not specified
description String --- A Cool Adidas T-Shirt Product description (HTML) or null if not specified
vendor String x Adidas Product vendor or null if not specified
handle String o adidas-1 Product unique handle (appears in URL) or null if not specified. It's automatically generated from the Product.title when a new Product is created.
collection_ids Array of Numbers --- [4, 5] A list of collections (their IDs) that contain the product or null if not specified
tags Array of Strings --- ["t-shirts", "blue-shirts"] A list of tag names or null if not specified
stock Number --- 10 The number of items in stock, based on the Variant values ( GET only)
url String --- en The public product URL (if published) or null ( GET only)
image_ids Array of Numbers --- [11,12,13] A list of Ids of the Images associated to the Product or null if not specified. An empty array will delete the old values.
featured_image Object --- The main image or null if none ( GET only)
id Number --- 11 Resource id
created_at String --- Sat, 28 Apr 2012 19:24:06 UTC Resource create date
updated_at String --- Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
name String --- jersey.png The name of the image
url String --- http://lh5.ggpht.com/JeuOabgSa7SOpPug... Image url (GET only). Default max size is 512px.
original_size_url String --- http://lh5.ggpht.com/JeuOabgSa7SOpPug...=s0 Image url (GET only) at original size (by appending the =s0 parameter)
type String --- image/png The content-type string with the image type
options Array of Strings o ["size", "color"] The product options or null if not specified. An empty array will delete the old values.
variants Array of Objects x The product variants or null if not specified. There has to be at least one variant. An empty array will delete the old values.
id Number --- 20 Resource id
created_at String --- Sat, 28 Apr 2012 19:24:06 UTC Resource create date
updated_at String --- Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
product_id Number o 1 The Resource Id of the related Product. Must be given when updating the Variant.
option1 String o XL The value of the Variant Option1 or null if not specified. Must be given if the Product has at least 1 Option.
option2 String o Blue The value of the Variant Option2 or null if not specified. Must be given if the Product has at least 2 Options.
option3 String o The value of the Variant Option3 or null if not specified. Must be given if the Product has 3 Options.
sku String --- 12345 The SKU (Stock Keep Unit) of the Product, if it has one, or null if not specified.
price String x 19.99 The price of the Variant.
compare_at_price String --- 9.99 Used for Variant prices comparision or null if not specified.
stock Number --- 50 The stock quantity of the Variant or null if not specified.
weight String --- 10.5 The weight of the Variant item or null if not specified.
image_id Number --- 11 The Id of one of the Images of the Product or null if not specified.
requires_shipping Boolean --- true true if the Variant can be shipped, false otherwise or null if not specified.
is_taxable Boolean --- true true if the Variant is taxable, false otherwise or null if not specified.
googleProductCategory String x Apparel & Accessories > Clothing Google Product category or null if not specified
gender String o unisex Gender (unisex, male, female) or null if not specified. It's required for some Google Product Categories.
age_group String o adult Age group (adult, kids) or null if not specified. It's required for some Google Product Categories.
mpn String o my-product-id-1 Product MPN or null if not specified. Either the MPN or GTIN are usually required.
gtin String o 1234567890 Product GTIN or null if not specified. Either the MPN or GTIN are usually required. It's required for some Google Product Categories. It must be a valid number.
condition String x new Condition (new, used, refurbished) or null if not specified

Examples:

200 GET /<shop-handle>/rest/product/51001

Show code
{
    "id": 51001,
    "created_at": "Sat, 26 May 2012 08:37:12 UTC",
    "updated_at": null,
    "published_at": null,
    "published": false,
    "title": "Adidas T-Shirt",
    "description": "A cool Adidas t-shirt",
    "vendor": "Adidas",
    "handle": "adidas-1",
    "collection_ids": [
        1
    ],
    "tags": [
        "t-shirts",
        "blue-shirts"
    ],
    "stock": 10,
    "url": "http://sample-store.products.sellmate.com/products/adidas-1",
    "image_ids": [
        11,
        12,
        13
    ],
    "featured_image": {
        "id": 93160,
        "created_at": "Thu, 02 Aug 2012 15:43:23 UTC",
        "updated_at": null,
        "name": "NBA-Jersey.jpg",
        "url": "http://lh5.ggpht.com/JeuOabgSa7SOpPug_BK64iHoI2AFU-0mo3EccFTaRNKZL_vECv3WpY9TNI_W9MBDeTOcZeBKpiNDi8dH2zaZFCA",
        "original_size_url": "http://lh5.ggpht.com/JeuOabgSa7SOpPug_BK64iHoI2AFU-0mo3EccFTaRNKZL_vECv3WpY9TNI_W9MBDeTOcZeBKpiNDi8dH2zaZFCA=s0",
        "type": "image/jpeg"
    },
    "options": [
        "size",
        "color"
    ],
    "variants": [
        {
            "id": 52001,
            "created_at": "Sat, 26 May 2012 08:37:12 UTC",
            "updated_at": null,
            "product_id": 51001,
            "option1": "XL",
            "option2": "Blue",
            "option3": null,
            "sku": "12345",
            "price": 19.99,
            "compare_at_price": null,
            "stock": 0,
            "weight": null,
            "image_id": null,
            "requires_shipping": true,
            "taxable": true
        }
    ],
    "googleProductCategory": "Apparel & Accessories > Clothing > Shirts & Tops > T-Shirts",
    "gender": "unisex",
    "age_group": "adult",
    "mpn": "adidas-1",
    "gtin": null,
    "condition": "new"
}

201 POST /<shop-handle>/rest/products

To create a new Product you just need to provide the required fields (and no Id):

Show code
{
    "title": "Adidas T-Shirt",
    "vendor": "Adidas",
    "variants": [
        {
            "price": 19.99
        }
    ],
    "googleProductCategory": "Apparel & Accessories > Clothing > Shirts & Tops > T-Shirts",
    "gender": "unisex",
    "age_group": "adult",
    "mpn": "adidas-1",
    "condition": "new"
}

Collections

Summary: Read/Write access to collections within a shop

Supported methods: GET, POST, PUT, DELETE

Request patterns:

GET    /<shop-handle>/rest/collections          to get all collections in the shop
GET    /<shop-handle>/rest/collections/count    to get the count of all collections in the shop
POST   /<shop-handle>/rest/collections          to create a new collection
GET    /<shop-handle>/rest/collections/<id>     to get a specific collection
PUT    /<shop-handle>/rest/collections/<id>     to modify an existing collection
DELETE /<shop-handle>/rest/collections/<id>     to delete an existing collection

Common URL query parameters

Query parameters can be used to fetch specific Collections (they can be combined together). GET /collections only.

Parameter Example Description
limit .../collections?limit=50 amout of results (default: 25, maximum: 100)
page .../collections?page=3 page to show (default: 1)
fields .../collections?fields=id,title,featured_image comma-separated list of fields to include in the response
query .../collections?query=num_of_products>5 semi-column-separated list of filters (using operators ><=)

Collection Resource properties:

Attribute Type Required Example value Description
id Number o 1 Resource ID. Must be given when updating the Collection.
created_at String --- Sat, 28 Apr 2012 19:24:05 UTC Resource create date or null if not specified
updated_at String --- Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
title String x Adidas T-Shirts Collection title
handle String o adidas-1 Collection unique handle (appears in URL) or null if not specified. It's automatically generated from the Collection.title when a new Collection is created.
description String --- The Best selection of Adidas T-Shirts Collection description (HTML) or null if not specified
tags Array of Strings --- ["t-shirts", "adidas"] A list of tag names or null if not specified
image_ids Array of Numbers --- [11,12,13] A list of Ids of the Images associated to the Collection or null if not specified. An empty array will delete the old values.
featured_image Object --- The main image or null if none ( GET only)
id Number --- 11 Resource id
created_at String --- Sat, 28 Apr 2012 19:24:06 UTC Resource create date
updated_at String --- Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
name String --- jersey.png The name of the image
url String --- http://lh5.ggpht.com/JeuOabgSa7SOpPug... Image url (GET only). Default max size is 512px.
original_size_url String --- http://lh5.ggpht.com/JeuOabgSa7SOpPug...=s0 Image url (GET only) at original size (by appending the =s0 parameter)
type String --- image/png The content-type string with the image type
num_of_products Number --- 1 Number of products in the collection ( GET only)

Examples:

200 GET /<shop-handle>/rest/collections/1

Show code
{
    "id": 1,
    "created_at": "Sat, 28 Apr 2012 19:24:05 UTC",
    "updated_at": null,
    "title": "Default Collection",
    "handle": "default-collection",
    "description": null,
    "tags": [
        "T-shirt"
    ],
    "image_ids": [10,11],
    "featured_image": {
        "id": 1133,
        "created_at": "mar, 06 mar 2012 10:49:13 UTC",
        "updated_at": null,
        "name": "KobeJersey.jpg",
        "url": "http://lh5.ggpht.com/JeuOabgSa7SOpPug_BK64iHoI2AFU-0mo3EccFTaRNKZL_vECv3WpY9TNI_W9MBDeTOcZeBKpiNDi8dH2zaZFCA",
        "original_size_url": "http://lh5.ggpht.com/JeuOabgSa7SOpPug_BK64iHoI2AFU-0mo3EccFTaRNKZL_vECv3WpY9TNI_W9MBDeTOcZeBKpiNDi8dH2zaZFCA=s0",
        "type": "image/jpeg"
    },
    "num_of_products": 1
}

201 POST /<shop-handle>/rest/collections

To create a new Collection you just need to provide the required fields (and no Id):

Show code
{
    "title": "Snowboards"
}

Images (Products + Collections)

Summary: Read/Write access to images within a resource (Product or Collection)

Supported methods: GET, POST, PUT, DELETE

Request patterns:

GET    /<shop-handle>/rest/<products|collections>/<id>/images          to get all images in the resource
GET    /<shop-handle>/rest/<products|collections>/<id>/images/count    to get the count of all images in the resource
POST   /<shop-handle>/rest/<products|collections>/<id>/images          to create a new image for a resource
GET    /<shop-handle>/rest/<products|collections>/<id>/images/<id>     to get a specific image in the resource
PUT    /<shop-handle>/rest/<products|collections>/<id>/images/<id>     to modify an existing image in the resource
DELETE /<shop-handle>/rest/<products|collections>/<id>/images/<id>     to delete an existing image in the resource

Common URL query parameters

Query parameters can be used to fetch specific Images (they can be combined together). GET /images only.

Parameter Example Description
fields .../images?fields=id,name,url comma-separated list of fields to include in the response
query .../images?query=type>image/png semi-column-separated list of filters (using operators ><=)

Image Resource properties:

Attribute Type Required Example value Description
id Number --- 11 Resource id
created_at String --- Sat, 28 Apr 2012 19:24:06 UTC Resource create date
updated_at String --- Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
name String --- jersey.png The name of the image
url String --- http://lh5.ggpht.com/JeuOabgSa7SOpPug... Image url (GET only). Default max size is 512px.
original_size_url String --- http://lh5.ggpht.com/JeuOabgSa7SOpPug...=s0 Image url (GET only) at original size (by appending the =s0 parameter)
type String --- image/png The content-type string with the image type

Image URL modifications:

To resize an image, append =sXX to the end of the image URL, where XX is an integer from 0–1600 representing the new image size in pixels. The API resizes the image to the supplied value, applying the specified size to the image's longest dimension and preserving the original aspect ratio. For example, if you use =s32 to resize a 1200x1600 image, the resulting image is a 24x32. If that image were 1600x1200, the resized image would be 32x24 pixels.

To crop and resize an image, append =sXX-c to the end of the image URL, where XX is an integer from 0–1600 representing the new image size in pixels. The API resizes the image to the supplied value, applying the specified size to the image's longest dimension and preserving the original aspect ratio. If the image is portrait, the API slices evenly from the top and bottom to make a square. If the image is landscape, the API slices evenly from the left and right to make a square. After cropping, the API resizes the image to the specified size.

Examples:

200 GET /<shop-handle>/rest/products/78/images/1133

Show code
{
    "id": 1133,
    "created_at": "mar, 06 mar 2012 10:49:13 UTC",
    "updated_at": null,
    "name": "KobeJersey.jpg",
    "url": "http://lh5.ggpht.com/JeuOabgSa7SOpPug_BK64iHoI2AFU-0mo3EccFTaRNKZL_vECv3WpY9TNI_W9MBDeTOcZeBKpiNDi8dH2zaZFCA",
    "original_size_url": "http://lh5.ggpht.com/JeuOabgSa7SOpPug_BK64iHoI2AFU-0mo3EccFTaRNKZL_vECv3WpY9TNI_W9MBDeTOcZeBKpiNDi8dH2zaZFCA=s0",
    "type": "image/jpeg"
}

201 POST /<shop-handle>/rest/products/78/images

To create a new image you have 2 possibilities: provide a url or a base-64 encoded string:

Show code
{
    "src": "http://www.nysportsjournalism.com/storage/KobeJersey.jpg"
}
{
    "name": "image-name",
    "type":"image/png",
    "attachment": "put your base64-encoded image data here"
}

Orders

Summary: Read/Write access to orders within a shop

Supported methods: GET, POST, PUT

Request patterns:

GET    /<shop-handle>/rest/orders          to get list of all orders in the shop
GET    /<shop-handle>/rest/orders/count    to get the count of all orders in the shop
POST   /<shop-handle>/rest/orders          to create a new order
GET    /<shop-handle>/rest/orders/<id>     to get a specific order
PUT    /<shop-handle>/rest/orders/<id>     to modify an existing order

Common URL query parameters

Query parameters can be used to fetch specific Orders (they can be combined together). GET /orders only.

Parameter Example Description
limit .../orders?limit=50 amout of results (default: 25, maximum: 100)
page .../orders?page=3 page to show (default: 1)
fields .../orders?fields=id,subtotal_price,gateway comma-separated list of fields to include in the response
query .../orders?query=subtotal_price<50 semi-column-separated list of filters (using operators ><=)

Order Resource properties:

Attribute Type Required Example value Description
id Number o 1 Resource ID. Must be given when updating the Order.
created_at String --- Sat, 28 Apr 2012 19:24:05 UTC Resource create date or null if not specified
updated_at String --- Mon, 14 May 2012 10:49:52 UTC Resource last update date or null if it has not been updated yet
subtotal_price String x 120 Order subtotal price. It must be not null and >0.
shipping_price String x 10 Order shipping price. It must be not null and >0.
tax_price String x 0 Order tax price. It must be not null and >0.
total_price String x 130 Order total price, the sum of subtotal_price, shipping_price, tax_price. It must be not null and >0.
line_items Array of Objects --- The list of items in the order
variant_id Number x 14 Variant resource Id
product_id Number x 10 Product resource Id
title String x T-Shirt - Blue XL The title of the Item, usually the combination of product title and variant options.
product_title String x T-Shirt Product title.
product_description String --- A Cool Adidas T-Shirt Product description (HTML) or null if not specified
product_vendor String --- Adidas Product vendor or null if not specified
variant_option1 String --- Blue The value of the Variant Option1 or null if not specified.
variant_option2 String --- XL The value of the Variant Option2 or null if not specified.
variant_option3 String --- null The value of the Variant Option3 or null if not specified.
variant_sku String --- 12345 The SKU (Stock Keep Unit) of the Product, if it has one, or null if not specified.
variant_price String x 120 The price of the Variant.
variant_weight String --- 10.5 The weight of the Variant item or null if not specified.
variant_weight_unit String --- null The weight unit of the Variant item or null if not specified.
variant_requires_shipping Boolean --- true true if the Variant can be shipped, false otherwise or null if not specified.
variant_taxable Boolean --- true true if the Variant is taxable, false otherwise or null if not specified.
quantity Number x 1 The quantity of the item in the order, must be at least 1.
line_price Number --- 120 The price of the item, based on the variant price and the quantity.
shipping_method Object --- Info about the shipping method or null if not specified.
price String x 3.99 The price of the shipping method. It must be >0
tracking_code String --- abcd1234 The code used to track the shipment or null if not specified.
carrier String x UPS The carrier used to ship (UPS, FedEx, ...)
payment_details Object --- TBD
note String --- null A note about the order, or null if not specified.
gateway String x GoogleCheckout The gateway used to purchase the order. It must be Prepayment, PayPal, GoogleCheckout, CashOnDelivery, Invoice.
currency String x USD The currency of the order.
shipping_address Object x Shipping address
first_name String x John First name
last_name String x Doe Last name
company String --- Example Corp. Company name
address1 String x 42 My Street Address line 1
address2 String --- Address line 2 or null if not specified
city String x New York City
zip String x 10000 ZIP code
province String --- NY Province/State or null if not specified
country String x USA Country
country_code String --- us 2-letter ISO 3166-1 country code
phone String --- 615-123-4567 Phone number
billing_address Object x Billing address
first_name String x John First name
last_name String x Doe Last name
company String --- Example Corp. Company name
address1 String x 42 My Street Address line 1
address2 String --- Address line 2 or null if not specified
city String x New York City
zip String x 10000 ZIP code
province String --- NY Province/State or null if not specified
country String x USA Country
country_code String --- us 2-letter ISO 3166-1 country code
phone String --- 615-123-4567 Phone number
customer Object x Info about customer
first_name String x John First name
last_name String x Doe Last name
email String x John Email address
addresses Array of Objects x The list of addresses in the customer
order_number String x 123456789123456 The order number.
order_name String x GC-123456789123456 The order name, tipically with a prefix followed by the order_number to indicate where the order was generated from (GC for GoogleCheckout, PP for PayPal, SM for orders created with the REST API).
cancelled_at String --- null Order cancel date or null if not specified.
cancel_reason String --- null The reason why the order has been cancelled or null if not specified.
closed_at String --- Mer, 08 ago 2012 09:26:10 UTC Order close date or null if not specified.
referring_site String --- https://www.google.com/search?tbm=shop&q=my-product Contains the url of the referrer that brought the customer to your store or null if not specified.
fulfillment_status Object x NEW The fulfillment status of the order. It must be FULFILLED, UNFULFILLED, NEW, PROCESSING, DELIVERED, WILL_NOT_DELIVER
financial_status Object x REVIEWING The financial status of the order. It must be AUTHORIZED, REVIEWING, CHARGEABLE, CHARGING, CHARGED, PAYMENT_DECLINED, REFUNDED, CANCELLED, CANCELLED_BY_GOOGLE
isSandbox Boolean x false true if the order was made in a Sandbox environment, false otherwise.

Examples:

200 GET /<shop-handle>/rest/orders/743

Show code
{
    "id": 743,
    "created_at": "mar, 07 ago 2012 14:34:55 UTC",
    "updated_at": null,
    "subtotal_price": 120,
    "shipping_price": 4.95,
    "tax_price": 0,
    "total_price": 124.95,
    "line_items": [
        {
            "variant_id": 14,
            "product_id": 10,
            "title": "T-Shirt - Blue XL",
            "product_title": "T-Shirt",
            "product_description": "A Cool Adidas T-Shirt",
            "product_vendor": "Adidas",
            "variant_option1": "Blue",
            "variant_option2": "XL",
            "variant_option3": "",
            "variant_sku": null,
            "variant_price": 120,
            "variant_weight": null,
            "variant_weight_unit": null,
            "variant_requires_shipping": true,
            "variant_taxable": true,
            "quantity": 1,
            "line_price": 120
        }
    ],
    "shipping_method": null,
    "payment_details": null,
    "note": null,
    "gateway": "GoogleCheckout",
    "currency": "USD",
    "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "Example Corp.",
        "address1": "42 My Street",
        "address2": "",
        "city": "New York",
        "zip": "10000",
        "province": "NY",
        "country": "USA",
        "country_code": "us",
        "phone": "615-123-4567"
    },
    "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "Example Corp.",
        "address1": "42 My Street",
        "address2": "",
        "city": "New York",
        "zip": "10000",
        "province": "NY",
        "country": "USA",
        "country_code": "us",
        "phone": "615-123-4567"
    },
    "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "addresses": [
            {
                "first_name": "John",
                "last_name": "Doe",
                "company": "Example Corp.",
                "address1": "42 My Street",
                "address2": "",
                "city": "New York",
                "zip": "10000",
                "province": "NY",
                "country": "USA",
                "country_code": "us",
                "phone": "615-123-4567"
            }
        ]
    },
    "order_number": "123456789123456",
    "order_name": "GC-123456789123456",
    "cancelled_at": null,
    "closed_at": null,
    "cancel_reason": null,
    "referring_site": null,
    "fulfillment_status": "NEW",
    "financial_status": "REVIEWING",
    "isSandbox": false
}

201 POST /<shop-handle>/rest/orders

To create a new Order you just need to provide the required fields (and no Id):

Show code
{
    "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "Example Corp.",
        "address1": "42 My Street",
        "address2": "",
        "city": "New York",
        "zip": "10000",
        "province": "NY",
        "country": "USA",
        "country_code": "us",
        "phone": "615-123-4567"
    },
    "cancel_reason": null,
    "currency": "USD",
    "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "addresses": [
            {
                "first_name": "John",
                "last_name": "Doe",
                "company": "Example Corp.",
                "address1": "42 My Street",
                "address2": "",
                "city": "New York",
                "zip": "10000",
                "province": "NY",
                "country": "USA",
                "country_code": "us",
                "phone": "615-123-4567"
            }
        ]
    },
    "financial_status": "REVIEWING",
    "fulfillment_status": "NEW",
    "gateway": "GoogleCheckout",
    "line_items": [
        {
            "variant_id": 14,
            "product_id": 10,
            "title": "T-Shirt - Blue XL",
            "product_title": "T-Shirt",
            "product_description": "A Cool Adidas T-Shirt",
            "product_vendor": "Adidas",
            "variant_option1": "Blue",
            "variant_option2": "XL",
            "variant_option3": "",
            "variant_sku": null,
            "variant_price": 120,
            "variant_weight": null,
            "variant_weight_unit": null,
            "variant_requires_shipping": true,
            "variant_taxable": true,
            "quantity": 1,
            "line_price": 120
        }
    ],
    "note": null,
    "order_name": "GC-335042596951346",
    "order_number": "335042596951346",
    "payment_details": null,
    "referring_site": null,
    "isSandbox": false,
    "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "Example Corp.",
        "address1": "42 My Street",
        "address2": "",
        "city": "New York",
        "zip": "10000",
        "province": "NY",
        "country": "USA",
        "country_code": "us",
        "phone": "615-123-4567"
    },
    "shipping_method": null,
    "shipping_price": 4.95,
    "subtotal_price": 120,
    "tax_price": 0,
    "total_price": 124.95
}