Frequently Asked Questions

Getting Started

What's the difference between a Custom App and a Platform App?

Custom Apps are private integrations you create from the merchant dashboard. They're auto-installed to your store and you get API credentials immediately -- no OAuth flow needed. Use them for your own store's integrations, scripts, or testing.

Platform Apps are listed in the app marketplace and can be installed by any merchant. They use the OAuth install flow and can embed as an iframe in the dashboard. Use them when building apps for multiple merchants.

See Custom Apps for a detailed comparison.

How do I get API credentials?

For Custom Apps: Create one from Settings > Apps > Manage in the dashboard. You'll receive an access token, client ID, and client secret immediately.

For Platform Apps: Register your app with the platform admin. After a merchant installs your app, you receive credentials through the OAuth flow.

Can I test the API locally?

Yes. Use https://api-dev.selorax.io/api as the base URL for the development server. You can use the interactive API tester in this documentation to try endpoints with your credentials.

Authentication

Which auth method should I use?

Scenario	Method
Short-lived browser requests	Bearer token (`Authorization: Bearer sx_at_...`)
Background jobs, cron, server-to-server	Client credentials (`X-Client-Id` + `X-Client-Secret` + `X-Store-Id`)
Iframe embedded in dashboard	Session tokens via `postMessage`

Client credentials never expire, making them ideal for server-side integrations. Bearer tokens expire after 24 hours (OAuth) or 1 year (Custom App).

My token expired. How do I get a new one?

OAuth tokens: Use the refresh token to obtain a new access token without requiring the merchant to re-authorize.

Custom App tokens: Regenerate from Settings > Apps > Manage in the dashboard.

What does "insufficient_scope" mean?

Your app doesn't have the permission required by the endpoint you're calling. For example, calling /api/apps/v1/orders requires the read:orders scope. Check the scope required for each endpoint in the API Reference.

API Usage

What are the rate limits?

Scope	Limit
All `/api/` routes	1,000 requests/minute
`/oauth/token`	10 requests/minute
`/session/verify`	300 requests/minute

When you exceed a limit, the API returns HTTP 429 Too Many Requests. Wait for the rate limit window to reset before retrying.

How does pagination work?

All list endpoints use offset-based pagination with page and limit query parameters. The response includes a pagination object with the total count:

{
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 230
  }
}

Calculate total pages: Math.ceil(total / limit). Maximum limit is 250.

Can I filter and sort results?

Yes. Each list endpoint supports filters specific to the resource:

Orders: status, since, until, customer_id, sort
Products: status, since, category_id, price_min, price_max, search, sort

Filters combine with AND logic -- all specified conditions must match. See the Orders API and Products API for details.

How do I search for products by name?

Use the search query parameter:

curl "https://api.selorax.io/api/apps/v1/products?search=rose&status=active" \
  -H "Authorization: Bearer <token>"

This performs a partial match on the product name (case-insensitive).

Webhooks

How do I verify a webhook is from SeloraX?

Every webhook delivery includes an X-SeloraX-Signature header (prefixed with sha256=) and an X-SeloraX-Timestamp header. Compute an HMAC-SHA256 of {timestamp}.{raw_body} using your webhook signing secret and compare it to the signature value. See Receiving Webhooks for code examples.

What happens if my webhook endpoint is down?

SeloraX retries failed deliveries — up to 6 total attempts (immediate, 1min, 5min, 30min, 2hr, 12hr). After 20 consecutive failures, the subscription is automatically disabled. See the Retry Policy for the full schedule.

Yes, if your app has the appropriate scope. Use the Webhooks API to create, list, and delete subscriptions via the REST API.

Billing

How does billing work for Platform Apps?

Your app creates a charge via the Billing API. The merchant is redirected to a payment page. After payment, the platform notifies your app via a callback. The platform retains a configurable commission (default 10%).

Supported models: one-time charges, recurring subscriptions, usage-based metering, and wallet.

Do Custom Apps need billing?

No. Custom Apps are private integrations for your own store. Since you're both the developer and the merchant, billing through the platform is unnecessary.

Embedded Apps

How does the iframe communicate with the dashboard?

The dashboard sends a session token to your app via window.postMessage(). Your app verifies it using your session_signing_key. After verification, use the App Bridge methods to interact with the dashboard (navigation, toasts, modals).

Can Custom Apps embed in the dashboard?

No. Only Platform Apps support iframe embedding. Custom Apps operate through direct API calls and webhooks.

Extensions

What's the difference between JSON and sandbox extensions?

JSON extensions are declarative UI trees — you define a component hierarchy as JSON, and the dashboard renders it natively. No JavaScript, no hosting, no iframe. Best for simple blocks, badges, and action buttons.

Sandbox extensions run your JavaScript inside an isolated iframe. You get full programmatic control — API calls, resource pickers, complex state, dynamic rendering. Use the @selorax/ui SDK to communicate with the dashboard.

See Extension Platform Overview for architecture details.

How many extension targets are available?

There are 34 targets — 25 for the admin dashboard (orders, products, customers, dashboard, navigation, settings, POS, checkout, fulfillment) and 9 for the customer-facing storefront. See the full list in the Extension Overview and Storefront Extensions.

Do I need to host anything for JSON extensions?

No. JSON extensions are stored in the platform and rendered by the dashboard. Your app only needs a backend if you use call_backend actions.

How do I deploy extensions?

Use the @selorax/cli:

npm install -g @selorax/cli
selorax auth:login --client-id sx_app_... --client-secret sx_secret_... --store-id 22
selorax deploy

See the CLI Reference for all commands.

Verify the subscription is active (not auto-disabled after failures)
Check that your endpoint returns a 2xx status code within 30 seconds
Confirm the event topic matches what you subscribed to
Check that the HTTPS URL is reachable from the public internet

I can't find data for a specific store

All API requests are scoped to the store_id from your authentication context. You can only access data for the store that installed your app. There is no cross-store access.

FAQ