Test your app before you submit
Submit only when your app is ready
Start here: install your app on a development store
How to use this page
Part 1: Before you start testing
ngrok, localhost, *.vercel.app, *.supabase.co, *.railway.app, *.herokuapp.com, and any hostname beginning with dev., staging., or test.Part 2: Permissions
Your app should request as few scopes as possible. Selecting every scope during development is common, so please review your selection carefully before you submit.
Product.write, remove it.Product.read and Product.write. See Justifying your scopes.Part 3: Activation, connection, and uninstall
state value is created for every request, stored with the session, and validated before the callback is accepted. Zid does not support PKCE, so state is your only protection against request forgery.error_code. Treat an activation that begins without a callback as an expected outcome, and confirm that a second attempt does not create a duplicate connection.app.market.application.uninstall, which is the only reliable way to learn that an uninstall has taken place.store_id = 123, category_id = 14, store_url = xyz.zid.store, or currency = SAR. Every value must come from the merchant's own data.Part 4: Subscription and billing
app.market.subscription.active grants the merchant access after payment.app.market.subscription.renew continues access. This event arrives after the renewal, never before it.app.market.subscription.upgrade adjusts the merchant's features to match the new plan, whether they move to a higher or a lower one.app.market.subscription.expired and .suspended withdraw access. Confirm the merchant can no longer use paid features.app.market.subscription.refunded is handled, so the merchant does not remain on a paid plan after a refund.event_name, not status. When a merchant has no subscription, status falls back to the final part of the event name, so it cannot be relied on.Part 5: Webhooks and data
target_url is not accepted. Send it in a header instead.YOUR_WEBHOOK_SECRET with the real one.429 response, wait before retrying rather than sending the request again immediately. See Rate Limiting.Part 6: By app type
6.1 Products
6.2 Orders
order.create arrives when a merchant receives a new order.order.status.update arrives for every status change: Preparing, Ready, In delivery, Shipped, and Cancelled.order.payment_status.update arrives when payment changes between Paid and Unpaid.6.3 Messaging and notification apps
order.create sends a message.order.status.update sends a message for each status: Preparing, Ready, In delivery, Shipped, and Cancelled.order.payment_status.update sends a message for Paid and Unpaid.abandoned_cart.created sends a message.customer.create sends a message.{{customer_name}}, {{order_id}}, and {{total_amount}} take their values from the Zid payload.Hello {{customer_name}} or Hello undefined.6.4 Marketing and coupon apps
6.5 Storefront JavaScript apps
6.6 Embedded apps
embedded_apps_tokens_write scope, your app must provide an embedded experience. A mismatch between the two is one of the most common reasons an app is returned.Final checklist
| Your app is installed on a development store β we check this first, and the review cannot begin without it | β |
| Every setting points to production: keys, URLs, and webhooks | β |
| Every scope corresponds to a feature your app provides today | β |
| OAuth begins as soon as the merchant selects Activate | β |
| Installing, uninstalling, and reinstalling all work, including after a scope change | β |
| Tokens are kept separate for each store and are never exposed | β |
| Subscription events are handled β paid apps only | β |
| Webhooks arrive, and repeated events are handled safely | β |
| Arabic data and Arabic screens are both supported | β |
| No values are hardcoded | β |
| Every section above that applies to your app passes | β |
Submit your app for review
1.
2.
3.
Modified atΒ 2026-10-21 20:08:04