Sync products, stock and orders without retyping

• Base URL. The Developer API screen shows yours, ending in /api/public/v1. Examples here use https://app.simplebks.com/api/public/v1.
• Format. JSON in, JSON out. Every response has success.
• Auth. Authorization: Bearer sbk_live_.... See Authentication.
• Pagination. ?page=1&limit=25, with a maximum limit of 100. List responses include a pagination object.
• Idempotency. Send an Idempotency-Key header on POST and PATCH orders. A retry with the same key never creates or settles twice.

curl "https://app.simplebks.com/api/public/v1/products?updated_since=2026-10-01&limit=2" \
  -H "Authorization: Bearer sbk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Each product has id, sku, name, description, barcode, tags, color, size, measurement, sellingPrice, image, isVariant, parentId, stock, orderRule, createdAt and updatedAt. orderRule is read-only (minimum order quantity and multiple) or null.

If the business has set an online stock location in Settings, Developer API, each stock row also carries that location's quantity. Sell from onlineLocation.quantity when it is present, otherwise quantity. Raw materials, archived products and products excluded from the online location are never returned.

{
  "reference": "SHOP-1042",
  "customer": { "name": "Ada Obi", "phone": "08030000000", "email": "[email protected]" },
  "items": [ { "sku": "CQ-001", "quantity": 2, "price": 5000 } ],
  "shippingFee": 1500,
  "paymentStatus": "paid",
  "paymentMethod": "paystack",
  "gatewayReference": "YOUR-GATEWAY-REFERENCE",
  "shippingAddress": "12 Example Street, Lagos",
  "notes": "Gift wrap"
}

curl -X POST "https://app.simplebks.com/api/public/v1/orders" \
  -H "Authorization: Bearer sbk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Idempotency-Key: SHOP-1042" \
  -H "Content-Type: application/json" \
  -d @order.json

• Required: customer.name and at least one item. Each item needs sku and a quantity of 1 or more. price is optional and defaults to the catalogue price. A negative price is rejected.
• Limits: at most 200 items per order. An unknown SKU returns 422 with every problem listed in errors.
• Payment: paymentMethod is one of paystack, card, transfer, cod, cash. paymentStatus: "paid" settles it at once.
• Duplicates: sending the same reference again returns the existing order with duplicate: true.
• Minimum quantities: an unpaid line below a product's minimum, or off its multiple, is rounded up and listed in quantityAdjustments. If the rounded quantity is more than you hold, the order is refused with 422 ORDER_QUANTITY_RULE.
• Response (201): the order with orderNumber (for example WEB-00012), status, paymentStatus, items, subtotal, shippingFee, total, saleReference, needsAttention, quantityAdjustments and createdAt.

curl -X PATCH "https://app.simplebks.com/api/public/v1/orders/WEB-00012" \
  -H "Authorization: Bearer sbk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"event":"payment.confirmed","method":"paystack","reference":"YOUR-GATEWAY-REFERENCE"}'

• payment.confirmed settles the customer's balance. paystack and card go to the gateway clearing account, cod and cash to Cash, transfer to the transfers clearing account. Repeat calls are safe.
• fulfilled marks the order delivered or collected.
• cancelled reverses the sale and restores stock. An order that is already paid is refused with 409: handle that as a refund inside Simplebks.

curl -X PUT "https://app.simplebks.com/api/public/v1/products/SK-0012/image" \
  -H "Authorization: Bearer sbk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.example/img/tee.jpg"}'

The URL must be publicly reachable and return real image bytes up to 8 MB. Sending the same picture again returns unchanged: true. An unknown SKU is 404; a bad or unreachable URL is 422. This needs the images:write scope.