Frequently asked questions
What is a DZBuild app?
A DZBuild app is a service you run on your own servers. A store owner installs it from their DZBuild dashboard through an OAuth 2.0 consent screen, and your server then reads and changes that store's data through the REST API at https://api.dzbuild.app/v1. None of your code runs on DZBuild. Core concepts describes apps, installs, stores and tokens.
Who can build a DZBuild app?
Any DZBuild account that owns a store can open the developer console, register up to 10 apps and test them on its own stores. Other merchants can install an app after DZBuild reviews and approves it. Get started walks through the first app.
Which store plans can install an app?
Every plan, from Free to Enterprise. The Enterprise plan requirement that applies to merchant API keys does not apply to app install tokens. A developer can set a minimum plan on the app; stores below it cannot install it and get a 403 app_plan_required answer. See plans and min_plan.
Do install tokens expire?
No. The token endpoint returns no expires_in and no refresh token. A token works until the merchant uninstalls the app, which revokes it, or installs the app again on the same store, which replaces it. See token lifetime and revocation.
How do I test an app before it is approved?
A new app is a draft and runs in test mode: it installs only on stores your own account owns, with real data. Register an https redirect URI, deploy the app to a workers.dev address (or run an https tunnel), install the app on your store from the authorize URL and call GET /v1/whoami with the token. The steps are on the Get started page.
Can my app send WhatsApp messages to buyers?
Yes, with the whatsapp:send scope. Your app sends the order templates that Meta approved for DZBuild, in Arabic or French, and each message costs one credit from the store's WhatsApp wallet. Free text and custom templates are not available. See the WhatsApp API.
Which webhook events does DZBuild send to apps?
order.created, order.confirmed, order.processing, order.shipped, order.delivered, order.cancelled and order.returned, plus app.uninstalled and the webhook.verify request from the console. Order events need the orders:read scope because the payload carries the buyer's name, phone and address. Every request is signed with X-DZ-Signature. See Webhooks.
Can a Worker on workers.dev receive webhooks?
No. DZBuild refuses webhook URLs on workers.dev. Put the Worker on a domain you own on your Cloudflare account, or poll GET /v1/orders?since= once a minute for new orders, which is what the Order notifications preset does.
What does the DZBuild app review check?
The listing (name, logo, descriptions in English, Arabic and French, homepage, support email), the redirect URIs, the requested scopes against what the listing says, the webhook URL and its verification, the developer account, the test installs and the security rules: exact redirect URIs, secrets kept server side, verified signatures, data deletion after uninstall, no scraping and answered support email. The review guidelines list what the console requires before you can submit.
Can an app manage API keys or webhooks through the API?
No. /v1/keys, /v1/webhooks and /v1/changes answer 403 with the message Apps cannot use this endpoint to any install token. The app's webhook URL is set once in the developer console and receives the events of every store that installs the app. See endpoints closed to apps.
Can I use these docs with an AI coding assistant?
Yes. Every page has a Markdown twin at the same URL plus .md, the index is https://dzbuild.dev/llms.txt, the whole site is https://dzbuild.dev/llms-full.txt, and an agent skill at https://dzbuild.dev/skills/dzbuild-apps/SKILL.md carries the rules an assistant needs. The OpenAPI description for apps is at https://dzbuild.dev/openapi/dzbuild-apps-v1.json. Build with AI agents explains how to use them.