Tenants, branches, and organisations

CargoSurge has three levels of grouping: Organisation → Tenant → Branch. This article explains when each one is the right container.

Overview

• Organisation — a parent container for multiple tenants. Used by groups and franchises. Most CargoSurge customers don't need one; they have a single tenant.
• Tenant — your company's workspace. Isolated data, one subscription, one admin team. This is what gets created at sign-up.
• Branch — a sub-unit inside a tenant. Dubai office, Jebel Ali warehouse, Abu Dhabi branch. Branches share master data and settings but can scope users, bookings, and invoices separately.

Think of it this way: one tenant = one legal entity. If two companies share ownership but have different tax registrations, they're two tenants (ideally under one organisation). One tenant with multiple physical locations, same legal entity? That's one tenant with multiple branches.

When to use each

Single tenant, no branches — solo office, 1–15 people. Don't add branches you don't need; it complicates reporting.

Single tenant with branches — one legal entity with multiple offices or warehouses. Examples:

• Forwarder with a Dubai office, Abu Dhabi office, and Jebel Ali warehouse.
• 3PL with three warehouses in different cities.

Organisation with multiple tenants — two+ legal entities under common ownership. Each tenant bills separately but the organisation admin can see roll-up reporting. Examples:

• Parent FZ company with a separate KSA subsidiary (different tax registrations, different local laws).
• Franchise network where each franchisee is a separate legal entity.

How branches work

Once you create a branch (Settings → Branches → + New Branch), you get:

• An assignable scope — every booking, invoice, quote, and shipment can be tagged to a branch.
• Branch-scoped users — a user can be restricted to "see only Dubai office's data" via their user-level branch assignment.
• Branch-specific bank details & addresses — your invoices can carry the right branch's info based on which branch raised the invoice.
• Reporting filters — every financial report supports "by branch" grouping.

Branches do not get their own subscription or user limits — those stay at the tenant level.

How organisations work

Organisations are platform-managed — you don't create one yourself. If you're a group considering multi-tenant structure, contact sales before you sign up the children; it's much easier to structure the group from the start than to migrate later.

Once set up:

• Each tenant has its own subscription (may be independently billed or group-rolled-up).
• Each tenant has its own users, data, and settings.
• An ORG_ADMIN role can view cross-tenant reporting but can't mutate data inside a tenant without also having a role there.
• Inter-tenant flows like Cross-Tenant Consolidations let one tenant's booking be consolidated by another tenant's master booking — see the Forwarding section.

Common pitfalls

Where to go next

• Roles & Permissions Matrix — how user access scopes to tenants and branches.
• Users & Roles admin — the actual UI for assigning branch scope to users.