Getting started with a SaaS App

This guide describes the implemented setup sequence. Marketplace remains disabled in the current release policy; use only an explicitly enabled, authorized test environment.

1. Create a developer account

Register in the authenticated Developer Console. A developer account has its own active or suspended lifecycle and is not a merchant role. Account availability depends on the Marketplace feature being enabled for the environment.

2. Create the app and first version

Create a stable app slug and bilingual listing. Add a semantic app version containing exact redirect URIs, requested scopes, declared webhook event names, and bilingual release notes. Request only scopes backed by a public capability your app actually uses.

3. Submit for review

Submit the version. Review is per version. Super Admin may approve or reject it, then publish an approved version. Support can inspect review data but cannot approve, reject, publish, suspend, or install on behalf of a merchant.

4. Test safely

Use the repository's local fixture model and synthetic merchant data. An external hosted sandbox is PLANNED. Do not use production tokens, merchant records, or provider credentials for development. Verify tenant isolation, negative scope cases, pagination, rate limiting, and webhook signature handling.

5. Install and authorize

Start the documented GET authorization journey. A merchant Owner or Admin signs in, selects an eligible store and approves a subset of the exact reviewed version's scopes. Exchange the returned one-use code with S256. Release enablement remains PARTIAL; use an authorized test setup and the public OAuth contract, never private RPCs.

6. Make the first API request

After an authorized test installation produces an access token, send it from your server as Authorization: Bearer <ACCESS_TOKEN>. Start with one of the eleven documented API v1 operations. There is no client secret. Store access and refresh tokens server-side and redact them from logs.

curl --request GET \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://example.com/api/v1/catalog/products?limit=25"

7. Add webhooks only when needed

The creation response returns a signing secret once; save it securely. Use only the resource events declared by the reviewed version and approved by the merchant. See the Webhooks reference for payloads, retries and the bounded final uninstall receipt. Private release acceptance remains pending.