Branches

A branch is one operating location of a company — a showroom, depot, service centre or office — and it is the place that documents, stock and people are keyed to. Each branch belongs to one company (its Partner Account). Orders, invoices, purchase documents, stock movements, payments and many other records name both the company and the branch they belong to. You set up branches once, after your companies exist and before people start transacting from those locations.

Overview

Branches are master data. A new organization starts with one company and no branches, and branches are optional: an organization that works from a single location can run without them. If you do create branches, xMatix uses them in four ways:

• Documents. A transaction names the branch it was raised at. xMatix checks that the branch really belongs to the document's company and that it is active.
• Stock. Stock is held per company and branch, and every storage location inside a warehouse belongs to exactly one branch. Moving stock between branches is a branch transfer.
• Tax. A branch can carry its own GST registration. Documents raised at that branch then use the branch's GSTIN and state.
• People. A resource's Default Branch fills the branch on the documents they create. On the mobile app, the branch's map position is the centre of the optional check-in location gate.

When to use it

Create a branch for every physical location that keeps its own stock, raises its own documents, holds its own GST registration or is where staff check in. If your organization truly operates from one location, you can hide the branch dimension everywhere instead (see Configuration).

How xMatix handles it

• Where branches live. Branches are part of the core platform. Open Branches in the Platform app (after Accounts and Items). Branches also appear in the Warehouse app and among the masters of the Sales, Procurement and Partner Onboarding settings apps. All of these open the same list and records.
• One company per branch. Partner Account names the company that owns the branch. When a company has at least one branch, every document for that company must name one of its branches. A company with no branches cannot have a branch on its documents.
• Branch pickers follow the company. On documents, the Branch lookup lists only the branches of the company already chosen on the document.
• Values copied from the GST registration. When you pick a GST Registration, xMatix copies its GSTIN and its state (into Source of Supply) onto the branch when you save. If Partner Account is still empty, it also fills it from the registration.
• Defaults handed to documents. A purchase-side document raised at the branch takes its supplier from the branch's Default Supplier Account if the supplier was left empty. A sales or purchase document takes its place of supply from the branch's Source of Supply if that field was left empty.

Prerequisites

• The company that owns the branch must already exist and be active. A new organization's own company is created for it. Further companies are onboarded under Setup → Feature Hub → Administration → Org Settings → Companies (see Tenants, companies and organizations).
• Optional records to create first, if you want to link them: the branch's Address (a contact address), its GST Registration, its Business Hours and its Business Unit.
• Create and edit access to the Branch entity in your security profile.

Procedure

Step 1 — Open the branch list

Open the app launcher, choose the Platform app (or Warehouse) and select Branches. The list has these views: All Branches, All Active Branches, All Sales Branches and All Service Branches. Check the list before you add anything. A duplicate branch splits stock and documents between two records, and nothing reconciles them.

Step 2 — Create the branch

Select New. The create form opens with the identity fields at the top:

1. Enter Name and a Code. The code must be unique across all branches.
2. Choose the owning company in Partner Account.
3. Choose Branch Type: Sales Branch or Service Branch. It is required.
4. Optionally enter a Marketing Name and choose Business Hours.

The form has three tabs below that:

• Contact Details — Address, Mobile, E-mail, Website and Sales Phone.
• Operational Details — the checkboxes Allow Purchase, Allow Sales, Allow Inventory, Allow Service, Active, Home Delivery and Service Pickup Drop.
• GST Details — GST Registration and Geo Location.

Tick Active: an inactive branch cannot be used on new documents. Select Save. The record page opens.

Step 3 — Review and complete the record

The record page has two tabs: Details and Storage Locations.

Details shows three sections:

• Branch Details — Name, Code, Business Hours, Business Unit, GST Registration, GSTIN, Branch Type, Default Supplier Account.
• Contact Information — Address, Source of Supply, Mobile, Website, Geo Location.
• Operational Control — the checkboxes.

Fields the create form does not show, such as Business Unit and Default Supplier Account, are filled in here. Select Edit in the page header to change the record.

Step 4 — Add storage locations

On the Storage Locations tab, select New to add the zones, bins and vans inside the branch. Every stock figure names a storage location, so a branch that holds stock needs at least one. See Storage locations and vans.

Step 5 — Set the branch on people

Open each Resource who works from the branch and set Default Branch (with Default Partner Account). From then on, documents that person creates get this company and branch automatically, unless the document already has a company or branch. The mobile check-in location gate also measures distance from the resource's default branch.

Step 6 — Retire a branch

To stop using a branch, open it, select Edit, clear Active and save. Existing documents keep the branch. New and edited documents that name it are rejected with "Branch is Inactive.". The branch then shows only in All Branches, not in All Active Branches. Prefer this to deleting a branch that has history.

Fields

The reference page also lists Parent Location, Default Inventory Valuation Method, Inventory Valation Method, Payroll Business Hours, Document Name Code, Phone, Sales Email, Service Email and Service Phone. These are not on the default layouts and are not used by any built-in process today. Document Name Code is the exception: an invoice's document series is built from the company's and the branch's codes. See the Branch entity reference for every field.

Business rules

• Code is required and unique, and E-mail is unique across branches.
• Branch Type is required.
• Sales Phone, when filled, must be exactly 10 digits. Otherwise the save fails with "Phone number provided is not in a valid format."
• Default Supplier Account must exist and must be flagged as a supplier account. Otherwise saving fails with "Default Supplier Account is invalid." or "Default Supplier Account must be an account flagged as a supplier account."
• GST Registration. Choosing or changing it copies the registration's GSTIN and state onto the branch, and fills an empty Partner Account. Clearing the registration leaves the copied values in place. Editing other fields never re-copies them, so a manual change to Source of Supply survives later edits.
• Branch checks on documents. When a document is saved, xMatix checks its company and branch together:
  • If the company has branches and no branch is given, the save fails with "Branch is required for this Partner Account."
  • If the branch belongs to another company, it fails with "Invalid Branch for Partner Account."
  • If the branch is inactive, it fails with "Branch is Inactive."
  • If the company has no branches but a branch is given, it fails with "Invalid branch for partner account."

  These checks apply to orders, quotes, invoices, credit notes, payments, delivery orders, fulfilments, purchase orders, goods receipts, bills, requisitions, shipments, transfers, adjustments, cycle counts, service orders, leads, opportunities and claim batches, among others.

  • Default company and branch from the creator. A new document with no company and no branch gets them from the creating user's resource:
    • The resource's Default Partner Account and Default Branch, when both are set.
    • Otherwise the resource's current partner-resource assignment.
    • Otherwise whichever single default is set.

    xMatix never picks a branch just because a company has only one.

    Example

    A distributor opens a second depot. The administrator creates a branch:

    • Name: North Depot
    • Code: NDP
    • Partner Account: the distributor's own company
    • Branch Type: Sales Branch
    • Business Hours: Standard 9 to 6
    • Active: ticked

    On GST Details, they pick the depot's GST registration. After saving, GSTIN and Source of Supply show that registration's number and state. They add Default Supplier Account = Sunrise Polymers on the record page. On the Storage Locations tab, they create NDP-MAIN (a warehouse) and NDP-VAN1 (a van). Finally, they set Default Branch = North Depot on the three resources who work there.

    The next morning, a sales executive at the depot creates an order. Company and branch are already filled in, and the order's place of supply is the depot's state. A purchase order raised at the depot without a supplier takes Sunrise Polymers.

    Training

    Practice exercise

    In a sandbox:

    1. Create a branch Training Branch (Code TRB, Branch Type Service Branch, Active ticked) for your company. Expected: the record page opens and the branch appears in All Service Branches.
    2. Enter Sales Phone 12345 and save. Expected: "Phone number provided is not in a valid format."
    3. Correct it to a 10-digit number and save.
    4. Clear Active and save. Then try to save a new order for that company with Branch = Training Branch. Expected: "Branch is Inactive."

    Quick reference

    • Branches: Platform app → Branches (also in Warehouse).
    • Required: Name, a unique Code, Branch Type. Always set Partner Account.
    • A company with branches needs a branch on every document; a company without branches cannot have one.
    • GSTIN is read-only; it comes from GST Registration.
    • Default Supplier Account fills empty suppliers on purchase documents raised at the branch.
    • Stock needs a storage location at the branch — add it on the Storage Locations tab.
    • Set Default Branch on each resource so their documents fill the branch automatically.
    • Retire a branch by clearing Active, not by deleting it.

    Permissions

    Branch is an ordinary entity: viewing, creating, editing and deleting branches is controlled by the Branch entity permissions in Setup → Access Control → Profiles → Entity Permissions. The security profiles that ship with xMatix grant full access to Branch. If you want only administrators to maintain branches, remove create, edit and delete from the other profiles but keep read: users need read access to see and pick branches on their documents.

    Changing the organization-shape setting below needs the setup.org.settings.manage capability.

    Configuration

    • Use branches at all. Go to Setup → Feature Hub → Administration → Org Settings. Under Organisation shape, the switch We operate from multiple locations is on by default. Turn it off only if your organization genuinely works from one location. Branch fields then disappear from every screen, list, report and dashboard, and documents are saved without a branch. Branches, branch postal codes, branch time slots and transfers are hidden too. The switch is independent of We run multiple companies.
    • Branch fields and layouts. The create form, record page and views are ordinary layouts and views. You can change them in the Design Studio (see Customizing xMatix).
    • Default branch per user. Set Default Branch and Default Partner Account on each resource. Partner-resource assignments cover people who work across several companies or branches.
    • Mobile check-in location gate. On the mobile app configuration's Check-In tab, the location gate checks that a check-in happens within a radius of the resource's default branch (250 m by default). The branch needs a Geo Location. Without one, the check-in is allowed and only the location is recorded. See Mobile app configuration.
    • Document numbering per branch. A numbering setting under Setup → Feature Hub → Platform → Document Settings can take its series from a field on the document. That lets each branch number its documents independently. See Email templates and document numbering.
    • Assignment by postal code. Branch postal codes map postal codes to branches. Assignment rules can use them to route new records to the branch that covers a customer's postal code.

    Common problems

    "Branch is required for this Partner Account."

    The document's company has at least one branch, so every document for it must name one. Choose a branch, or set Default Branch on your resource so it is filled for you.

    "Invalid Branch for Partner Account."

    The branch on the document belongs to a different company. This usually happens after the company was changed on a document that already had a branch. Pick one of the selected company's branches.

    "Branch is Inactive."

    The branch has been retired. Choose an active branch, or ask an administrator to tick Active on the branch again.

    "Invalid branch for partner account."

    The company on the document has no branches at all, but a branch was given. Clear the branch, or ask an administrator whether the branch was linked to the wrong company.

    My check-in says the branch has no usable coordinates

    Your default branch has no Geo Location, so the location gate cannot measure distance. The check-in still goes through, with your location recorded. An administrator should set the branch's Geo Location.

    The Branch field has disappeared from every screen

    The organization has turned off We operate from multiple locations in Org Settings. Turn it back on if branches are needed.

    Common questions

    Do we have to create branches?

    No. A new organization has one company and no branches, and everything works without them. Create branches when you have more than one location that holds stock, raises documents or registers for GST separately. Once a company has a branch, every document for that company must name one, so create branches for all of that company's locations together. Assign default branches to resources at the same time. If you will only ever have one location, turn off We operate from multiple locations to hide the branch field everywhere.

    Can one branch serve two companies?

    No. A branch belongs to exactly one company through Partner Account, and documents are rejected when the branch and company do not match. If two companies share a building, create a branch for each company. Stock is also held per company and branch, so this keeps each company's stock and documents separate.

    Why does the Allow Sales checkbox not stop sales at a branch?

    The Allow Purchase, Allow Sales, Allow Inventory and Allow Service checkboxes describe the branch, but no built-in process reads them today. A branch with Allow Sales cleared can still be used on an order. If you need to enforce such a restriction, add a validation rule on the document that checks the branch, or retire the branch by clearing Active.

    Can I change a branch's GST registration later?

    Yes. Changing GST Registration re-copies the new registration's GSTIN and state onto the branch when you save. Documents saved earlier keep the values they had. If you clear the registration, the branch keeps the last copied GSTIN and Source of Supply.

    Related topics

    • Branch entity reference
    • Tenants, companies and organizations
    • Storage locations and vans
    • Branch transfers
    • Mobile app configuration
    • Security profiles and the grant matrix
    • Email templates and document numbering