SeloraXDEVELOPERS

Creating an App

This guide walks you through registering a new app on the SeloraX platform and understanding the configuration options available to you.

Registration Process

Register your app through the Developer Portal at portal.selorax.io:

  1. Sign in — Log in with your SeloraX merchant account (password or OTP) or use "Sign in with SeloraX".
  2. Create your app — Fill out the fields described below (name, redirect URLs, scopes, webhook topics, app URLs).
  3. Receive credentials — On creation, you'll receive your client_id, client_secret, and session_signing_key. These are shown only once — store them securely.
  4. Configure your app — Set up your app_url (iframe frontend), webhook_url (OAuth callback), and webhook_receive_url (webhook delivery endpoint).
  5. List on marketplace — Toggle is_listed to true when ready for merchants to discover and install your app.
  6. Implement the OAuth callback — Set up your redirect URL to handle the authorization code exchange (or use direct-install for first-party apps).
  7. Test the install flow — Install your app on a test store and verify the full lifecycle works.

Want instant credentials instead?

If you're building a private integration for your own store, use a Custom App instead. You get API credentials immediately — no registration process or OAuth flow needed.

Developer Portal API

All registration and management actions are also available via the Developer Portal API. See the Apps API for programmatic app creation.

App Configuration Fields

The following fields define your app's identity, behavior, and integration points:

Required Fields

FieldDescriptionExample
nameDisplay name shown to merchants in the marketplace (3-255 chars)"SeloraX Messaging"
redirect_urlsJSON array of allowed OAuth callback URLs (min 1)["https://my-app.example.com/oauth/callback"]
requested_scopesJSON array of permission scopes your app needs (min 1)["read:orders", "billing"]

App URL Fields

FieldDescriptionExample
app_urlFrontend URL loaded as an iframe in the merchant dashboard"https://my-app.example.com"
webhook_urlBackend URL that receives OAuth token callbacks on install"https://my-api.example.com/api/oauth"
webhook_receive_urlBackend URL that receives webhook event deliveries"https://my-api.example.com/api/webhooks"
setup_urlURL shown to merchants during the OAuth install flow (optional)"https://my-app.example.com/setup"
homepage_urlPublic homepage for your app listing"https://my-app.example.com"

webhook_url vs webhook_receive_url

These serve different purposes: - webhook_url — Called once during direct-install to deliver OAuth tokens (POST webhook_url/token). This is your OAuth callback endpoint. - webhook_receive_url — Called for every webhook event delivery (order changes, app events, etc.). This is your event handler endpoint.

Profile Fields

FieldDescriptionDefault
slugURL-safe identifier (lowercase, numbers, dashes only, 3-255 chars)Auto-generated from name
iconURL to your app's icon image--
screenshotsJSON array of screenshot URLs (max 10)[]
descriptionFull description of your app (max 8000 chars)--
short_descriptionBrief summary shown in marketplace cards (max 500 chars)--
categoryApp category for marketplace filtering (max 100 chars)--
developer_nameYour name or company name (max 255 chars)--
developer_emailContact email for developer communications--

Billing Fields

FieldDescriptionDefault
pricing_typeBilling model: "free", "subscription", or "usage""free"
pricing_amountPrice in BDT (Bangladesh Taka)0
commission_ratePlatform commission as a decimal (0 to 1, e.g., 0.2000 = 20%)0.2000

Webhook Fields

FieldDescriptionDefault
webhook_topicsJSON array of event topics to auto-subscribe on install[]
metadataJSON object for custom key-value datanull

Credentials You Receive

When your app is created, you receive three credentials. These are shown only once -- store them securely.

Client ID

sx_app_1b16e193a28d2640d2d9734dbf4907e8

Format: sx_app_<32 hex characters>

Used in OAuth flows and API requests to identify your app. This value is not secret and can be included in frontend code.

Client Secret

sx_secret_dd0f155b6e333f59acbd3cd5905f2de2fce237fa8f499ecec2605b83eb1b974b

Format: sx_secret_<64 hex characters>

Used for token exchange and server-to-server authentication. Keep this value secret. Never expose it in client-side code, public repositories, or logs.

Session Signing Key

ac4d5804b66820c347f62609bd20683e732c27ebf829c9636e9a369b4919d0af

Format: 64 hex characters

Used to verify HMAC signatures on session tokens sent from the dashboard iframe via postMessage. This lets your app confirm that the session token originated from the SeloraX platform and has not been tampered with.

Available Scopes

Scopes define what data your app can access. Request only the scopes your app actually needs.

Orders

ScopeDescription
read:ordersView orders, order details, and order history
write:ordersCreate, update, and manage order status

Products

ScopeDescription
read:productsView products, variants, and categories
write:productsCreate, update, and delete products

Customers

ScopeDescription
read:customersView customer profiles and contact information
write:customersCreate and update customer records

Inventory

ScopeDescription
read:inventoryView stock levels and inventory locations
write:inventoryAdjust stock quantities and manage inventory

Store

ScopeDescription
read:storeView store settings, domains, and configuration
write:storeUpdate store settings

Discounts

ScopeDescription
read:discountsView discount codes and promotions
write:discountsCreate, update, and delete discounts

Analytics

ScopeDescription
read:analyticsView store analytics and reporting data

Shipping

ScopeDescription
read:shippingView shipping zones, rates, and 3PL configurations
write:shippingUpdate shipping settings and manage fulfillment

Billing

ScopeDescription
billingCreate charges, subscriptions, and manage billing for your app
read:billingView billing history and charge status

Messaging

ScopeDescription
manage:messagingSend SMS, email, and push notifications to customers

Webhook Topics

When your app is installed, the platform automatically creates webhook subscriptions for the topics listed in your webhook_topics field. Available topics:

TopicDescription
order.createdA new order is placed
order.updatedAn order is modified
order.status_changedAn order's status transitions (confirmed, shipped, delivered, etc.)
product.createdA new product is added
product.updatedA product is modified
product.deletedA product is removed
customer.createdA new customer account is created
customer.updatedA customer record is modified
inventory.updatedStock levels change for a product variant
app.installedYour app is installed on a store
app.uninstalledYour app is removed from a store

Billing events (charge.created, charge.activated, charge.declined, charge.cancelled, charge.expired, charge.payment_failed, subscription.renewal_pending) are automatically delivered to apps that use the billing system. See Event Topics for full payload shapes.

Each webhook delivery includes an HMAC signature in the X-SeloraX-Signature header (prefixed with sha256=) so your app can verify the payload's authenticity. See Receiving Webhooks for verification details.

Example Configuration

Here is a complete example of an app configuration:

{
  "name": "Order Tracker Pro",
  "slug": "order-tracker-pro",
  "description": "Track all your orders in real-time with live status updates and customer notifications.",
  "short_description": "Real-time order tracking and notifications",
  "icon": "https://cdn.example.com/tracker-icon.png",
  "screenshots": [
    "https://cdn.example.com/tracker-dashboard.png",
    "https://cdn.example.com/tracker-settings.png"
  ],
  "homepage_url": "https://tracker.example.com",
  "app_url": "https://tracker.example.com/embed",
  "webhook_url": "https://api.tracker.example.com/api/oauth",
  "webhook_receive_url": "https://api.tracker.example.com/api/webhooks",
  "redirect_urls": ["https://tracker.example.com/oauth/callback"],
  "requested_scopes": [
    "read:orders",
    "read:customers",
    "read:shipping",
    "billing"
  ],
  "webhook_topics": ["order.created", "order.status_changed"],
  "developer_name": "Acme Dev Co",
  "developer_email": "[email protected]",
  "pricing_type": "subscription",
  "pricing_amount": 499,
  "commission_rate": 0.2,
  "category": "order-management"
}

Include the billing scope

If your app uses any billing features (charges, subscriptions, wallet), you must include "billing" in your requested_scopes. Without it, all billing API calls will return 403 insufficient_scope.

Handling the OAuth Callback

When a merchant installs your app, SeloraX redirects them to your redirect_uri with an authorization code. Your server must exchange this code for tokens within 60 seconds.

Node.js Example

const express = require("express");
const app = express();
 
const CLIENT_ID = process.env.SELORAX_CLIENT_ID;
const CLIENT_SECRET = process.env.SELORAX_CLIENT_SECRET;
 
app.get("/oauth/callback", async (req, res) => {
  const { code, state } = req.query;
 
  // 1. Verify state matches what you sent (CSRF protection)
  if (state !== req.session.oauthState) {
    return res.status(400).send("Invalid state parameter");
  }
 
  // 2. Exchange the authorization code for tokens
  const response = await fetch("https://api.selorax.io/api/apps/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code,
      redirect_uri: "https://your-app.com/oauth/callback",
    }),
  });
 
  const tokens = await response.json();
 
  // 3. Store tokens securely, keyed by store_id
  await db.saveInstallation({
    store_id: tokens.store_id,
    store_name: tokens.store_name,
    installation_id: tokens.installation_id,
    access_token: tokens.access_token, // encrypt this
    refresh_token: tokens.refresh_token, // encrypt this
    scope: tokens.scope,
    token_expires_at: new Date(Date.now() + tokens.expires_in * 1000),
  });
 
  res.redirect("/install-success");
});

Python Example

import requests
from flask import Flask, request, redirect, session
 
app = Flask(__name__)
 
@app.route("/oauth/callback")
def oauth_callback():
    code = request.args.get("code")
    state = request.args.get("state")
 
    if state != session.get("oauth_state"):
        return "Invalid state", 400
 
    response = requests.post(
        "https://api.selorax.io/api/apps/oauth/token",
        json={
            "grant_type": "authorization_code",
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "code": code,
            "redirect_uri": "https://your-app.com/oauth/callback",
        },
    )
 
    tokens = response.json()
    # Store tokens.access_token, tokens.refresh_token, tokens.store_id
    save_installation(tokens)
    return redirect("/install-success")

Next Steps

Now that your app is registered, follow the Your First App tutorial to build a working integration with full code examples.