Development - Playbook

Before writing your first line of app code, get your account, environment, and understanding of Salla's architecture in place. This article is a literal setup procedure, follow it top to bottom and you will finish with a registered account, a working local environment, and a clear mental model of how a Salla app talks to a merchant's store. Skipping this article is the single most common cause of rework later.

If you are experienced, some of this will feel familiar (OAuth, webhooks). If you are newer, every step below assumes no prior Salla-specific knowledge and explains the reasoning, not just the action.

Figure 4.1 - Overview of the Partner registration and setup flow

Partner Requirements

Partner Account Setup, Step by Step

Go to the Salla Partners Portal and register as a Developer (see Introduction to Salla Partners if unsure which partner type fits you).

Complete the registration form

Complete the registration form with your business or individual details. Salla verifies this information before granting full access.

Once verified, log in to the Partners Portal dashboard, separate from any merchant store login, with its own credentials.

Create a demo/test store

From the dashboard, create a demo/test store immediately, even before your app idea is finalized, you will need it for every step that follows.

Check Your Account Type

A verified Partner account is separate from a Salla merchant account. If you cannot see developer tools like API credentials or demo stores, double-check which account you are logged into, this is the most common early setup mistake.

Figure 4.2 - The Salla Partners Portal registration form

Verifying your Salla Partner account process:

Open ID Verification

Under the setting section, click on ID Verification.

Figure 4.3 - Open ID Verification from your account settings

Fill out your identity information

Figure 4.4 - The application after being downloaded from the app store; the app got auto-authorized

Upload the required documents

Figure 4.5 - Select from the product list what represents you and upload its required document

Fill in the payment accounts

Figure 4.6 - Fill in the payment accounts

Request verification

Once you done, click on ask to verify, the team will review your request, and you will get an email response.

Confirm the verified label

By the end of the process, you will see the verified label on top of your account setting page, like image below.

Figure 4.7 - The verified label shown on your account settings page

Access Requirements

Once registered, you need three things before you can start building:

Verify your Partner account.

Access to a demo/test store to build and test against real, non-production data.

App credentials, a client ID and client secret, issued after you create your app entry in the Portal (Core Development, Creating Your App).

Figure 4.8 - Creating a demo store from the Partners Portal

Development Environment, Step by Step

Choose your language/framework

Salla's APIs are standard REST endpoints, so any modern backend stack works.

Install a local tunneling tool

Install a local tunneling tool (e.g., ngrok) so Salla can send webhook events to your machine while you develop locally, webhooks require a publicly reachable URL, and your laptop is not one by default.

Set up version control

Set up version control (git) from the first commit, including a .gitignore that excludes credentials and environment files.

Create a .env file

Create a .env file (or your framework's equivalent) for your client ID, client secret, and any third-party API keys, never hard-code these into source files.

Best Practices

Set up your demo store before writing any integration code, testing against real data structures early avoids surprises later.

Keep app credentials out of source control from the very first commit.

Use the Salla Partners AI Agent Kit at https://docs.salla.dev/2228615m0

Common Mistakes

Delaying webhook testing until late in development, when local testing tools would have caught issues early.

Salla App Standards

Security Requirements

Store credentials and tokens securely, never in client-side code, logs, or version control.

Validate and sanitize all data received via webhooks and APIs, never trust incoming data to be well-formed by default.

Use HTTPS for all endpoints your app exposes, including your webhook receiver.

Performance Expectations

Apps that are slow to install, slow to load in the merchant dashboard, or slow to respond to store events create a poor experience and risk rejection during review. A good beginner rule of thumb: if a merchant-facing action takes longer than two seconds, either speed it up or give clear loading feedback.

UX Guidelines

Apps embedded inside the merchant dashboard should feel consistent with Salla's own interface, clear navigation, sensible defaults, and no unnecessary friction during setup (see App Onboarding & Embedded Pages in Core Development).

Compliance Requirements

Handle merchant and customer data responsibly: only request the data scopes your app actually needs, and be transparent about how data is used, especially for apps passing data to third-party providers (AI models, SMS providers).

Figure 4.9 - The OAuth scope-approval screen a merchant sees during install

Best Practices

Request the minimum OAuth scopes your app needs - broader access requests slow down merchant trust and review approval.

Document your data handling practices clearly before submission; this is typically requested during review.

Common Mistakes

Requesting full-store data access when your app only needs order or product data.

Treating security and compliance as a pre-launch checklist item instead of a design principle from day one.

Technical Architecture Overview

How Salla Apps Work

A Salla app is fundamentally an external service that does four things. This is the single most useful mental model for every later article:

Authenticates with a merchant's store via OAuth.

Receives store events via webhooks (new order, product updated, etc.).

Reads/writes store data via Salla's APIs.

Optionally renders UI inside the merchant dashboard via embedded pages.

Figure 4.10 - The three core flows between a merchant's store and your app server

Authentication Flow, Step by Step

Salla apps use OAuth to obtain merchant-specific access. Here is the exact sequence:

Figure 4.11 - The OAuth authorization sequence, from install to authenticated API calls

Merchant clicks Install

The merchant clicks "Install" on your app, either from the App Store or a direct link you have shared.

Salla shows the authorization screen

Salla redirects the merchant to an authorization screen showing exactly what data your app is requesting access to.

Merchant approves the scopes

The merchant approves (or denies) those scopes. If approved, Salla redirects back to a URL you specify with a temporary authorization code.

Exchange the code for a token

Your app server exchanges that code for an access token via a secure, server-to-server request, this token is used for every subsequent API call on behalf of this merchant.

Store the token securely

Your app stores that token securely, associated with the merchant's store ID, and uses it until it expires or the merchant uninstalls.

// Illustrative pattern only - confirm exact field names
// against Salla's current API reference before implementing.
POST /oauth2/token
{
  "grant_type": "authorization_code",
  "client_id": process.env.SALLA_CLIENT_ID,
  "client_secret": process.env.SALLA_CLIENT_SECRET,
  "code": authorizationCodeFromRedirect,
  "redirect_uri": process.env.APP_BASE_URL + "/oauth/callback"
}
// Response includes an access_token - store this
// securely, scoped to the merchant's store ID.

Scope of This Section

Exact authentication parameters and endpoints are covered in Salla's official API reference,

This playbook explains the pattern, not the field-level specification. Always confirm exact request/response details against the current API docs before implementing.

Data Flow

Data flows in through webhooks (events happening in the store) and out through API calls (your app acting on the store).

Here is a realistic order.created webhook payload, so you know what to expect in Core Development:

// Illustrative webhook payload - field names may vary;
// confirm against Salla's current webhook reference.
{
  "event": "order.created",
  "merchant": 123456,
  "data": {
    "id": 987654,
    "status": "pending",
    "total": { "amount": 149.00, "currency": "SAR" },
    "customer": { "id": 55123, "name": "Example Customer" }
  }
}

Design your app's data flow diagram early, knowing which events you subscribe to and which API calls you will make in response clarifies your entire backend architecture before you write code.

Figure 4.12 - The webhook subscription settings screen in the Partners Portal

App Lifecycle

A Salla app moves through distinct states over its life. Understanding this now sets up Core Development and Publishing Your App cleanly, building and publishing are two distinct stages with different requirements.

Created

App entry exists in the Partners Portal; credentials issued.

In development

You are building and testing against your demo store.

Submitted for review

Sent to Salla for review ahead of publishing (Publishing Your App).

Approved / published

Live in the App Store, discoverable by merchants.

Installed

A specific merchant has authorized and is using your app.

Active / uninstalled

Ongoing use, or the merchant has removed the app.

A Step Easy to Miss

Handling the "uninstalled" state properly. When a merchant uninstalls your app, Salla sends a webhook event for that too (app.uninstalled), your app should revoke/delete the stored access token and clean up merchant-specific data per your retention policy (Data Management, Core Development). Skipping this leaves orphaned data behind and is one of the most commonly overlooked paths during testing.

Best Practices

Map your app's webhook subscriptions and API calls into a simple diagram before starting development.

Treat token storage and refresh handling as core architecture, expired tokens are a leading cause of app malfunctions merchants report.

Common Mistakes

Polling the API for data that is available via webhook, this wastes calls and introduces lag.

Not handling the "app uninstalled" event, leaving orphaned data or broken states behind.

Development Preparation

Partner Account Setup, Step by Step#

Verifying your Salla Partner account process:#

Access Requirements#

Development Environment, Step by Step#

Salla App Standards#

Security Requirements#

Performance Expectations#

UX Guidelines#

Compliance Requirements#

Technical Architecture Overview#

How Salla Apps Work#

Authentication Flow, Step by Step#

Data Flow#

App Lifecycle#

Partner Account Setup, Step by Step

Verifying your Salla Partner account process:

Access Requirements

Development Environment, Step by Step

Salla App Standards

Security Requirements

Performance Expectations

UX Guidelines

Compliance Requirements

Technical Architecture Overview

How Salla Apps Work

Authentication Flow, Step by Step

Data Flow

App Lifecycle