# DZBuild API is Live — Build Custom Integrations for Your Store The **DZBuild API v1** is now live. After months of development and testing with pilot merchants, we're opening the API to all developers. Build custom integrations, sync with your existing systems, and automate your e-commerce operations. ## What You Can Build The API opens DZBuild to developers who want to: * **Sync inventory** from your warehouse management system * **Push orders** to your CRM or ERP * **Build custom storefronts** on mobile apps or other platforms * **Embed DZBuild** in your existing website or app * **Automate workflows** with webhooks and scripts * **Track signups** from your marketing campaigns *** ## Quick Start ### Base URL ``` https://api.dzbuild.app/v1 ``` All requests use JSON. UTF-8 encoding. ### Authentication Two key types: **1. Platform Key (Server-to-Server)** Full CRUD access to your store. Use from your backend only. ``` curl https://api.dzbuild.app/v1/whoami \ -H "Authorization: Bearer dzpk_live_." ``` **2. Public Key (Browser / Client-Side)** HMAC-signed requests for signup tracking and event logging. Safe to embed in frontend code. ### Create Your First Key Dashboard → **Settings → API** ([`/dashboard/api`](https://dzbuild.com/dashboard/api)) → **Generate key** — available to the store owner on an Enterprise plan; the secret is shown once, at creation. Default scopes (platform key): * `store:read`, `store:write` * `products:read`, `products:write` * `orders:read`, `orders:write` * `customers:read` * `landing_pages:read`, `landing_pages:write` * `webhooks:read`, `webhooks:write` * `usage:read` *** ## What's in v1 ### Core Resources | Resource | Endpoints | Description | | ----------------- | ------------------------------------ | ----------------------------------- | | **Store** | `GET /v1/store` | Store settings, metadata, plan info | | **Products** | `GET/POST/PATCH/DELETE /v1/products` | Full product catalog CRUD | | **Orders** | `GET/PATCH /v1/orders` | Read orders, update status | | **Customers** | `GET /v1/customers` | Customer list and details | | **Landing Pages** | `GET/POST /v1/landing-pages` | Read and create landing pages | | **Keys** | `GET/POST /v1/keys` | Manage API keys programmatically | | **Usage** | `GET /v1/usage` | API usage stats, rate limit info | | **Quotas** | `GET /v1/quotas` | Plan limits and current usage | ### Public-Key Endpoints For high-volume client-side tracking: | Endpoint | Use Case | | ------------------ | ------------------------------------------------- | | `POST /v1/signups` | Track user signups from your platform | | `POST /v1/events` | Log custom events (page views, add to cart, etc.) | These endpoints return `202 Accepted` immediately. Events are queued and processed asynchronously — your client doesn't wait. ### Webhooks Subscribe to real-time events: | Event | When It Fires | | ------------------- | --------------------------------- | | `order.created` | New order placed | | `order.confirmed` | Order confirmed by merchant | | `order.shipped` | Order handed to courier | | `order.delivered` | Order delivered to customer | | `order.cancelled` | Order cancelled | | `signup.counted` | New signup tracked via public key | | `product.stock_low` | Product stock below threshold | ### Example: Create a Product ``` curl -X POST https://api.dzbuild.app/v1/products \ -H "Authorization: Bearer $DZ_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "name": "Cotton T-Shirt", "price": 1500, "description": "100% cotton, made in Algeria", "sku": "TS-COT-001", "stock_quantity": 50, "track_stock": true, "status": "active" }' ``` Response: ``` { "data": { "id": 42, "name": "Cotton T-Shirt", "slug": "cotton-t-shirt", "pricing": { "price": 1500, "compare_price": null, "cost_price": null }, "inventory": { "sku": "TS-COT-001", "track_stock": true, "stock_quantity": 50, "low_stock_alert": 5 }, "status": "active", "created_at": "2026-04-30 14:22:10" }, "meta": { "request_id": "abc123def4", "api_version": "v1" } } ``` ### Example: List Orders ``` curl 'https://api.dzbuild.app/v1/orders?status=pending&limit=10' \ -H "Authorization: Bearer $DZ_KEY" ``` Response: ``` { "data": { "items": [ { "id": 1287, "order_number": "ORD-13-20260430-AD3C", "status": "pending", "payment_status": "pending", "payment_method": "cod", "total": 3500, "customer_name": "Ahmed Benali", "customer_phone": "0555123456", "wilaya_id": 16, "commune": "Bab Ezzouar", "delivery_type": "home", "created_at": "2026-04-30 10:15:00" } ], "next_cursor": "MTI4Ng", "has_more": true }, "meta": { "request_id": "def456abc7", "api_version": "v1" } } ``` *** ## How Requests Behave The API is served from a global network, so latency stays low wherever you call from. **What that means for your integration:** * **Authenticated before anything else** — A request without a valid key (or, for public keys, a valid HMAC signature) is rejected outright with `401` * **Rate limited per key** — See the limits below; exceeding them returns `429` with `retry_after` * **Cached reads** — Safe `GET` responses may be served from cache for up to 30 seconds * **Queued writes** — High-volume endpoints (`/v1/signups`, `/v1/events`) return `202 Accepted` immediately and finish processing asynchronously ### Response Envelope Every response follows the same shape: **Success:** ``` { "data": { ... }, "meta": { "request_id": "req_abc123", "api_version": "v1" } } ``` **Error:** ``` { "error": { "code": "not_found", "message": "Product with ID 999 not found" }, "meta": { "request_id": "req_abc123", "api_version": "v1" } } ``` *** ## Rate Limits | Plan | Requests/min | Requests/month | Signups/month | Webhooks/month | | ---------- | ------------ | -------------- | ------------- | -------------- | | Free | 30 | 10,000 | 100 | 1,000 | | Pro | 300 | 500,000 | 5,000 | 50,000 | | Pro + API | 1,200 | 5,000,000 | 50,000 | 500,000 | | Enterprise | 6,000+ | Unlimited | Unlimited | Unlimited | Rate limits are **per-key**, sliding window of 60 seconds. Exceeding limits returns `429 Too Many Requests` with `retry_after` in the error response. *** ## Idempotency All write operations (`POST`, `PATCH`, `DELETE`) require an `Idempotency-Key` header. This prevents duplicate operations if a request is retried. ``` -H "Idempotency-Key: $(uuidgen)" ``` Use any unique string. We recommend UUID v4. *** ## Pagination All list endpoints use **cursor-based pagination**. No offset pagination (it's slow and inconsistent with real-time data). ``` GET /v1/products?limit=50&cursor=eyJpZCI6MTAwfQ ``` Response includes `next_cursor` and `has_more`. Pass `next_cursor` to get the next page. *** ## SDKs and Libraries We're starting with raw HTTP. Official SDKs coming soon: * JavaScript/TypeScript * Python * PHP * Go In the meantime, use `curl`, `fetch`, `axios`, or any HTTP client. *** ## Getting Started 1. **Read the API Reference** — Full documentation at `/api-docs/intro` 2. **Generate a Key** — Settings → API ([`/dashboard/api`](https://dzbuild.com/dashboard/api)) 3. **Test with `curl`** — Try `GET /v1/whoami` to verify your key works 4. **Build something** — Create an integration, sync your data, automate workflows *** ## Real-World Examples ### Sync Products from CSV ``` import csv import requests API_KEY = "dzpk_live_xxx.yyy" BASE_URL = "https://api.dzbuild.app/v1" with open('products.csv') as f: reader = csv.DictReader(f) for row in reader: requests.post( f"{BASE_URL}/products", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", "Idempotency-Key": row['sku'] }, json={ "name": row['name'], "price": int(row['price']), "sku": row['sku'], "stock_quantity": int(row['stock']), "status": "active" } ) ``` ### Webhook Handler ``` // Express.js — verify the X-DZ-Signature HMAC, then dispatch on `event`. import crypto from 'node:crypto'; import express from 'express'; const app = express(); const SECRET = process.env.DZBUILD_WEBHOOK_SECRET; app.post('/webhooks/dzbuild', express.raw({ type: 'application/json' }), // we need the RAW body for HMAC (req, res) => { const ts = req.get('X-DZ-Timestamp'); const sig = req.get('X-DZ-Signature'); if (!ts || !sig) return res.status(401).end(); if (Math.abs(Math.floor(Date.now()/1000) - Number(ts)) > 300) return res.status(401).end(); const bodyHash = crypto.createHash('sha256').update(req.body).digest('hex'); const expected = crypto.createHmac('sha256', SECRET).update(`${ts}.${bodyHash}`).digest('hex'); if (expected.length !== sig.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) { return res.status(401).end(); } const evt = JSON.parse(req.body.toString('utf8')); switch (evt.event) { case 'order.created': handleNewOrder(evt.data); break; case 'order.shipped': sendShippingNotification(evt.data); break; } res.status(200).end(); }); ``` The signature scheme is `hmac_sha256(secret, timestamp + "." + sha256(body))`. See [Verifying signatures](https://dzbuild.com/api-docs/webhooks/verifying-signatures.md) for code in PHP, Python, and Go. *** ## Support * **API Docs:** [`/api-docs/intro`](https://dzbuild.com/api-docs/intro.md) * **Email:** `support@dzbuild.com` * **Telegram:** [@dzbuild](https://t.me/dzbuild) * **Response time:** 24-48 hours for technical questions *** ## Pricing API access is included in all plans: * **Free:** 10K requests/month, 100 signups/month * **Pro:** 500K requests/month, 5K signups/month * **Pro + API:** 5M requests/month, 50K signups/month, priority support * **Enterprise:** Unlimited, dedicated support, custom SLA *** ## What's Next This is v1. Already planned for the next minor releases: * **v1.1:** `PATCH /v1/store`, product combinations on `/v1/products/{id}`, presigned upload URLs for product images, order refunds endpoint. * **v1.2:** Official Node.js and Python SDKs. * **v1.3+:** Bulk operations and additional webhook events, driven by merchant feedback. **What do you want to see?** Email `support@dzbuild.com` with feature requests. *** ## Start Building The API is live. Generate your key and make your first request today: ``` curl https://api.dzbuild.app/v1/whoami \ -H "Authorization: Bearer YOUR_KEY" ``` Full API reference: **[/api-docs/intro](https://dzbuild.com/api-docs/intro.md)** Happy building! 🚀