Blog details
Short answer: Salla API integration means a custom system can exchange orders, products, stock and customer records with a Salla store through Salla's official Merchant APIs and webhooks, without staff copying data by hand. A ready-made app can be enough for a simple, one-way flow; a custom integration is worth scoping when you already run inventory, accounting or fulfilment outside Salla, or when you need retries, a single source of truth and a clear owner for tax invoices.
By Mohamed Samy, senior backend developer specializing in Laravel/PHP, with seven years of experience. Published: 12 November 2026. Updated: 12 November 2026.
This is not tax or legal advice, and it is not a substitute for counsel or for Salla's official documentation.
Most owners who contact me already have a live Salla store in Saudi Arabia or the Gulf, plus a warehouse or accounting file that no longer matches the dashboard. Whether to stay on a hosted platform or build a custom ecommerce store is a different article, as is the earlier choice between a company website, an online store and a hosted platform. This one assumes you are keeping Salla as the storefront and need a reliable Salla API integration with the systems you already run. Golden Code builds that custom layer from scratch; we do not resell a ready-made Salla app or publish a fixed package price.
What Salla API integration actually has to do
Salla publishes Merchant APIs as REST endpoints under the official base https://api.salla.dev/admin/v2. Access is granted through OAuth 2.0: the merchant authorises an app, your server receives a time-limited access token, and each call carries an Authorization header. Official documentation states that access tokens last 14 days, and that a refresh token (requested with the offline_access scope) can be used within a 1-month window and is single-use. The merchant can later disconnect the app from the Partners dashboard. That is the official model, not a shared password or a one-off export. API rate limits depend on the merchant's Salla plan; see Salla's rate-limiting documentation for the current table.
| Area | What usually breaks today | What the integration should do |
|---|---|---|
| Orders | Staff copy a ticket from Salla into a sheet | A confirmed order arrives once in your system |
| Stock | Two channels sell the same unit | One source of truth, with a clear write direction |
| Products | Prices and SKUs drift between systems | An agreed owner for the catalogue |
| Customers | A buyer exists twice, with different groups | A stable identity, using current official endpoints |
| Accounting | A visit is invoiced twice, or not at all | One owner for the official tax invoice |
| Failures | A missed webhook is discovered weeks later | A queue, a signature check, a daily reconciliation |
A private app for one merchant and a public app listed for other stores are different products. Salla's create-your-first-app guide walks through creating the app in the Partners portal, choosing a public or private type, and collecting the credentials. Ask for English and Arabic app names if you will publish. A marketplace listing is not required for a one-store integration.
Official Salla markets, and where Egypt still belongs
Salla is a store platform for merchants in Saudi Arabia and the Gulf. Official availability is Saudi Arabia, the UAE, Kuwait, Qatar, Bahrain and Oman. This guide starts with a Saudi or other Gulf store. Egypt appears here as businesses selling into Saudi Arabia, fulfilment from Egypt, and Egyptian teams working for a Gulf merchant, not as a co-equal Salla merchant market.
Egyptian businesses still need a Salla API integration when they sell into Saudi Arabia, fulfil from Egypt, or already run a custom inventory or custom ERP that has to talk to a Salla store. Egyptian teams working for a Gulf merchant hit the same problem. The product idea can be shared; tax, payout and data rules stay country-specific.
If you fulfil from Egypt or keep customer records there, map that operation clearly. Where does stock really live? Who confirms that an order can ship? Which customer records are personal data under Egypt's Personal Data Protection Law? Confirm duties with counsel. An Egypt e-receipt, POS and ERP integration is a separate Egyptian tax-receipt workflow, not a Salla or ZATCA walkthrough; confirm any duty with your accountant. The integration should not invent a second customer database in an unencrypted sheet, or copy fields you do not need.
Payments that already happen inside Salla do not automatically become a second payment integration in your app. A custom checkout or payout report is a separate, verified scope, and this article will not promise a payment gateway build that is not in the inventory.
Ready-made Salla apps versus a custom layer
The Salla App Store and the official APIs can cover a simple case: send paid orders to one accounting tool, or push stock from one warehouse. A ready-made app is a reasonable first look when your workflow matches what the vendor already ships and you accept that vendor's failure handling.
It becomes a poor fit when three systems all try to be the source of truth, when a refund or a partial shipment never reaches accounting, or when you cannot tell whether yesterday's orders all arrived. Custom work is not automatically better. You will own the mapping, hosting, token storage and monitoring. That is worth it when you can describe the gap from a real week of orders, not from a wish for a complete middleware platform.
If you are automating a narrow, already-stable handoff, our guide to n8n self-hosted versus cloud versus custom code is about that choice. A custom WhatsApp AI chatbot for business is a messaging layer; it does not replace order and stock sync over the Salla API. After a short inventory we can send you a custom technical quote for a Salla API integration. We do not publish a fixed package.
Webhooks, the API, and the cases that break a demo
Salla's documentation describes two families of webhooks. App events are sent for the app itself, such as installation or authorisation. Store events are the ones you subscribe to, including through the Partners portal, so a new or updated order can reach your server instead of polling every few minutes. You can also register a webhook through the API. Polling still has a place for backfill and a daily check. It is a poor primary path if the warehouse must move when the order is paid.
A webhook is not trusted just because it arrived. The official webhooks page describes verifying the request, including the X-salla-signature header and a secret you hold on your server. Reject anything that does not match. Return quickly and do the heavy work on a queue, so a slow accounting call does not make Salla retry a job you already started. If the same event arrives twice, your system must not create two orders. Store the official event identity and make the write idempotent.
Salla's list-orders documentation, opened on 12 November 2026, carries a breaking-change notice: effective 18 February 2026, the groups array under customer is deprecated, and the Customer Details endpoint is the alternative for customer groups. A second notice says that starting 1 September 2026 expanded=true is no longer supported, and that apps created after 15 August 2024 already did not support it. As of today, those dates have passed. An integration that still expects the old fields will fail quietly, so build against the current official pages and keep a changelog.
Cancellations, partial refunds, split shipments, coupons and unpaid reservations break a happy-path demo. Agree them in writing before anyone writes the first mapper. The same is true for stock: if Salla and your warehouse can both write the quantity, you will oversell. Choose one writer for each SKU, or a documented merge rule, and test a sale on both channels in the same minute.
Gulf stores, ZATCA and data you should not copy twice
For a Saudi store, tax invoicing is often the hidden scope. Our ZATCA Phase 2 integration guide is the place to read that workflow. The rule here is operational, not a filing date: pick one system that issues the official tax invoice for a given order, and do not let Salla and your accounting tool both issue one. Confirm the obligation and the current wave with your accountant and the official channel; I will not invent a deadline here.
A UAE or other Gulf entity selling through Salla still needs its own invoice and data rules. Do not paste a Saudi export format onto another country, and do not assume Egyptian personal-data duties disappear because the storefront is in Saudi Arabia. Customer records remain personal data. Map where they are hosted, including backups, and collect only what the journey needs.
Bilingual catalogues, riyal versus Egyptian pound, and branch-level stock belong to the merchant's actual legal entities, not to a single global price list that silently converts figures. The architecture can be shared. Policy for each entity should stay separate.
What we build, and what we will not promise
We scope a custom Salla API integration around a real week of orders: what is created in Salla, what must land in your warehouse or accounts, and who is told when a handoff fails. A third-system integration is listed only where access is verified, not as an imaginary marketplace, courier or ERP API.
We will not promise a connector that “covers every Salla app and every accounting package,” or that stays compatible forever without maintenance. Official endpoints change, as the list-orders notices show. The proposal should include monitoring, reconciliation, and an owner for token rotation when an access token expires or a merchant revokes the app.
Golden Code does not sell a ready-made Salla product. The development services overview is the starting point for a custom build, with source-code handover in the proposal.
Six steps to scope a custom Salla API integration
Step 1: Map what stays in Salla and what lives in your system
Write down the storefront, the warehouse, accounting, fulfilment and any other tool that already touches an order. Name the source of truth for catalogue, stock, customers and invoices. The map is the scope, not a blank wish for full sync.
Step 2: List the flows and the events that start them
For orders, products, stock and customers, say whether the update starts in Salla or in your system, and whether it is one-way or both ways. Include a cancellation, a refund and a stock adjustment. If a flow has no owner, it does not belong in the first release.
Step 3: Scope the app, the permissions and the official docs
Agree whether the app is private to one merchant or intended for more stores. List the OAuth scopes you actually need, using the authorization guide and the current Merchant API pages. Do not request access you will not use, and do not hard-code fields that official notices have already retired.
Step 4: Design webhook intake, signatures and retries
Give your server a stable HTTPS endpoint, verify the official signature, and process work on a queue. Store the event identity so a retry cannot create a second order. Keep polling or a daily pull as a backfill, not as the only way you learn a sale happened.
Step 5: Agree refunds, shipments and who issues the tax invoice
Take anonymized examples of a paid order, a partial refund, a split shipment and a coupon. Decide which system issues the official tax invoice, and confirm any ZATCA or local duty with your accountant. Do not leave that decision to the first live dispute.
Step 6: Test on a non-production store, then agree monitoring and handover
Use a demo or staging store before a live catalogue. Reconcile a full day's orders against Salla and investigate every mismatch. Agree who watches failed jobs, how tokens are stored and rotated, and how staff are trained. After that review we can send you a custom technical quote based on your Salla order and inventory map.
Soft next step
If you run a Salla store in Saudi Arabia or the Gulf, sell into KSA from Egypt, or already have a warehouse or accounting system out of date with the dashboard, send a short inventory: the store URL, the systems that must receive or send data, and one recent week of exceptions. We will say what belongs in a custom Salla API integration and what should stay with your accountant or counsel. You can also send Golden Code that inventory for a custom technical quote. No fixed package, only a scoped proposal.
FAQ
Do we have to leave Salla to use a custom system?
No. A custom integration is for the case where Salla remains the storefront and your warehouse, accounts or fulfilment need a reliable exchange of data. Leaving the platform entirely is a different decision, covered in our ecommerce cost guide.
Is a ready-made Salla app enough?
It can be, when your flow is simple, one-way and already matches what the app ships. It is usually a poor fit once several systems write the same stock or invoice, or once you cannot tell whether every paid order arrived.
Should we rely on webhooks or poll the API?
Use webhooks for near-real-time store events, with a signature check and an idempotent queue, and keep a periodic API pull for backfill and reconciliation. Polling alone is a slow and incomplete primary path.
Will one integration automatically cover an Egyptian operation and a Gulf store?
No. You can share the technical architecture, but tax invoices, payouts, catalogues and data rules stay entity-specific. Confirm local requirements with counsel and your accountant before you copy one country's settings into another.
Who should issue the official tax invoice for a Salla order?
Pick one system and keep it consistent. For a Saudi store, read our ZATCA Phase 2 guide and confirm the current duty with your accountant. This article will not invent a filing date or a second issuer.
Do you sell a fixed Salla API integration package?
No. Golden Code does not publish a fixed Salla package or a ready-made app price. We quote custom technical work after an inventory of your store, flows and exception cases.
Sources
- Salla platform documentation — docs.salla.dev and Get started (Merchant API base
https://api.salla.dev/admin/v2) - Salla — Authorization (OAuth 2.0) and rate limiting
- Salla — Webhooks and Register webhook
- Salla — Create your first app and the Partners portal
- Salla — List orders (breaking-change and deprecation notices opened 12 November 2026) and Customer details
