API reference

Your app calls the same REST API that merchants use, at https://api.dzbuild.app/v1. Two references describe it, and this page covers what changes when you call it with an install token.

Two references

The API documentation on dzbuild.com explains the main resources with their parameters, responses and examples, in three languages:

• English: dzbuild.com/api-docs
• Arabic: dzbuild.com/ar/api-docs
• French: dzbuild.com/fr/api-docs

Those pages are written for merchant API keys. With an install token, the rules on this page win where they differ: any plan can use your app, the limits are in Rate limits, and some endpoints are closed to apps.

The OpenAPI description for apps is one JSON file in OpenAPI 3.1 format. It lists the 92 operations an install token can call, with their scopes, parameters and response shapes. Import it into Postman or Insomnia, or generate types from it.

Download dzbuild-apps-v1.json

curl -sO https://dzbuild.dev/openapi/dzbuild-apps-v1.json

The file declares https://api.dzbuild.app as its server. Its dzOAuth security scheme lists every scope with an English description.

Sending the install token

The token exchange gives you one access token per store the merchant approved (see OAuth). Each token starts with dzpk_live_. Send it in the Authorization header with the Bearer scheme:

curl https://api.dzbuild.app/v1/whoami \
  -H "Authorization: Bearer dzpk_live_xxxxxxxx"

The token decides the store. There is no store parameter on the requests, so to work on another store of the same merchant, use that store's token from the stores list of the token response. Keep tokens on your server. They do not expire on their own. A token stops working when the merchant uninstalls your app, or when the merchant installs it again on the same store, which replaces the token.

Status	Message	Cause
401	Missing Authorization header	No Authorization header.
401	Unsupported Authorization scheme	The header does not start with Bearer.
401	Invalid or revoked API key	The token is wrong, or it was revoked by an uninstall.

Every install token is also checked against the state of your app and of the store. A refused call answers 403 with one of these codes:

Code	Meaning
app_uninstalled	The app is no longer installed on this store.
app_suspended	DZBuild suspended the app.
app_not_approved	The app is in test mode and only runs on its developer's stores.
app_plan_required	The store's plan is below the minimum plan you set for the app.

Responses

A successful response puts the result in data. An error puts a code and a message in error. Both carry meta.request_id; quote it when you contact DZBuild about a call.

{
  "error": { "code": "forbidden", "message": "Missing scope: orders:write" },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

List endpoints answer:

{
  "data": { "items": [...], "next_cursor": "...", "has_more": true },
  "meta": { "request_id": "...", "api_version": "v1" }
}

Send next_cursor back as cursor to get the next page, and stop when has_more is false. GET /v1/orders also accepts since (orders created at or after that time), status and customer_phone.

whoami

GET /v1/whoami needs no scope. It tells you which store a token belongs to and what it may do. For an install token it adds an app object:

{
  "data": {
    "key_id": "dzpk_live_3c9e1a7f5b2d80",
    "store_id": 1234,
    "type": "platform",
    "rate_limit_tier": "enterprise",
    "pilot": true,
    "scopes": ["orders:read", "whatsapp:read", "whatsapp:send"],
    "app": {
      "app_id": 12,
      "client_id": "dzapp_4e1b9c07d2a86f35e0b1",
      "install_id": 57
    }
  },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

Field	Meaning
store_id	The store this token works on.
scopes	The scopes the merchant granted.
rate_limit_tier	Always enterprise for install tokens, whatever the store's plan.
app.app_id	Your app's id.
app.client_id	Your app's OAuth client id.
app.install_id	The install on this store. Webhook payloads such as app.uninstalled use the same id.

Endpoints closed to apps

These endpoints answer 403 to an install token, whatever its scopes:

Endpoints	Answer	Why
/v1/keys and /v1/keys/{key_id}	Apps cannot use this endpoint	API keys belong to the merchant.
/v1/webhooks and everything under it	Apps cannot use this endpoint	Your app's webhook is set once in the developer console for every store (see Webhooks).
/v1/changes and everything under it, undo included	Apps cannot use this endpoint	The change log and undo stay with the merchant.

POST /v1/landing-pages/generate needs the ai:generate scope, which apps cannot request because it spends the merchant's AI credits. It answers 403 with Missing scope: ai:generate.