Start here
An owner or administrator creates a key in Portal → Settings → Storefront API. Third-party API access requires Pro or above, or an active trial. Use a separate integration for each application and environment.
This is a scoped public API, with catalog reads and unpaid draft orders. It does not expose payroll, accounting reports, arbitrary customer lists, payment collection or subscription billing. Hosted stores and marketplace connectors are separate workflows.
Base URL: https://api.zubda.co/api/storefront/v1
- Create a key with the actions your integration needs.
- Store it in your server’s secret manager or environment.
- Fetch an active location, then its product catalog.
- Submit a draft with a stable checkout reference as its idempotency key.
- Review the order in Zubda before fulfillment and payment confirmation.
Keep authentication on your server
Send the key in X-API-Key. Never include it in browser JavaScript, mobile applications, query strings or public logs. A storefront browser calls your own backend; your backend calls Zubda.
GET /api/storefront/v1/locations
X-API-Key: YOUR_SERVER_SIDE_KEY
Accept: application/jsonThe API rejects Cookie, Authorization and Origin headers on these routes. Strip browser credentials in your backend proxy. Responses use Cache-Control: no-store. A Zubda subscription-payment provider secret is not an integration key.
Choose catalog-read and/or order-write scope. Order-write permits creating and checking only this integration’s orders. Keys expire after 1–365 days; their full value appears only when created or replaced.
Read catalog and availability
GET /api/storefront/v1/locations
GET /api/storefront/v1/products?locationId=LOCATION_UUID&page=0&size=25The locations response is an array of active location IDs and names. Product results are paginated, starting at page 0, with 1–100 items per page and stable name/ID ordering. Read the page’s content and pagination metadata until the last page.
Each product includes id, sku, name, description, imageUrl, unitPrice, currency, vatRate, taxInclusive, trackInventory and availableQuantity. Cost prices, suppliers and margins are excluded.
Respect taxInclusive: exclusive prices need VAT added; inclusive prices already contain it. An untracked sales-only item has null availability, which is different from zero stock. Availability is a snapshot, not a reservation. The team allocates serialized or batched items during fulfillment.
Submit an unpaid draft order
POST /api/storefront/v1/orders
X-API-Key: YOUR_SERVER_SIDE_KEY
Content-Type: application/json
Idempotency-Key: checkout-123
{
"locationId": "LOCATION_UUID",
"customer": {
"name": "Example Customer",
"email": "customer@example.com",
"phone": "+254700000000",
"address": "Delivery address"
},
"lines": [{"productId": "PRODUCT_UUID", "quantity": 2}],
"notes": "Delivery instructions"
}Use actual location and product UUIDs from your catalog. Supply customer details or an existing customerId, never both. Your backend must authorize repeat customers; never allow one shopper to choose another shopper’s customer ID.
Orders accept 1–100 lines, positive quantities with up to three decimal places, and notes up to 1,000 characters. Customer names are required and limited to 200 characters; email 200, phone 40 and address 500. All lines must use one currency. Foreign-currency orders need configured exchange rates.
Zubda calculates catalog prices, VAT and totals. Do not submit discounts, prices, payment status, fulfillment state or serial allocations. The response contains id, orderNumber, status, paymentStatus, total, amountPaid, currency and customerId.
A new order is DRAFT / UNPAID. Submission does not collect money, reserve or deduct stock, allocate serials or recognize revenue. Review and fulfill through Zubda’s sales workflow. Verify actual payments independently; a customer-facing redirect is not proof of payment.
Retry safely and check status
Use a stable Idempotency-Key of 1–100 letters, digits, dots, underscores, colons or hyphens. Repeating the same key and body returns the original order ID. A changed body with that key returns 409.
After a timeout, retry the original body and key. Generating a new key can create a second order. Store the checkout reference and returned order ID in your own backend. Prices and taxes remain server-owned; show the returned order total to the buyer.
GET /api/storefront/v1/orders/ORDER_UUID
X-API-Key: YOUR_SERVER_SIDE_KEYStatus reads are limited to orders belonging to the same integration application. Poll with backoff. Storefront API v1 does not provide outbound order webhooks.
Replace or revoke a key
- Choose Replace key in Settings.
- Save the replacement in your server’s secret manager.
- Verify a catalog request and deploy your configuration.
- Revoke the old key.
Replacement preserves the integration’s order history and retry namespace. The old key remains valid until revoked or expired. Creating a separate integration starts a new namespace. Replacements expire after 90 days.
If a key leaks, revoke the exposed key promptly. Remove it from logs and history, create a replacement, and report any suspected unauthorized access privately. Owners and admins can list and revoke keys after a downgrade, even when new key creation is locked.
Handle errors and request limits
| Status | Recovery |
|---|---|
| 400 | Check the request fields and idempotency key. |
| 401 | Check key expiry, revocation and organization access. |
| 402 | The subscription no longer includes API access. |
| 403 | Create or use a key with the required scope. |
| 404 | Check the resource ID and integration ownership. |
| 409 | Use the original body with its retry key, or start a genuinely new checkout. |
| 429 | Wait for Retry-After, then retry with backoff. |
| 5xx / timeout | Retry transient failures with backoff; preserve order body and retry key. |
The backend limits requests to 120 per minute per IP and key per instance, with Retry-After: 60 on 429. A multi-instance deployment also needs shared reverse-proxy rate limits. Your storefront must enforce shopper authentication, customer ownership and checkout abuse limits.
Organization access follows subscription grace: seven days of full access after expiry, then read-only through day 14. A key’s own expiry takes effect immediately.
Ask, share and help shape the API
Use Q&A for integration help, Ideas for feature requests, and Show and tell for examples. Read the welcome guide before posting.
Include the endpoint, HTTP status, expected result and a minimal example with synthetic data. Redact API keys, cookies, passwords, customer details and payment information. Community discussions do not promise response times or delivery dates.
For private account help, contact Zubda. Report vulnerabilities privately to platform@zubda.co with a subject starting SECURITY-.