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:
- Sign in — Log in with your SeloraX merchant account (password or OTP) or use "Sign in with SeloraX".
- Create your app — Fill out the fields described below (name, redirect URLs, scopes, webhook topics, app URLs).
- Receive credentials — On creation, you'll receive your
client_id,client_secret, andsession_signing_key. These are shown only once — store them securely. - Configure your app — Set up your
app_url(iframe frontend),webhook_url(OAuth callback), andwebhook_receive_url(webhook delivery endpoint). - List on marketplace — Toggle
is_listedtotruewhen ready for merchants to discover and install your app. - Implement the OAuth callback — Set up your redirect URL to handle the authorization code exchange (or use direct-install for first-party apps).
- 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
| Field | Description | Example |
|---|---|---|
name | Display name shown to merchants in the marketplace (3-255 chars) | "SeloraX Messaging" |
redirect_urls | JSON array of allowed OAuth callback URLs (min 1) | ["https://my-app.example.com/oauth/callback"] |
requested_scopes | JSON array of permission scopes your app needs (min 1) | ["read:orders", "billing"] |
App URL Fields
| Field | Description | Example |
|---|---|---|
app_url | Frontend URL loaded as an iframe in the merchant dashboard | "https://my-app.example.com" |
webhook_url | Backend URL that receives OAuth token callbacks on install | "https://my-api.example.com/api/oauth" |
webhook_receive_url | Backend URL that receives webhook event deliveries | "https://my-api.example.com/api/webhooks" |
setup_url | URL shown to merchants during the OAuth install flow (optional) | "https://my-app.example.com/setup" |
homepage_url | Public 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
| Field | Description | Default |
|---|---|---|
slug | URL-safe identifier (lowercase, numbers, dashes only, 3-255 chars) | Auto-generated from name |
icon | URL to your app's icon image | -- |
screenshots | JSON array of screenshot URLs (max 10) | [] |
description | Full description of your app (max 8000 chars) | -- |
short_description | Brief summary shown in marketplace cards (max 500 chars) | -- |
category | App category for marketplace filtering (max 100 chars) | -- |
developer_name | Your name or company name (max 255 chars) | -- |
developer_email | Contact email for developer communications | -- |
Billing Fields
| Field | Description | Default |
|---|---|---|
pricing_type | Billing model: "free", "subscription", or "usage" | "free" |
pricing_amount | Price in BDT (Bangladesh Taka) | 0 |
commission_rate | Platform commission as a decimal (0 to 1, e.g., 0.2000 = 20%) | 0.2000 |
Webhook Fields
| Field | Description | Default |
|---|---|---|
webhook_topics | JSON array of event topics to auto-subscribe on install | [] |
metadata | JSON object for custom key-value data | null |
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
| Scope | Description |
|---|---|
read:orders | View orders, order details, and order history |
write:orders | Create, update, and manage order status |
Products
| Scope | Description |
|---|---|
read:products | View products, variants, and categories |
write:products | Create, update, and delete products |
Customers
| Scope | Description |
|---|---|
read:customers | View customer profiles and contact information |
write:customers | Create and update customer records |
Inventory
| Scope | Description |
|---|---|
read:inventory | View stock levels and inventory locations |
write:inventory | Adjust stock quantities and manage inventory |
Store
| Scope | Description |
|---|---|
read:store | View store settings, domains, and configuration |
write:store | Update store settings |
Discounts
| Scope | Description |
|---|---|
read:discounts | View discount codes and promotions |
write:discounts | Create, update, and delete discounts |
Analytics
| Scope | Description |
|---|---|
read:analytics | View store analytics and reporting data |
Shipping
| Scope | Description |
|---|---|
read:shipping | View shipping zones, rates, and 3PL configurations |
write:shipping | Update shipping settings and manage fulfillment |
Billing
| Scope | Description |
|---|---|
billing | Create charges, subscriptions, and manage billing for your app |
read:billing | View billing history and charge status |
Messaging
| Scope | Description |
|---|---|
manage:messaging | Send 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:
| Topic | Description |
|---|---|
order.created | A new order is placed |
order.updated | An order is modified |
order.status_changed | An order's status transitions (confirmed, shipped, delivered, etc.) |
product.created | A new product is added |
product.updated | A product is modified |
product.deleted | A product is removed |
customer.created | A new customer account is created |
customer.updated | A customer record is modified |
inventory.updated | Stock levels change for a product variant |
app.installed | Your app is installed on a store |
app.uninstalled | Your 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.