ZATCA supplier registration in Saudi Arabia

Registration is required for any Saudi VAT number that will clear or report invoices through Invopop. It is a prerequisite for the clearance and reporting flow.

Sandbox environments

In sandbox, the Register Party step’s configuration selects which ZATCA portal to onboard against. Production enrollments ignore this and always use the live endpoint.

Mode	Target	OTP in the wizard	Use it to
`developer`	ZATCA Developer (sandbox) portal	Dummy — any placeholder value is accepted	Test the onboarding flow end to end without touching a real ZATCA account.
`simulation` (default)	ZATCA Simulation portal	Real — must be generated from the supplier’s FATOORA Simulation account	Rehearse the production onboarding with genuine certificates and compliance checks before going live.

The two modes target different ZATCA sandbox endpoints and differ mainly in how the OTP is treated:

Developer is the lightweight sandbox. ZATCA does not validate the OTP, so the value the supplier types in the onboarding wizard is a dummy. You can register any party in developer mode, but ZATCA only accepts invoices issued from its fixed test VAT number, 399999999900003.
Simulation mirrors production. The OTP must be a real one-time password the supplier generates from their FATOORA Simulation portal, exactly as they would in production.

In both sandbox modes the supplier still completes the same wizard, only the OTP requirement changes.

How it works

Registration spans two parts: a workflow you run against the party document, and a hosted onboarding wizard the supplier completes to provide the FATOORA OTP.

Set State → Processing

Sets the state of the silo entry as “Processing”.

Validates the party’s tax ID, supplier identity, 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.

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.

Set State → Registered

Sets the state of the silo entry as “Registered”.

ZATCA register party workflow

Add to my workspace →

Workflow
Code

Copy and paste into a new Empty Party workflow.

ZATCA register supplier workflow

{
    "name": "ZATCA register supplier",
    "description": "Registers a supplier with ZATCA and provisions its production CSID",
    "schema": "org/party",
    "steps": [
        {
            "id": "f60b2e30-6fce-11f1-b09d-79f60b032746",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "fd448bb0-6fce-11f1-b09d-79f60b032746",
            "name": "Register supplier with ZATCA",
            "provider": "gov-sa.party.register",
            "config": {
                "mode": "simulation"
            }
        },
        {
            "id": "0064b770-6fcf-11f1-b09d-79f60b032746",
            "name": "Wait for OTP submission",
            "provider": "gov-sa.wait.authorization"
        },
        {
            "id": "0236df60-6fcf-11f1-b09d-79f60b032746",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `registered`{.state .registered}",
            "config": {
                "state": "registered"
            }
        }
    ],
    "rescue": [
        {
            "id": "04aa0240-6fcf-11f1-b09d-79f60b032746",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

The onboarding wizard

The link published by Register Party provides an onboarding wizard for the supplier to complete:

Company details

The supplier confirms the legal name and provides the invoice type (1000 standard, 0100 simplified, or 1100 both), branch name, registered address, and business category. These values feed the certificate request.

Get the OTP from FATOORA

The supplier signs in to the FATOORA portal and generates a One-Time Password for the EGS unit. The wizard shows the relevant FATOORA screens.

Enter the OTP

The supplier pastes the OTP and reviews the recap of the details that will be sent to ZATCA.

Confirm details

Here you will make sure all the details you entered were correct. Click “Back” if you need to change anything.

Submit

Upon submit, Invopop requests the Compliance CSID, and stores the credentials. This unblocks the Wait for ZATCA certificate upload step in the workflow.

The invoice type chosen here determines which compliance samples Invopop submits: 1000 runs standard tax invoices, credit notes, and debit notes; 0100 runs the simplified equivalents; 1100 runs both sets.

Reading registrations

The ZATCA registrations dashboard lists every party the workspace has onboarded, ordered alphabetically by name, so you can confirm what a supplier is registered for without leaving the console. Each row carries the registration’s details: Name, Branch Name, Identity Code, Identity Scheme, Business Category, Registered Address, Tax Code, Simplified Invoices and Standard Invoices, showing which document types the party can submit, Status — Registered, or Unregistered and the Silo Entry the registration was started from. In sandbox, an extra Environment column precedes the tax code, separating Simulation from Developer registrations.

The Name in each row is a quick filter: selecting it opens the invoices tab filtered to that party’s cleared and reported chain. The Supplier Tax Code column on that tab filters back the other way, to the registered party.

Unregistration (sandbox only)

Unregistering a party from ZATCA in production environment is handled by the taxpayers, 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. It targets a single registration, the one that matches the party’s VAT number and supplier identity, so unregistering one branch leaves the other registrations under the same VAT number untouched.

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 taxpayer in the FATOORA portal.

ZATCA unregister supplier workflow (sandbox only)

Add to my workspace →

Workflow
Code

Copy and paste into a new Empty Party workflow.

ZATCA unregister supplier workflow

{
    "name": "ZATCA unregister supplier",
    "description": "Removes a supplier's registration from Invopop's internal systems",
    "schema": "org/party",
    "steps": [
        {
            "id": "572ac450-6fcf-11f1-b09d-79f60b032746",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "5c0e9910-6fcf-11f1-b09d-79f60b032746",
            "name": "Unregister supplier from ZATCA",
            "provider": "gov-sa.party.unregister"
        },
        {
            "id": "5e800e40-6fcf-11f1-b09d-79f60b032746",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "60e4d940-6fcf-11f1-b09d-79f60b032746",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

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 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

What do I need to onboard a party with ZATCA?

A workspace with the Saudi Arabia app enabled, and an org/party (the supplier) carrying:

a Saudi VAT registration number,
an identity of type CRN, MOM, MLS, 700, SAG, or OTH, and
a complete national address (building number, postal code, district, street, additional street, and country).

During the hosted onboarding wizard the supplier also provides the legal name, invoice type (1000 standard / 0100 simplified / 1100 both), branch name, registered address, and business category — plus the FATOORA OTP.

How long is the OTP valid?

1 hour from when it is generated in the FATOORA portal. If it expires, generate a new one and re-enter it in the wizard.

What is the difference between Developer and Simulation sandbox modes?

In Developer mode the OTP is not validated (any placeholder works) and you can only send invoices from ZATCA’s fixed test VAT 399999999900003. In Simulation mode the OTP must be real and you can send from any registered party.

Can I test in Simulation without a real FATOORA account?

No. Simulation requires a real FATOORA account and taxpayer to generate a valid OTP. Use Developer mode if you want to test the flow without a real account.

More available in our Saudi Arabia FAQ section.

🇸🇦 Invopop resources for Saudi Arabia


Compliance	Invoicing compliance in Saudi Arabia Compliance timeline
Apps	Saudi Arabia
Guides	Registration Clearance & reporting
FAQ	Saudi Arabia FAQ
GOBL	Saudi Arabia Tax Regime ZATCA Addon
GitHub	gobl.sa.zatca

Participate in our community

Ask and answer questions about invoicing in Saudi Arabia →

Networks

Countries

Set-up

GOBL

Apps

API

Features

ZATCA supplier registration in Saudi Arabia

Sandbox environments

How it works

ZATCA register party workflow

The onboarding wizard

Reading registrations

Unregistration (sandbox only)

ZATCA unregister supplier workflow (sandbox only)

Multi-branch entities

FAQ

Participate in our community

​Sandbox environments

​How it works

ZATCA register party workflow

​The onboarding wizard

​Reading registrations

​Unregistration (sandbox only)

ZATCA unregister supplier workflow (sandbox only)

​Multi-branch entities

​FAQ

Participate in our community

Sandbox environments

How it works

The onboarding wizard

Reading registrations

Unregistration (sandbox only)

Multi-branch entities

FAQ