The Zid ERP integration guide: what to build, in what order

Why this guide exists

The API reference on docs.zid.sa tells you what a single endpoint accepts and returns. But when you connect a Zid store to an ERP, an accounting system, a WMS or your own backend, your questions are different: which endpoints does the integration need? In what order? And which behaviours break an integration in month three?

Integrating a Zid Store with an ERP or Accounting System is written to answer those three questions. It is a task-oriented companion to the API reference, not a replacement for it: the reference stays authoritative for every request and response schema, and the guide carries only what changes integration design.

It is system-neutral — it describes Zid's side of the contract and the decisions any ERP forces, not one vendor's connector — and it covers both shapes: a private app for one store, or a public App Market app installed by many. The audience is developers, solution architects and functional consultants.

What's inside

The guide sums itself up in one sentence: Zid pushes Orders, Products, Stock and Customers to you by webhook; everything else you poll inside a 60-requests-per-minute budget per app per store. So settle push-vs-pull for every object before you write any code.

• Part 1 — concepts you need before writing code: push vs pull, base URLs and the different headers each API family expects, OAuth and the token lifecycle, the install journey Zid requires, scopes, the money model and VAT, order status, products and variants and stock, customers, discounts, customer wallets, and marketplace orders such as Mazeed and Trendyol.
• Part 2 — interface design decisions: what to settle per data object (sync direction, and the source of truth for each field), nine questions that remove most later ambiguity, and a table mapping every Zid concept onto its ERP counterpart with the thing to watch out for.
• Part 3 — building it: product and stock sync, orders for both reading and creating with a full field reference, returns and credit notes, coupons and bundle offers, the webhook receiver, errors and limits and silent incompleteness, money and VAT and invoicing and reconciliation, then testing, cutover and go-live.
• Appendix: worked examples with real figures from a development store — a single-coupon order, a triple-coupon order, a bundle order and a full reverse lifecycle — plus a table mapping each ERP concern to the section that answers it.

How to use it

• Pick your reading path on page two. Architects start with push vs pull, then the design decisions, then the limits. Developers start with headers and OAuth, then orders and webhooks. Finance consultants start with money, discounts and invoicing.
• Start from the last table when your question is specific. A cross-reference at the end maps each concern — "when is the invoice generated?", "how do I match customers?" — to a section number and page.
• Treat it as a knowledge base. Each subsection is one retrievable unit containing the claim, the field paths and one example, so it drops straight into an AI assistant, a RAG index or an internal support playbook.
• Work the checklist before you ship. The guide closes with a test matrix, a go-live checklist and what to monitor afterwards, plus the exact shape Zid needs for a technical escalation.

Five mistakes it saves you

The guide opens with five mistakes that break integrations in month three, each linked to the section that deals with it:

1. Putting access_token in the Bearer header — it goes in X-Manager-Token.
2. No monitored refresh job for tokens that expire after one year.
3. Recomputing totals instead of posting payment.invoice[] as it stands.
4. Triggering invoice logic off Order Status instead of payment status.
5. Retrying non-idempotent writes without searching first.

Before you start

The version published here is 1.2.0, last reviewed on 7 October 2026 against the Zid platform and a live development store. Platform behaviour moves, so if your downloaded copy and the published documentation on docs.zid.sa disagree, the documentation wins.

It is not tax, legal or compliance advice; the VAT and invoicing sections describe platform configuration and field semantics only. Zid stores operate in several countries, so rules that apply to Saudi Arabia alone — e-invoicing (ZATCA) and the national short address — are marked KSA only inside the guide, and everything else is market-independent.