Core concepts

Apps

An app is the record you create in the developer console. It holds your credentials, your redirect URIs, the scopes you may request, your webhook settings and a minimum plan. Each app has one status:

Status	Who can install it	What happens to existing installs
draft	Only the developer, on stores the developer account owns	Tokens work on the developer's own stores
in_review	Only the developer, on stores the developer account owns	Tokens work on the developer's own stores. An approved app sent back to review after an edit keeps every existing install working.
approved	Any store owner	Tokens work
rejected	Nobody	Every call answers 403 with app_suspended
suspended	Nobody	Every call answers 403 with app_suspended

DZBuild reviews an app after you submit it from the console. The review guidelines list what the review checks.

Test mode

A draft or in-review app runs in test mode. The consent screen accepts it only for the developer who owns it, and only for stores that account owns. This lets you build and test the whole flow before review, with real data from your own store.

The API applies the same rule on every call. If an app has not been approved yet and the install belongs to someone other than the developer, the call answers 403 with app_not_approved and the message This app is in test mode and only runs on its developer's stores.

Stores

A store is one DZBuild shop, with its own products, orders and plan. One merchant account can own several stores.

• Only the store owner can install an app. The consent screen lists only the stores the logged-in account owns, so a team member cannot pick a store they work on.
• One consent can cover up to 10 stores. Each store gets its own install and its own token.
• A token reads and writes only the store it was issued for. The token response lists every installed store in stores, and repeats the first one at the top level.

Installs

An install links one app to one store. There is at most one install per app and store.

The merchant starts an install from the Extensions page of their dashboard. The Install button opens your homepage URL, or your launch URL when no homepage is set, in a new tab. DZBuild does not send the merchant to the authorize URL for you, so that page must start the OAuth flow.

• The install is created when your server exchanges the code at the token endpoint, not when the merchant clicks approve.
• If the merchant installs your app again on the same store, the install keeps its install_id. DZBuild issues a new token, revokes the old one and stores the scopes from the latest consent.
• Only the merchant can uninstall, from your app's page in their dashboard. There is no revoke endpoint for apps.

When a merchant uninstalls your app, DZBuild does four things at once: it marks the install as uninstalled, revokes the token, drops the webhook deliveries still waiting for your endpoint, and queues one app.uninstalled event if your endpoint is verified and active. From then on the old token answers 401.

Plans and min_plan

DZBuild stores are on one of four plans, from lowest to highest: free, pro, unlimited, enterprise. Any plan can install an app. The Enterprise plan requirement for merchant API keys does not apply to install tokens.

You can raise the bar with min_plan in the console. It defaults to free, which allows every store.

• On the consent screen, a store below min_plan is shown as not eligible and cannot be picked.
• On every API call, a store below min_plan answers 403 with app_plan_required and a message that names the plan, for example This app requires the Pro plan.
• A paid plan that has expired counts as free in both checks.

Per-install rate limit

Each install has its own budget of 120 requests per minute. The window is a fixed calendar minute, so the counter resets at the start of each minute.

The install budget is checked first. After it, the request also counts against the store's shared per-minute budget, which the merchant's own keys and other apps use too. A runaway app hits its own limit before it can use up the store's.

Over the limit, the API answers 429 with a Retry-After header and this body:

{
  "error": {
    "code": "rate_limited",
    "message": "Per-minute API limit exceeded for this app install",
    "retry_after": 42
  },
  "meta": {
    "request_id": "5f2c9a0b1d3e4f60",
    "api_version": "v1"
  }
}

If the store budget runs out first, the message is Per-minute API limit exceeded for this store. Rate limits explains how to back off.

Install tokens

An install token is the bearer token your server receives from the token endpoint. It is an API key of the same kind a merchant creates, marked as belonging to your install.

What an install token is:

• A bearer token that starts with dzpk_live_, sent as Authorization: Bearer ....
• One token per install, so one per store.
• Limited to the scopes the merchant approved, checked by the same scope rules as every other key.
• Reported as rate_limit_tier: enterprise by GET /v1/whoami on any plan, with the per-install limit above as the real budget.
• Valid with no expiry date. The token endpoint returns no expires_in and no refresh token.
• Revoked when the merchant uninstalls your app, and replaced when the merchant installs it again.

What an install token is not:

• It is not a merchant key. It does not appear on the merchant's API keys page and does not count toward the merchant's key limit.
• It cannot manage keys, webhooks or the change log. Calls to /v1/keys, /v1/webhooks and /v1/changes answer 403 with the code forbidden and the message Apps cannot use this endpoint.
• It is not tied to a person's session. It keeps working when the merchant logs out.
• It does not cover several stores. Use the token issued for each store.

Every refusal that is specific to apps answers 403 with the error envelope:

Code	Message	Cause
app_uninstalled	This app is no longer installed on this store	The install is no longer active
app_suspended	This app has been suspended by DZBuild	The app is suspended or rejected
app_not_approved	This app is in test mode and only runs on its developer's stores	The app has not been approved yet and the store owner is not the developer
app_plan_required	This app requires the Pro plan (the plan name varies)	The store is below min_plan