Copy page

Private API

The Private API gives your server full access to the shop: customers, subscriptions, orders, invoices, products and more. Call it from a backend only; a private key in browser code can read and change every customer's data.

Base URL

Base URL
https://api.subbly.co/private/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 Private API key in the X-API-KEY header on every request.

Authenticated request
curl https://api.subbly.co/private/v1/customers \
  -H 'X-API-KEY: <api-key>'

Get your API key

Private API keys live in the Subbly admin under Settings › API keys. In the Private API keys card, click Generate API key, then copy the key with the icon next to it. You can keep several keys, so give each integration its own; if one leaks, delete it from the same card and generate a new one. A Private key can read and change everything in your shop, so keep it on your server and out of files you commit.

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 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.