Customers, companies and branches

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

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

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

Send order emails: who gets an email when an order changes.
Create an order and take payment.
Sign in users from a browser app: a dealer portal where each salesperson sees their own orders.