---
title: Customers, companies and branches
description: How customers, companies, branches, staff users and salespeople relate to an order, how to keep your own fields and states on it, and where the conversation with the customer lives.
---

Goal: map a B2B or dealer business onto Bolder: who buys, for which company, from which branch, sold by whom, and what you can store on the order. Every name below is a v2 resource; the [API reference](/api/v2) has the fields.

## Who is who

| Concept | Resource | What it is |
|---|---|---|
| **Customer** | `/customers` | The person an order is for (the order's `contact`). Has an email, a phone, an optional tax id (`tax_id`, e.g. a Chilean RUT) and an optional **salesperson**. |
| **Company** (empresa) | `/shops/{shop_id}/companies` | An institutional customer. Name, tax id and email domain are unique per seller. An order points to one with `company_id`. |
| **Branch** (sucursal) | `/shops/{shop_id}/branches` | A location of the seller. Branches you create through the API are hidden offices: never a pickup point or a shipping origin, so they don't appear in the store locator or at checkout. Use them to group staff, for example one per dealer office. |
| **Staff user** | `/shops/{shop_id}/admins` | Someone who works in the store, with a role (*administrador*, *supervisor*, *vendedor*). Users are assigned to branches with `/shops/{shop_id}/branches/{id}/users`. |

A customer is not a user: customers buy and can sign in to the storefront; users work in the admin or in your app.

## Salespeople and "own" orders

A customer's `salesperson_id` is a staff user. That link decides what a *vendedor* sees: their token carries `orders.read_own` / `orders.write_own`, which give access only to the orders of their own customers. When such a token creates an order, a new customer gets that user as salesperson and the order's `salesperson_id` is set to them. Details are in [Own-records scopes](/api/v2).

Two more effects of branches. A staff user with the full orders scopes who is assigned to branches only sees the orders fulfilled from those branches (a *vendedor* is not affected: they already see only their customers' orders). And staff assigned to other branches are skipped by the staff emails of an order fulfilled from a branch (see [Send order emails](/guides/order-emails)).

## What you can store on an order

- **`company_id`**: the customer's company, settable on create and on any update; filter with `GET /v2/orders?company_id=`.
- **`purchase_order_number`**: the customer's purchase order (OC) number, filterable. Attach the document itself with `POST /orders/{order_id}/documents` (`document_type: purchase_order`).
- **`external_id`**: your own reference, unique per seller, filterable; the safe key for retries.
- **`contact_data`**: free key/value fields (`[{ "key": "visit_window", "value": "mornings" }]`). They are stored on the order and returned as `custom_data`, but you **can't filter or search** by them.
- **Tags**: free labels (`tags`). Filter with `tag` or `tags`. Use a tag for anything you need to find orders by.

## Your own states with tags

An order has Bolder's own statuses (`status`, `fulfillment_status`). If your process has steps of its own (visit scheduled, installed...), keep them in a tag with a fixed prefix and tell the store about it with the shop setting `website.track_state_tag_prefix`:

- With the prefix `estado:`, the tag `estado:Visita agendada` makes the order's state "Visita agendada".
- `GET /orders/{order_id}/progress` returns that state, when it started, its history and the last comment for the customer.
- The public tracking endpoint (`GET /track/status.json`, see [Forms & Content](/frontend/sdk/forms)) shows the same state to the customer, without any personal data.

To change the state, replace the order's `tags` with the new state tag (keep the other tags), or send `_policies.append_tags: true` to add tags without replacing them.

## The order conversation

`/orders/{order_id}/messages` holds the order's conversation:

- **Messages** (the default) are visible to the customer. Add `notify: true` to also email the message to them.
- **Notes** (`internal: true`) are for staff only and are never shown or emailed to the customer.

The latest staff message is the `comment` returned by `/progress` and by public tracking. Messages need a token issued to a user (the author) with the full orders scopes.

## Next

- [Send order emails](/guides/order-emails): who gets an email when an order changes.
- [Create an order and take payment](/guides/create-an-order).
- [Sign in users from a browser app](/guides/browser-sign-in): a dealer portal where each salesperson sees their own orders.