Versions & review

Scopes are granted per app version. A version bundles the scopes you request, a required justification for each, and your webhook topics. You submit a version for review; only an approved version can be installed, and any scope change means a new version and a new review.

Create and submit a version

Create a version, then submit it. Every entry in requested_scopes needs a non-empty string in scope_justifications.

# 1. Create the version
curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/apps/app_123/versions \
  -H "Authorization: Bearer $USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_scopes": ["catalog:read", "orders:read"],
    "scope_justifications": {
      "catalog:read": "Read products to sync your loyalty catalog.",
      "orders:read":  "Read orders to award points on purchase."
    },
    "webhook_topics": ["app/installed", "app/uninstalled", "orders/create"]
  }'
# -> { "data": { "id": "ver_…", "version": 1, "status": "draft" } }

# 2. Submit it for review
curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/apps/app_123/versions/ver_456/submit \
  -H "Authorization: Bearer $USER_JWT"
# -> { "data": { "review_case_id": "case_…", "state": "submitted" } }

Review states

A submission opens a review case that moves through a small state machine. Track it with GET /appstore/partner/review/cases/{id}.

State	Meaning
`submitted`	Received, queued for review.
`automated_checks`	Automated checks are running (redirect allowlist, webhook HMAC probe, scope sanity).
`in_review`	A reviewer is evaluating it.
`changes_requested`	The reviewer needs changes — read the case thread, address them, resubmit.
`approved`	Live. Merchants can install this version; existing installs flip to `pending_reauth`.
`rejected`	Declined. The thread explains why; fix and submit a new version.

The common path is submitted → in_review → approved. A reviewer may route to changes_requested (you act, then it returns to review) or rejected.

Message the review team

Each case carries a thread you share with the reviewer. Use it to explain design decisions, respond to changes_requested, or ask questions. Decisions are also posted to the thread as system messages, so the case is a complete record.

curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/review/cases/case_789/messages \
  -H "Authorization: Bearer $USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"body":"Narrowed the request to orders:read only — removed customers:read."}'

Scope justifications are required

A submission with a missing or empty justification for any requested scope is rejected outright. Write one concrete sentence per scope stating what your app does with it — the merchant sees this exact text on the consent screen, so it must be honest and specific.

What gets an app rejected

Over-broad scopes — requesting catalog:write when you only read, or bundling scopes “just in case.” Ask for the minimum; each scope must earn its justification.
* or agent:admin — app tokens get no super-scope elevation, so these are never valid on a version. Request the exact resource scopes instead.
Weak webhook verification — the HMAC probe sends a bad signature and expects a 401. An endpoint that accepts it fails. See Webhooks.
Redirect URIs that don’t match — the authorize redirect_uri must be in the app’s exact allowlist; wildcards or mismatches are blocked.
Vague or missing justifications — see above.
Scopes the app doesn’t use — declaring topics or scopes the integration never exercises.

Before submitting, run the flow end-to-end on your own store: install with your requested scopes, confirm every Gateway call your app makes returns 200 (not 403 FORBIDDEN_SCOPE), and confirm your webhook endpoint returns 401 on a tampered signature and 200 on a valid one.

Install flow (OAuth)

How merchants install an approved version.

Scopes

The full scope catalog.

Build an App

Create and submit a version

Review states

Message the review team

Scope justifications are required

What gets an app rejected

Next

Install flow (OAuth)

Scopes

​Create and submit a version

​Review states

​Message the review team

​Scope justifications are required

​What gets an app rejected

​Next

Install flow (OAuth)

Scopes

Create and submit a version

Review states

Message the review team

Scope justifications are required

What gets an app rejected

Next