SeloraXDEVELOPERS

Platform Overview

SeloraX is a multi-tenant e-commerce platform. Each merchant operates an independent store with its own products, orders, customers, and settings -- all running on shared infrastructure. The developer platform lets you build apps that integrate with any merchant's store.

How Apps Work

Apps on SeloraX run as iframes embedded inside the merchant dashboard. When a merchant installs your app, it appears as a menu item in their admin panel. Clicking it loads your app's frontend URL inside the dashboard frame.

For backend operations, apps authenticate using one of two methods:

  • OAuth 2.0 -- Used during the install flow. The merchant authorizes your app, and you receive an access token scoped to their store.
  • Client credentials -- Used for server-to-server calls. Your app sends its client_id and client_secret in request headers to authenticate without user interaction. These credentials never expire, similar to Shopify offline access tokens.

What Apps Can Do

Read and Write Store Data

Access orders, products, customers, inventory, discounts, shipping information, and store settings through the REST API. All data is scoped to the merchant's store.

Subscribe to Webhooks

Register for real-time event notifications. When an order status changes, a product is updated, or any other tracked event occurs, the platform sends an HMAC-signed HTTP POST to your webhook endpoint.

Use Platform Billing

Charge merchants for your app through the SeloraX billing system. Supported billing models:

ModelDescription
One-timeA single charge for a feature or service
RecurringMonthly or annual subscription
Usage-basedMetered billing based on consumption (e.g., per SMS sent)
WalletMerchants pre-load a balance and your app deducts from it

All payments flow through the platform. You configure a commission rate (default 20%) that SeloraX retains.

Build Dashboard Extensions

Inject custom UI directly into the merchant dashboard — blocks on order/product detail pages, action buttons, dashboard widgets, navigation links, and more. Choose between JSON mode (declarative, no hosting needed) or sandbox mode (full JavaScript control in an iframe). See Extensions.

Send Messages

Apps with the manage:messaging scope can send SMS, email, and push notifications to customers on behalf of the merchant using the embedded messaging system.

Architecture

The following diagram shows how an app integrates with the SeloraX platform:

                    SeloraX Platform
                   +-----------------+
                   |   Merchant      |
                   |   Dashboard     |
                   |                 |
                   |  +-----------+  |
  postMessage      |  | App       |  |    HTTPS
  (session token)  |  | (iframe)  |<-------> App Frontend
                   |  +-----------+  |       (your server)
                   +-----------------+
                          |
                     REST API calls
                     (Bearer token)
                          |
                   +-----------------+
                   |  SeloraX API    |
                   |  (Express.js)   |
                   +-----------------+
                          |
                   +-----------------+        Webhook POST
                   |  Event System   |------> App Backend
                   |  (Inngest)      |        (HMAC-signed)
                   +-----------------+

Install Flow

  1. App registers -- You provide your app's URLs, requested scopes, and webhook topics.
  2. Merchant installs -- The merchant clicks "Install" in the app marketplace. The platform redirects them to your OAuth callback URL with an authorization code.
  3. Token exchange -- Your backend exchanges the authorization code for an access token and refresh token.
  4. Webhook subscriptions created -- The platform automatically creates webhook subscriptions for the topics your app declared.
  5. Iframe loads -- The merchant navigates to your app in the dashboard. The platform loads your app_url in an iframe and sends a session token via postMessage.
  6. API calls -- Your app uses the access token (or client credentials) to call the SeloraX REST API.
  7. Webhook events -- When relevant data changes, the platform sends HMAC-signed POST requests to your webhook endpoint.

Uninstall Flow

When a merchant uninstalls your app, the platform performs a complete cleanup:

  1. Tokens revoked — All access tokens and refresh tokens are invalidated immediately. Redis caches are cleared. Any API call using these tokens returns 401.
  2. Installation marked uninstalled — The installation record is updated with status: "uninstalled" and timestamps.
  3. Webhook subscriptions disabled — All webhook subscriptions for the installation are soft-deleted. Your endpoint stops receiving events.
  4. Pending charges cancelled — Any pending charges are cancelled. Active recurring subscriptions are cancelled. Already-paid one-time charges and wallet top-ups are preserved.
  5. Webhook events fired — The platform sends app.uninstalled to any remaining active subscriptions, and charge.cancelled (with reason: "app_uninstalled") for each cancelled charge.

Handle uninstalls gracefully

Your app should listen for the app.uninstalled webhook and clean up any local state (stored tokens, cached data, scheduled jobs) for that store. After uninstall, client credentials for that store will also stop working.

Reinstallation

If a merchant reinstalls your app after uninstalling it, the full OAuth flow runs again. Your app receives new tokens — old tokens are not reactivated. The installation record is updated (not duplicated), so the installation_id may remain the same but with fresh credentials.

Scoping and Multi-Tenancy

Every API call is scoped to a single store. The access token encodes the store_id, so your app only sees data belonging to the merchant who installed it. If your app is installed by multiple merchants, you receive a separate access token for each store.

Next Steps

Previous
Introduction
Next
Creating an App