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 ```text title="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. ```bash title="Authenticated request" curl https://api.subbly.co/private/v1/customers \ -H 'X-API-KEY: ' ``` ### Get your API key Private API keys live in the Subbly admin under [Settings › API keys](https://www.subbly.co/admin/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: ```json title="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.