Getting started

Documentation for all public and administrative Storefront APIs.

Authentication

We use the OAuth 2.0 Authorization Framework to authenticate requests. When your Storefront account is provisioned, you will receive a pair of YOUR_CLIENT_ID and YOUR_CLIENT_SECRET that you need to keep for yourself. You use the YOUR_CLIENT_ID and YOUR_CLIENT_SECRET to authenticate yourself to Storefront, and receive an access token in exchange. That access token must be used in every API call you send.

caution

Never share your YOUR_CLIENT_SECRET!

note

Access tokens are short-lived, meaning: they expire within minutes. Once an access token expires, simply request a new access token by method described below.

User-Scoped and Tenant-Scoped Clients

There are two types of clients. User-scoped clients are always assigned to an individual user. Tenant-scoped clients can be used to execute an API request on behalf of another user.

A user-scoped client is required for APIs that require elevated permissions such as creating new catalogs or modifying vendors. For example, the Admin API requires a user-scoped client.

A tenant-scoped client can be used for APIs that are typically executed by a machine on behalf of a user. An example is to search for a product on behalf of some shopper. It would simply not be suitable to issue a client for each user, especially for organizations with thousands of users.

Tenant-scoped clients typically allow to pass the email address for which the request should be executed. Please refer to the actual documentation if and how a user-scoped or a tenant-scoped client are permitted.

Issuing an Access Token

Here are the steps towards getting yourself an access token.

Prepare a HTTP request like so:

1. Set the URL to https://YOUR_DOMAIN/oauth/authorize.
2. Set the Content-Type header to application/x-www-form-urlencoded.
3. Set the grant_type=client_credentials as a parameter.
4. Set the client_id=YOUR_CLIENT_ID as a parameter.
5. Set the client_secret=YOUR_CLIENT_SECRET as a parameter.
6. (optional) For tenant-scoped clients, set the email=YOUR_EMAIL_ADDRESS as a parameter.
7. Send the HTTP request via HTTP POST.

Examples

cURL

curl --request POST \
     --url 'https://YOUR_DOMAIN/oauth/authorize' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data client_id=YOUR_CLIENT_ID \
     --data client_secret=YOUR_CLIENT_SECRET

JavaScript

var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://YOUR_DOMAIN/oauth/authorize',
  headers: {'content-type': 'application/x-www-form-urlencoded'},
  data: {
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

C#

var client = new RestClient("https://YOUR_DOMAIN/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Java

HttpResponse<String> response = Unirest.post("https://YOUR_DOMAIN/oauth/authorize")
  .header("content-type", "application/x-www-form-urlencoded")
  .body("grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET")
  .asString();

Go

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io"
)

func main() {
    // Configure your URL
    url := "https://YOUR_DOMAIN"

    // Ask for the client_credentials OAuth 2.0 flow
    data := url.Values{
        "grant_type":    []string{"client_credentials"},
        "client_id":     []string{YOUR_CLIENT_ID},
        "client_secret": []string{YOUR_CLIENT_SECRET},
    }
    requestBody := strings.NewReader(data.Encode())

    // Prepare HTTP request
    req, err := http.NewRequest("POST", baseURL+"/oauth/authorize", requestBody)
    if err != nil {
        panic(err)
    }
    req.Header.Set("content-type", "application/x-www-form-urlencoded")

    // Execute the request
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // The HTTP response body will return JSON according to the OAuth 2.0 specification.
    body, err := io.ReadAll(req.Body)
    if err != nil {
        panic(err)
    }
    fmt.Println(resp)
    fmt.Println(string(body))
}

Parameters

Parameter	Description
grant_type	Set this to client_credentials to ask for the OAuth 2.0 Client Credentials flow.
client_id	Your Storefront Client ID. You can find this in the settings tab of your account.
client_secret	Your Storefront Client Secret. You can find this in the settings tab of your account.
email	Only required if the Client is tenant-scoped.

Response

If everything goes well, you will receive a successful HTTP response with status 200 OK with a payload containing the access_token, token_type, and expires_in values:

{
    "access_token": "HH3wr4...Neuz2PI",
    "token_type": "bearer",
    "expires_in": 300
}

Notice that the expires_in specifies the number of seconds until this access token expires.

note

If your access token is expired, you'll get a HTTP response with status 401 Unauthorized.

Errors

In case of an error, you can use the HTTP status code and the response body to find out what went wrong.

HTTP Status Code	Description
400 Bad Request	The server understood your request but is unable to complete it, e.g. because a required parameter is missing.
401 Unauthorized	You sent invalid credentials.
500 Internal Server Error	Something went wrong on our side.

The HTTP response body if formatted according to the OAuth 2.0 Specification Section 5.2.

Example:

{
    "error": "invalid_request",
    "error_description": "Invalid request"
}