Skip to content

Document ZATCA VAT group registration in Saudi Arabia #485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
migueltorresvalls wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document ZATCA VAT group registration in Saudi Arabia #485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
67d5bfe
Document ZATCA VAT group registration in Saudi Arabia
migueltorresvalls Jul 16, 2026
4d6bd9e
Reword Saudi Arabia docs to multi-branch entities
migueltorresvalls Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion apps/saudi-arabia.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ import FAQ from '/snippets/faqs/sa/composers/app-zatca.mdx';
* **Clearance** of standard tax invoices (B2B, B2G).
* **Reporting** of simplified tax invoices (B2C).
* ZATCA onboarding: OTP, compliance checks, and production CSID provisioning.
* **Multi-branch onboarding**: a single VAT number can hold several registrations, one per [supplier identity](/guides/sa-zatca-registration#multi-branch-entities), each with its own CSID and invoice chain.
* UBL 2.1 with KSA extensions, ICV/PIH chaining, and the Phase 2 QR code.

Check out the guides below to get started:
Expand All @@ -58,7 +59,7 @@ import FAQ from '/snippets/faqs/sa/composers/app-zatca.mdx';

Registration
<Card title="Register supplier with ZATCA" icon="https://assets.invopop.com/apps/zatca/icon.svg" horizontal>
Validate the party, stake the VAT claim, and publish the ZATCA onboarding link the supplier follows.
Validate the party, stake the claim on its VAT number and identity, and publish the ZATCA onboarding link the supplier follows.
</Card>
<Card title="Unregister supplier from ZATCA" icon="https://assets.invopop.com/apps/zatca/icon.svg" horizontal>
Removes the party and its stored credentials from Invopop's internal systems.
Expand Down
8 changes: 8 additions & 0 deletions changelog/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@ sidebarTitle: "Overview"
mode: "center"
---

<Update label="July 16, 2026" description="ZATCA multi-branch registration" tags={["Saudi Arabia"]}>

## New features

**Saudi Arabia multi-branch registration.** A single VAT number can now hold multiple ZATCA registrations, one per supplier identity (`CRN`, `MOM`, `MLS`, `700`, `SAG`, `OTH`). A business whose branches share a VAT number but hold different commercial registrations can onboard each branch with its own CSID and its own invoice chain, and invoices route to the matching registration by VAT number and identity. See the [registration guide](/guides/sa-zatca-registration#multi-branch-entities).

</Update>

<Update label="June 26, 2026" description="Weekly update" tags={["Saudi Arabia", "API"]}>

## New features
Expand Down
23 changes: 20 additions & 3 deletions guides/sa-zatca-registration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Registration spans two parts: a workflow you run against the party document, and
Sets the state of the silo entry as "Processing".
</Step>
<Step title="Register supplier with ZATCA">
Validates the party's identity and full address, then publishes a public onboarding link in the meta section of the party. The supplier follows this link to complete the onboarding wizard.
Validates the party's tax ID, [supplier identity](#multi-branch-entities), and full address, stakes the claim on that VAT number and identity, then publishes a public onboarding link in the meta section of the party. The supplier follows this link to complete the onboarding wizard.
</Step>
<Step title="Wait for ZATCA certificate upload">
Pauses until the supplier uploads the compliance CSID. It will then submit the mandatory compliance sample invoices and swaps the Compliance CSID with the Production CSID.
Expand Down Expand Up @@ -113,10 +113,10 @@ The link published by **Register Party** provides an onboarding wizard for the s

Unregistering a party from ZATCA in production environment is handled by the **tax payers**, directly in the **FATOORA portal**, signing in with their own credentials.

Invopop also provides an unregister action that removes the party and its stored credentials from **Invopop's internal systems only**. It does not touch the party's registration with ZATCA.
Invopop also provides an unregister action that removes the party and its stored credentials from **Invopop's internal systems only**. It does not touch the party's registration with ZATCA. It targets a single registration, the one that matches the party's VAT number and [supplier identity](#multi-branch-entities), so unregistering one branch leaves the other registrations under the same VAT number untouched.

<Warning>
This action is intended for **testing in sandbox** — for example, to re-onboard the same VAT during development. It is **not** for live environments; unregistering at ZATCA is always done by the tax payer in the FATOORA portal.
This action is intended for **testing in sandbox**, for example to re-onboard the same VAT number and identity during development. It is **not** for live environments; unregistering at ZATCA is always done by the tax payer in the FATOORA portal.
</Warning>

<Tabs>
Expand All @@ -131,6 +131,23 @@ Invopop also provides an unregister action that removes the party and its stored
</Tab>
</Tabs>

## Multi-branch entities

A business can run several branches that all share the same VAT number while each branch onboards its own device or system. A single VAT number therefore often needs more than one registration, and Invopop supports this through the GOBL identities field.

Every party registered with ZATCA is linked to a unique CSID certificate that identifies both its VAT number and its branch. Invopop gives each unique combination of VAT number and supplier identity its own CSID certificate, allowing them to act independently and through their own invoice chain.

Set the identity on the [`org.Party`](https://docs.gobl.org/draft/org/party) document as an entry in `identities` whose `type` is one of:

| `type` | Identity |
|---|---|
| `CRN` | Commercial Registration Number |
| `MOM` | Momrah license (Ministry of Municipality, Rural Affairs and Housing) |
| `MLS` | MLSD license (Ministry of Human Resources and Social Development) |
| `700` | 700 number (unified national number) |
| `SAG` | Sagia license (Ministry of Investment, formerly SAGIA) |
| `OTH` | Other identifier |

## FAQ

<FAQ />
Expand Down