Copy page

Storefront API

The Storefront API is the API behind your storefront: the shop and its settings, products and bundles, carts and checkout, and the account of the signed-in customer. It is safe to call from the browser with a Storefront API key; Subbly.js wraps it for you.

Base URL

Base URL
https://api.subbly.co/storefront/v1

Every path in this reference is relative to it. Requests and responses are JSON; send Content-Type: application/json with a body.

Authentication

Send your Storefront API key in the X-API-KEY header on every request.

Endpoints about one customer — their addresses, subscriptions, orders, wallet — also need the customer's access token, in the Authorization header as a bearer token. The Auth endpoints issue the token; it expires after expires_in seconds.

Both headers
curl https://api.subbly.co/storefront/v1/customer \
  -H 'X-API-KEY: <api-key>' \
  -H 'Authorization: Bearer <access-token>'

Pagination

List endpoints take page and per_page query parameters and return the items in data next to a pagination object:

A page
{
  "pagination": {
    "current_page": 1,
    "last_page": 4,
    "from": 1,
    "to": 25,
    "total": 92
  },
  "data": []
}

Errors

The API answers with the usual HTTP status codes. 4xx responses carry a JSON body with a message; validation errors (422) add a code and an errors object keyed by field.

Status	Meaning
400	The request is malformed.
401	The API key or the access token is missing or wrong.
403	The key is valid but may not do this.
404	Nothing at this path, or it belongs to another shop.
422	The body or the query failed validation.
429	Too many requests; wait and retry.

The description of each endpoint lists the errors it can return.