Out: catalogue and stock
Pull with GET requests. Poll with updated_since, or react to stock.updated webhooks.
Developers
Run your own website on your real stock
A developer connects your site once. After that, stock flows out and orders flow into your books.
At a glance
| Item | Detail |
|---|---|
| Who it is for | Businesses with a custom-built site or app, and the developer who builds it |
| Plan | Professional and Enterprise plans |
| Permission | Manage integrations |
| Direction | Catalogue and stock out to the site. Orders in. Product pictures can come in from the site. |
| Not for you if | You run WooCommerce. Use the WooCommerce connection instead. |
Set up
The site never writes stock. Simplebks stays the source of truth.
-
Set the online stock location
Optional. In Settings, Integrations, Developer API, choose the Online stock location your site sells from. Leave it unset to expose total stock.
-
Check readiness
The Catalogue integration readiness card counts missing and duplicate SKUs. Fix them first: the API identifies products by SKU.
-
Create a key
Create an API key. Start with a Test key while you build.
-
Read the catalogue
Your site calls GET /products and GET /stock, and can use updated_since for incremental sync.
-
Send orders
Your site calls POST /orders with a stable reference and an Idempotency-Key, then PATCH /orders/:orderNumber for payment, fulfilment or cancellation.
-
Subscribe to webhooks
Add an endpoint for order.updated and stock.updated so your site stays current without polling.
-
Go live
Create a Live key, swap it into your server settings and revoke the Test key.
Optional: import product details from your site
Use this if your site is where product names, descriptions and pictures are first written. Find it under Settings, Integrations, Developer API, Import product details from your website.
- How it works. You give Simplebks an HTTPS feed address and an optional bearer token. Simplebks pulls it only when you ask: Save, Test, then Preview. You approve what to import. Nothing runs on a schedule and nothing is pushed back.
- Feed shape. JSON with an array under
products(ordata). For more pages, returnnextCursor; Simplebks asks for the next page with?cursor=. - Required per product.
externalId(orid),sku,nameandsellingPrice(zero or more). - Optional.
description,categoryName,brandName,tags,imageUrl(orimage, orimages[0].url) andstatusof active or inactive. Stock in the feed is ignored. - Limits. HTTPS only, 12 seconds per request, 5 MB per response, 20 pages and 5,000 products per run.
- Conflicts. Choose Use website details for selected changes, or Keep Simplebks details. Undo safe changes is available after a run.
{
"schemaVersion": "1",
"products": [
{ "externalId": "p-100", "sku": "TEE-BLUE-M", "name": "Blue tee", "sellingPrice": 5000,
"description": "Cotton tee", "categoryName": "Tops", "status": "active" }
],
"nextCursor": null
}What moves
In: orders
POST /orders books a sale at once. Strict SKU matching: an unknown SKU is refused with 422.
Both: events
Webhooks tell your site when an order changes, including when staff change it in Simplebks.
Limits and known issues
- Public API keys are strict about SKUs. An unknown SKU is refused, unlike WooCommerce orders.
- Rate limit: 120 requests per minute per key.
- Cancelling a paid order through the API is refused. Handle refunds inside Simplebks.
Troubleshooting
| You see | Do this |
|---|---|
| 402 PLAN_UPGRADE_REQUIRED | The business is not on the Professional or Enterprise plan. |
| 403 INSUFFICIENT_SCOPE | Edit the key scopes: revoke and create a key with the scope you need. |
| 422 on POST /orders | Read the errors array. It names each item with a missing or unknown SKU or a bad quantity. |
| Orders appear but not in the books you expect | Check you used a Live key. Test key orders are flagged TEST. |
| Catalogue test fails | The feed address must be HTTPS and return JSON with a products array within 12 seconds. |
Security
What Simplebks stores and how you take it back.
- Keep keys on your server. Never ship an API key in browser code.
- Feed token is encrypted. The optional bearer token for your catalogue feed is sealed at rest and never shown again.
- Verify webhooks. Check the signature on every delivery.
Not supported yet
- Writing stock or prices by API.
- Reading customers, invoices or reports by API.
- A separate sandbox host.
FAQ
Can my site take payments?
Your site takes payment with its own gateway, then reports it with a payment.confirmed event so Simplebks settles the order.
Can my site update stock?
No. Stock moves only through orders you send and activity inside Simplebks.
Do I have to use the catalogue feed import?
No. It is optional and only for bringing product details from your site into Simplebks, on request.
How do I test safely?
Use a Test key. Orders are flagged TEST in Web Orders and stay out of your real figures.
Can a non-developer set this up?
A non-technical owner can create the key and hand it to the developer, who does the rest.
Start free and hand your developer an API key.