Submitting your app for review

Zid reviews every app before it goes live in Zid App Market. This page covers everything that has to be in place, what reviewers check, and the mistakes that most often get an app rejected.

This page applies to OAuth apps published in Zid App Market. Private apps are not listed in the market and do not go through review.

Throughout this page we use an imaginary app, StockSync, as the example.

Part 1: Your account

These are set once and apply to every app you publish. Your app cannot be submitted until all three are complete.

1. Partnership details

Partner Dashboard → Partnership → Onboarding

Onboarding is a three-step wizard: Authorized Member → Contact Info → Business Details.

First choose your business type, because it changes what you have to provide.

If you are a company

Field	Requirement
Company name (Arabic)	Required
Company name (English)	Required
Commercial Registration Number	Required — Saudi CR numbers must be exactly 10 digits
CR Certificate	Required — PDF, JPG or PNG, up to 5 MB
Is your company VAT-registered?	Required for companies resident in Saudi Arabia
VAT Registration Number	If VAT-registered — 15 digits, starting and ending with 3
VAT Certificate	PDF, JPG or PNG, up to 5 MB
Country, City	Required
Address Line 1, Building Number, District	Required
Postal Code	Required — 5 digits
Address line 2	Optional
Work field, Customer count	Optional

If you are an individual

Field	Requirement
ID document	Required — PDF, JPG or PNG, up to 5 MB
Freelancer document	Optional
Country, City	Required
Address fields	Optional

Document verification is separate from review. Your documents carry a verification state shown at the top of the Partnership page. Until finance verifies them, payouts cannot be settled — but an unverified state does not block you from submitting an app.

2. Contact people

Partner Dashboard → Partnership → Onboarding → Contact Info

Field	Requirement
Partnership Officer — Full Name (Arabic)	Required
Partnership Officer — Full Name (English)	Required
Partnership Officer — Email Address	Required
Partnership Officer — Mobile Number	Required — format `+966 5X XXX XXXX`
Add a Financial Officer	Optional toggle — a separate person who receives financial correspondence

Keep these current. They are the channel Zid uses to reach you about your review, and a stale email is a common reason a review stalls with no reply.

3. Bank account

Partner Dashboard → Payments → Bank Account
/partner/{id}/bank-account

Required before submission, even if your app is free — a free app can add paid plans later, and the account has to exist first.

Field	Requirement
Bank name	Required
Account holder name	Required
Country	Required — detected from your IBAN if you leave it blank
IBAN	Required if your country uses IBAN. Letters and digits only, validated
SWIFT / BIC code	Always required — 8 or 11 characters, letters and digits only
Account number	Shown instead of IBAN if your country does not use IBAN — 4 to 17 characters
Routing number	Required for US banks
Tax document	PDF, PNG or JPEG, up to 5 MB

Your VAT answer and your tax document must agree. You declare whether you are VAT-registered in Partnership → Business Details, while the certificate is uploaded on the Bank account page, where the field is labelled optional. Reviewers check the two against each other, and a mismatch is one of the most common finance flags.

4. Sign the partnership agreement

Partner Dashboard → Partnership → agreements

Each app needs a signed agreement before it can be submitted. You can preview the agreement before signing.

An unsigned agreement blocks submission. This is the single most common reason a submission is turned away before review even begins.

Part 2: Your app listing

Partner Dashboard → Apps → Create application.

Step 1: Choose the app type


Public app	Published to Zid App Market. Merchants discover, install and rate it. Requires review before going live
Private app	Offered to a single merchant store by invitation. Not reviewed, not listed

Choose Public app.

Step 2: Name and categorise it

Only four things are asked here. Everything else is edited after the app exists.

Field	Requirement
App name (Arabic)	Required — 3 to 24 characters, must contain Arabic, unique across the market
App name (English)	Required — 3 to 24 characters, must not contain Arabic, unique across the market
Category	Required
Tags	Optional

Categories are grouped into Marketing & Growth, Sales & Conversion and Operations & Store Management. Pick the one a merchant would browse to find you.

Step 3: The app editor

Your app opens on a six-tab editor, and its status starts as Draft:

General settings · App details · Webhooks · Plans · Publish · Activation

General settings

Holds your API keys (OAuth 2.0 endpoint, Client ID, Client secret) and the Developer Bridge for testing your OAuth flow before going live.

Below that are Scopes. Each group offers up to three levels — None, Read, Read and Write — and groups with a single available level are selected automatically and cannot be changed.

Then the justification field, labelled "Why does your app need these scopes?" — see Justifying your scopes for what reviewers expect in it:

Briefly explain (50–200 characters) why your app needs the selected scopes — reviewers use this to validate the request.

The same tab also holds Embedded experience (run your app inside the dashboard sidebar instead of a new tab) and Storefront snippets (HTML or JavaScript injected at well-known storefront events).

App details

Everything merchants see in your listing.

Basic info

Field	Requirement
App name (Arabic / English)	As above
Developer name (Arabic)	Required — Arabic letters and spaces only
Developer name (English)	Required — Latin letters, spaces and hyphens only
App URL	Required — must start with `https://`
Video URL	Optional — public YouTube link only, other providers are not supported
Category, Tags	Category required

Application links

Field	Requirement
Application website	Optional — your public marketing site, if different from the App URL
Redirection URL	Required — where Zid sends merchants after install to start the OAuth flow
Callback URL	Required — where Zid returns the OAuth code after the merchant authorizes your app
Maintainer email	Required — reviewers and Zid support reach you here

Support & Policies

Field	Requirement
Phone number	Required if no support channel URL
Support channel URL	Required if no phone number — WhatsApp, Telegram or a support portal are all accepted
FAQ URL	Optional
Privacy policy URL	Required for review

A WhatsApp or Telegram link is fine as your support channel. It is not acceptable as your privacy policy — that must be a real policy page.

Descriptions

Field	Limit
Short description (Arabic / English)	100 characters each
Description (Arabic / English)	4,000 characters each

App icon — PNG or JPG, exactly square (1:1), maximum 250 × 250 pixels, up to 2 MB.

Screenshots — up to 10 each, PNG or JPG.


Screenshots (Arabic)	Required. You cannot save your listing without at least one
Screenshots (English)	Optional — shown to merchants viewing your listing in English

Testing before you submit

At the bottom of App details is Development store. Install your app on one of your development stores and walk the merchant experience yourself before sending it to review.

Plans

Public plans and private plans sit on separate tabs. You can offer up to eight public plans.

Each plan is Free, Recurring or Usage-based, and takes a name and description in both languages (300 characters each) plus 1 to 5 features, where every feature row has an Arabic and an English variant. If you charge by consumption, read Usage-based plans first — an app cannot mix usage-based and recurring plans. Custom pricing for a single merchant is covered in Private plans.

See Creating a plan for every field and limit, and Plans and pricing for choosing between the models. Before review, your app needs either a free plan or a paid plan with a free trial so reviewers can test it.

Webhooks

Events are organised into webhook groups. Each group sends every event you select to the same HTTPS endpoint with the same headers.

See Subscription and app events for the full event list, when each one fires, and both payload shapes.

Step 4: Submit

The Publish tab shows your current status and the submit button. Zid's description of what happens next:

When you're ready, send this app to our reviewers. They will check the listing details, scopes, and webhooks before publishing it to the App Market.

Your app moves through these states:

State	Meaning
Draft	Not yet submitted. Only you can see it
Request to publish	Submitted, waiting for review
Published	Live in the market
Rejected	Not approved. Zid sends you the reason
Unpublished	Was live, now withdrawn

You can pull a published listing back to draft at any time to make changes.

Part 3: What reviewers check

Reviewers work through the same nine checks on every app.

1. Names

Your Arabic and English names must each read as a real product name in that language. A placeholder, an internal code name, or a name that is really a company abbreviation will be sent back — this includes the developer name, which merchants see on your listing.

2. URLs

Every URL has to be a real, public, production address.

No test or staging hosts. A redirect or installation URL pointing at a sandbox, a proxy, or a -test hostname is rejected.

The privacy policy must be a real privacy policy page. A link to a chat app, a social media profile, or a PDF in a file-sharing folder does not qualify.

Everything must still resolve over HTTPS with current TLS at review time, not only when you first saved it.

3. Screenshots

Arabic screenshots are required. Reviewers look for screenshots that show your app actually working inside the merchant's dashboard — not a marketing banner, not your own website, not an empty state.

4. Category

Your category must match what the app does, because it determines where merchants find you.

5. Descriptions

Both descriptions must explain, in their own language, what a merchant does with your app. Two common rejections:

One vague sentence per language that never says how the app is used.

A description that promises features your app cannot deliver, because the scopes for them were never requested. Reviewers read your description against your scopes — if you describe pushing products and stock, you need the matching write scopes.

Also check the small things: a description that begins with a stray character, or an Arabic field containing English, gets flagged.

6. Scopes

This is the most common cause of rejection. Reviewers compare every scope against your features. Requesting write access for a read-only app, or scopes for features you do not have, fails the review. Justifying your scopes covers what your description has to show.

A read-only analytics app requesting write scopes across the platform will be rejected outright.

7. Plans

Your pricing must match what you charge everywhere else.
If your app is sold on other platforms, or priced on your own website, your Zid plans must match that pricing. A different price on Zid is not accepted.

Also checked:

Every plan has a description in both languages. An empty English plan description is a rejection.

No stray characters at the start of a plan name or description.

No leftover test plans in the list.

Creating a plan lists every field and limit.

8. Webhook events

A paid app with no webhook subscriptions gets questioned, because it has no way to know when a merchant's subscription changes. Reviewers look for the full subscription lifecycle, not just the happy path — an app that handles only activation, renewal and expiry, but ignores suspension, warning, upgrade and refund, will be asked to complete the set.

Free apps are not expected to subscribe to subscription events. The full list, with the timing of each event, is in Subscription and app events.

9. Bank account and agreement

Bank account present, with tax status matching the uploaded document.

Partnership agreement signed.

Commercial terms agreed with your partnership manager.

10. Your OAuth and activation flow

Reviewers install your app on a test store and walk it exactly as a merchant would. How your app connects is as reviewable as what your listing says, and it is a frequent cause of rejection — the full rules are in Public Apps OAuth Requirements.

Your app must start OAuth the moment the merchant clicks Activate. Any paid Zid plan is settled before that point, so nothing should stand between Activate and the consent screen.

Three flows are rejected outright:

Rejected flow	What to do instead
Signup or login before OAuth — the merchant hits your registration form before they ever see Zid's consent screen	Start OAuth immediately, then link the account after the callback
Generic homepage or manual discovery — the merchant lands on your marketing site or settings area and has to go hunting for the Zid integration	Open OAuth directly, or your approved dedicated setup journey
Manual credentials or manual store identification — asking the merchant to paste tokens, API keys, client secrets, a Store ID or a store URL	Identify the store automatically through OAuth and exchange the code on your server

Also checked while the reviewer walks your app:

The connection survives setup. The verified store must not switch or get lost during signup, login, configuration or account linking, and the merchant must never have to restart activation to recover it.

Accounts are never linked on a matching email alone. Authenticate the external account and confirm the store-to-account association explicitly.

Nothing leaks. Access tokens, refresh tokens, client secrets and authorization codes must stay off page content, URLs, client-side storage, analytics and logs.

"Ready" means ready. Don't show a service-ready state, or start background syncing, while mandatory setup is still incomplete.

Denial is handled. If the merchant cancels, your callback is never called at all — Zid returns them to their dashboard with an error_code. Treat "activation started, no callback arrived" as a normal outcome, and make sure a retry doesn't create a duplicate connection.

Two implementation details that fail reviews quietly:

The authorization code lasts 10 minutes and works once. Exchange it inside the callback request. Queuing it for a background worker, or retrying after a failed exchange, both break.

PKCE is not supported. Zid's Authorization Code flow is for confidential clients. code_challenge and code_verifier are ignored, so your protection against request forgery is the state parameter — generated per request, bound to the session, and validated before you accept the callback.

And one that breaks apps after they go live: when you add a scope, each merchant re-approves by deactivating and reactivating your app. That issues a new token pair for a store you already have. If your app treats a known store as a duplicate install and discards the new tokens, it stays broken — and to the merchant it looks like the re-approval simply failed.

If your service genuinely needs setup before a store can be connected, there is an exception path — Partner-managed setup — but it needs Zid's prior written approval. Removing your Zid plans does not grant it.

Errors the dashboard will show you

Some problems are caught before you ever reach a reviewer. The three you are most likely to meet:

"The justification must be at least 50 characters." — your scope description is too short. The counter under the field shows your length out of 200.

"URL must start with https://." — every URL field rejects plain HTTP inline, before saving.

"Add at least one screenshot." — saving App details is blocked until you have at least one Arabic screenshot.

Beyond these, each URL is checked live over TLS 1.2 or 1.3 with a five-second timeout when you save. A URL that is unreachable, or serving an expired or outdated certificate, fails.

Common reasons apps get rejected

In rough order of how often they come up:

Scopes that do not match the app. Write access on a read-only app, or scopes for features that do not exist.

An activation flow that does not start with OAuth — a signup gate, a generic homepage, or a form asking the merchant to paste credentials.

Unsigned partnership agreement.

Test or non-production URLs in the redirect or installation fields.

A privacy policy that is not a privacy policy — a chat link, a social profile, a shared file.

Thin descriptions that never explain how a merchant uses the app.

Pricing that differs from the partner's own website or another platform.

Missing plan descriptions, usually the English one.

Incomplete webhook coverage on a paid app.

10.

Stray characters at the start of a name or description, or the wrong language in a language-specific field.

11.

Missing or mismatched bank and tax details.

Before you submit

Partnership details complete, with documents uploaded

Partnership officer details are up to date, and the email is one you actually monitor — it is how Zid reaches you about the review

Bank account saved, and your VAT answer matches the certificate you uploaded

Partnership agreement signed

Both app names read as real product names, and so does the developer name

Every URL is production, HTTPS, and live

At least one support channel: phone number or support URL

Arabic screenshots show the app working inside the dashboard

Both descriptions explain how merchants use the app

Every scope is used by a feature that exists today

Plan prices match your website and any other platform you sell on

Every plan has an Arabic and English description

A free plan or a free trial exists so reviewers can test

Webhook events cover the whole subscription lifecycle

Activation starts OAuth immediately — no signup gate, no homepage detour, no pasted credentials

A cancelled authorization, a retry and a reinstall all leave your app in a correct state

Reactivation after a scope change overwrites the stored tokens instead of discarding them

No test plans, test URLs or placeholder text anywhere

Documentation you'll need

Before you build

Start Here — the platform in overview

Create your First App — the walkthrough

Connecting your app

Public Apps OAuth Requirements — the activation and security rules reviewers apply

Authorization — the OAuth technical reference

OAuth Errors & Troubleshooting — error codes, denial handling, the consent lifecycle

Zid Bridge Tool — test your authorization flow before going live

Pricing and billing

Plans and pricing — the models available and how to choose

Creating a plan — every field and limit

Usage-based plans — charging for consumption

Private plans — custom plans for one merchant

Subscription Details — read a merchant's current subscription

Update Usage-Based Charges — post a usage charge

Scopes and permissions

Justifying your scopes — what reviewers expect in your description

Reacting to merchants

Subscription and app events — install, uninstall and the subscription lifecycle

Webhooks — store data webhooks, which are a separate system

Building the experience

Embedded Apps — running inside the merchant dashboard

StoreFront Events — hooks available on the storefront

Zid MUI — Zid's component library

Zid SDKs — official client libraries

Working with the APIs

Responses — the response envelope and error shapes

Rate Limiting — the limits your app has to respect

Merchant APIs — everything your app can read and change

Submitting your app for review

Part 1: Your account#

1. Partnership details#

2. Contact people#

3. Bank account#

4. Sign the partnership agreement#

Part 2: Your app listing#

Step 1: Choose the app type#

Step 2: Name and categorise it#

Step 3: The app editor#

General settings#

App details#

Testing before you submit#

Plans#

Webhooks#

Step 4: Submit#

Part 3: What reviewers check#

1. Names#

2. URLs#

3. Screenshots#

4. Category#

5. Descriptions#

6. Scopes#

7. Plans#

8. Webhook events#

9. Bank account and agreement#

10. Your OAuth and activation flow#

Errors the dashboard will show you#

Common reasons apps get rejected#

Before you submit#

Documentation you'll need#