App Lifecycle

App statuses

Every Bazex app goes through these statuses:

If your app is rejected during review, it returns to DRAFT status with reviewer notes explaining what needs to change.

Step 1: Create your app

Sign in to the developer portal at admin.bazex.co and navigate to Developer → My Apps → Create App.

You'll need to provide:

After creation, you receive your Client ID and Client Secret (prefix: fbcs_). Store the Client Secret securely — it's only shown once.

Step 2: Test in sandbox

Every developer account has an automatically provisioned sandbox business for testing. You can install your DRAFT app on this sandbox without going through review.

curl -X POST https://api.bazex.co/developer/apps/APP_ID/test-install \
  -H "Authorization: Bearer YOUR_JWT"

{
  "installationId": "clx1install789",
  "accessToken": "fbat_test_abc123...",
  "webhookSecret": "whsec_test_def456...",
  "businessId": "clx1sandbox123",
  "isTestInstall": true
}

You can also test-install from the developer portal UI. The portal shows a "Test Installation" card on your app detail page with a button to install and a dialog to reveal the access token.

You can also test the full OAuth flow — the OAuth authorize endpoint supports the DEVELOPER role and will install against your sandbox business.

Managing test installs

# Check test install status
curl https://api.bazex.co/developer/apps/APP_ID/test-status \
  -H "Authorization: Bearer YOUR_JWT"

# Uninstall test
curl -X POST https://api.bazex.co/developer/apps/APP_ID/test-uninstall \
  -H "Authorization: Bearer YOUR_JWT"

Step 3: Configure your manifest

If your app uses blocks, embeds, or hooks, configure the manifest JSON in the developer portal. The manifest defines your extension points and is synced to the platform when you save. See the Extensions guide for the full manifest format.

The manifest also supports a top-level settingsSchema for global app settings that merchants can configure after installing your app.

Step 4: Submit for review

When your app is ready, click "Submit for Review" in the developer portal. This moves your app to PENDING_REVIEW status.

While in review, your app cannot be edited. If you need to make changes, you'll need to wait for the review outcome.

Review process

The Bazex team reviews your app for:

• Functionality — Does the app work as described?
• Security — Is the app handling data safely? Are signatures verified?
• Scope appropriateness — Does the app only request scopes it needs?
• Quality — Is the app description clear? Are there screenshots?
• Policy compliance — Does the app follow platform guidelines?

Approved: Your app is published to the marketplace immediately. Merchants can find and install it.

Rejected: Your app returns to DRAFT status. Check the reviewer notes for feedback on what to fix, make changes, and resubmit.

Versioning

Your app has a version field that you can update in the developer portal. When you update your app after it's been approved, the platform tracks version changes.

The system also maintains an approvedScopes snapshot — the set of scopes that were approved during the last review. This is important for scope expansion detection.

Scope expansion & re-consent

If you need additional permissions after your app is already installed by merchants, Bazex handles the re-consent flow automatically:

1. Add new scopes in the developer portal and submit the update for review
2. After approval, existing installations are flagged with needsReConsent: true
3. Merchants see a prompt to approve the additional scopes in their admin panel
4. Until re-approved, the access token only grants the original scopes. API calls requiring the new scopes will return 403.
5. After merchant approves, needsReConsent is cleared and the token grants the full scope set

Installation & uninstallation

When a merchant installs your app through the marketplace:

1. They're redirected through the OAuth flow (consent screen → authorize → token exchange)
2. An AppInstallation record is created
3. You receive an access token scoped to their business
4. Webhooks defined in your app are automatically created for that business
5. Blocks, embeds, and hooks become available in their site builder / storefront

When a merchant uninstalls your app:

• The access token is revoked — all API calls will return 401
• Webhooks for that installation are deactivated
• Blocks are removed from their site pages
• Embeds stop being injected into the storefront
• An app.uninstalled event fires internally
• After 48 hours, a business.data_erasure webhook is sent — your app must delete all stored merchant data (see Webhooks)

Managing credentials

You can regenerate your app's Client Secret from the developer portal if it's been compromised. This invalidates the old secret immediately.

Developer analytics

The developer portal provides analytics for each of your apps:

• Total installs — lifetime installation count
• Active installs — currently installed (not uninstalled)
• Webhook success rate — percentage of successful webhook deliveries
• Average webhook latency — how fast your endpoint responds
• Install trend — 30-day chart of installs and uninstalls
• Webhook delivery chart — 30-day stacked chart of successful vs. failed deliveries

You can also access analytics programmatically:

curl https://api.bazex.co/developer/apps/APP_ID/analytics \
  -H "Authorization: Bearer YOUR_JWT"

Best practices

• Request minimal scopes — merchants are more likely to install apps that request fewer permissions
• Test thoroughly — use the sandbox to test all features before submitting
• Write clear descriptions — explain what your app does and why merchants need it
• Add screenshots — visual examples help merchants understand your app
• Handle errors gracefully — if your hook times out or API returns an error, the merchant's store should still function
• Verify all signatures — always validate webhook and hook signatures before processing
• Store tokens securely — never expose access tokens or client secrets in client-side code
• Respond to webhooks quickly — return 200 within a few seconds, process events asynchronously