@spree/docs 0.1.183 → 0.1.184

package/dist/developer/core-concepts/catalogs.md

@@ -0,0 +1,140 @@
+---
+title: Catalogs
+description: Showing different products and prices to different audiences — a wholesale range, a channel-specific selection, or one company's negotiated pricing.
+---
+
+## Overview
+
+Not every shopper should see the same store. A wholesale buyer gets trade prices and a range retail never sees. A negotiated account has its own agreed pricing. A retail till carries a subset of what the website does.
+
+A catalog answers both halves of that at once: **what an audience sees**, and **what they pay**.
+
+```mermaid
+flowchart LR
+    Catalog --> Assortment["Assortment<br/><i>which products</i>"]
+    Catalog --> PriceList["Price list<br/><i>what they cost</i>"]
+    Catalog --> Audience["Assignments<br/><i>who gets it</i>"]
+```
+
+```mermaid
+erDiagram
+    Catalog ||--o{ CatalogProduct : "assortment"
+    Catalog ||--o{ CatalogAssignment : "audiences"
+    Catalog }o--o| PriceList : "optional pricing"
+    CatalogAssignment }o--|| Channel : "one of"
+    CatalogAssignment }o--|| CustomerGroup : "one of"
+    CatalogAssignment }o--|| Market : "one of"
+    CatalogAssignment }o--|| Company : "one of"
+
+    Catalog {
+        string name
+        boolean active
+        integer position
+    }
+```
+
+## The two modes
+
+The single most useful thing to understand about catalogs is that an **empty assortment means something different from a full one** — it's the switch between the two ways a catalog is used.
+
+
+  - **Pricing overlay** — **Assortment empty.** Nothing is hidden — the audience browses the normal store — but the attached price list applies.
+
+    This is how "this company sees everything, just at their negotiated prices" is expressed.
+  - **Restricted range** — **Assortment has products.** The audience sees *only* what's in it.
+
+    This is how a wholesale-only range, or a channel-specific selection, is expressed.
+
+
+That's worth pausing on, because it's the one behaviour that surprises people: adding a product to an empty catalog doesn't add one item to what a customer sees — it switches the catalog into restricting mode, and they now see *only* that item.
+
+## Creating one
+
+```typescript Admin SDK
+const catalog = await adminClient.catalogs.create({
+  name: 'Wholesale',
+  price_list_id: 'plist_xxx',
+  active: true,
+})
+```
+
+The price list is optional. A catalog with an assortment and no price list restricts the range at normal prices; a catalog with a price list and no assortment adjusts prices without hiding anything.
+
+### Filling the assortment
+
+```typescript Admin SDK
+// Add products (a bare array of IDs)
+await adminClient.catalogs.products.create(catalog.id, ['prod_xxx', 'prod_yyy'])
+
+const { data: products } = await adminClient.catalogs.products.list(catalog.id)
+
+await adminClient.catalogs.products.delete(catalog.id, 'prod_xxx')
+```
+
+Products are positioned, so a catalog also controls the order they're presented in.
+
+When a catalog should restrict to exactly what its price list covers, there's a shortcut that copies those products in rather than making someone add them by hand:
+
+```typescript Admin SDK
+const { added_count } = await adminClient.catalogs.importProducts(catalog.id)
+```
+
+## Choosing the audience
+
+A catalog is assigned to one of four things:
+
+| Assign to | Meaning |
+|---|---|
+| **[Channel](channels.md)** | Everyone buying through this channel — an app, a retail till |
+| **[Customer group](customers.md)** | A segment — wholesale accounts, staff, a loyalty tier |
+| **[Market](markets.md)** | Everyone in a region |
+| **[Company](companies.md)** | One B2B organization |
+
+```typescript Admin SDK
+await adminClient.catalogs.assign(catalog.id, {
+  assignable_type: 'customer_group',
+  assignable_id: 'cgrp_xxx',
+})
+```
+
+> **NOTE:** **A company assignment covers the whole subtree.** Assign the group-wide catalog once at the root of a [company tree](companies.md) and every division below inherits it — no re-assigning per branch. A branch can still add its own catalog on top.
+
+## What a shopper ends up seeing
+
+When several catalogs could apply, they combine rather than compete:
+
+**Step 1: Find the catalogs that apply**
+
+For a company buyer, that's the catalogs on their node **and its ancestors**. Otherwise their customer group's catalogs. Otherwise the channel's default catalog, if it has one.
+
+  **Step 2: Combine the assortments**
+
+The shopper sees the union of what those catalogs contain — so a division's extra catalog adds to the group's range rather than replacing it.
+
+  **Step 3: Any empty assortment lifts the restriction**
+
+If one applicable catalog is a pricing overlay, the restriction is off and the shopper sees the full range. An overlay is explicitly "don't hide anything", and that has to win — otherwise adding negotiated pricing would accidentally narrow someone's catalog.
+
+
+Gated storefront access is checked before any of this — a shopper who has to sign in never reaches catalog resolution.
+
+## How pricing resolves
+
+Prices are checked in order, and the first match wins:
+
+1. Price lists attached to the applicable catalogs, **nearest first** — the buyer's own company node before its parent's
+2. Ordinary price lists whose rules match
+3. The product's base price
+
+Nearest-first is what lets a subsidiary hold a better-negotiated rate than the group's, without disturbing anyone else.
+
+> **WARNING:** A price list attached to a catalog applies **because the catalog applies** — its own rules are not consulted, and it's excluded from ordinary rule matching.
+> 
+> That exclusion is load-bearing: a price list with no rules would otherwise match everyone, and one company's negotiated pricing would leak to the entire storefront.
+
+## Related
+
+- [Companies](companies.md) — B2B buyers and the subtree rule
+- [Pricing](pricing.md) — price lists and rules
+- [Products](products.md) — the catalog being narrowed
+- [Channels](channels.md) — per-channel default catalogs

package/dist/developer/core-concepts/commissions.md

@@ -0,0 +1,253 @@
+---
+title: Commissions
+description: What a marketplace charges its sellers — rates and the rules that target them, how a fee is calculated, and the settlement record left behind.
+---
+
+## Overview
+
+A marketplace earns by taking a cut of what its sellers sell. Commissions are how you describe that cut and how Spree records what was actually charged.
+
+There are two halves, and — as with [promotions and discounts](promotions.md) — keeping them apart is what makes the whole thing work:
+
+| | |
+|---|---|
+| **Commission rate** | Configuration. What you charge, and when. Editable. |
+| **Commission line** | The record of one charge on one sale. Frozen. |
+
+Editing a rate changes what the *next* sale is charged and never what a past one was.
+
+```mermaid
+flowchart LR
+    Sale["A seller's item sells"] --> Resolve["Find the first<br/>matching rate"]
+    Resolve --> Calc["Calculate the fee<br/>and its tax"]
+    Calc --> Line["Commission line<br/><i>frozen</i>"]
+
+    style Line fill:#e8f5e9,stroke:#2e7d32
+```
+
+> **NOTE:** **A commission is not a [fee](fees.md).** A fee is charged to the shopper and rolls into the order total. A commission is a settlement between the marketplace and the seller — the customer never sees it, and it never touches the order total.
+
+## Rates
+
+A rate says what to charge. It's either a percentage of the sale or a flat amount.
+
+```typescript Admin SDK
+await adminClient.commissionRates.create({
+  name: 'Electronics',
+  code: 'electronics',
+  kind: 'percentage',
+  value: '12.5',
+  enabled: true,
+})
+```
+
+| Attribute | Description |
+|---|---|
+| `name` | What operators call it |
+| `code` | An optional short handle, unique per store |
+| `kind` | `percentage` or `fixed` |
+| `value` | The percentage, for a percentage rate |
+| `enabled` | Whether it's in play |
+| `position` | Where it sits in the list — see below |
+| `tax_inclusive` | Whether the fee is charged on the gross or net amount |
+| `include_shipping` | Whether delivery is commissioned too |
+| `commission_tax_rate` | An explicit tax rate for the fee, overriding the default |
+
+## The list is the precedence
+
+This is the most important thing to understand about commission rates, and it's deliberately different from how you might expect.
+
+When a sale happens, Spree walks the store's enabled rates **in list order** and takes **the first one whose rules match**. There's no scoring, and no built-in hierarchy where a product rule beats a category rule.
+
+> **INFO:** What an operator sees in the table is exactly what resolution does. A marketplace that wants a different answer drags a row up or down, rather than reasoning about which rule type counts as "more specific".
+
+Two consequences worth planning around:
+
+**A rate with no rules matches everything.** That's how you express a default — and it belongs at the **bottom** of the list, because anything below it is unreachable.
+
+**New rates are created at the top.** A rate is created to say something more specific than what's already there, and appending it below the catch-all would leave it dead on arrival.
+
+```mermaid
+flowchart TB
+    R1["1. Electronics — 12.5%<br/><i>category rule</i>"] --> R2
+    R2["2. Trusted sellers — 8%<br/><i>seller rule</i>"] --> R3
+    R3["3. Default — 15%<br/><i>no rules</i>"]
+
+    style R3 fill:#fff3e0,stroke:#e65100
+```
+
+If nothing matches, **no commission is charged**. That's a real answer, not a fallback — a marketplace with no rate covering a sale charges nothing rather than inventing a default nobody configured.
+
+## Rules
+
+Rules narrow when a rate applies. A rate can hold several, and **all of them must match** — while the IDs listed *within* one rule are alternatives.
+
+So "electronics **and** these three sellers" is two rules on one rate.
+
+```typescript Admin SDK
+// Every rule kind, with the schema describing its settings — so an editor
+// is built from what this marketplace actually has, not a hardcoded list
+const { data: types } = await adminClient.commissionRates.ruleTypes()
+
+await adminClient.commissionRates.update('crate_xxx', {
+  rules: [
+    { type: 'category_rule', preferences: { category_ids: ['ctg_xxx'] } },
+    { type: 'seller_rule', preferences: { seller_ids: ['sel_xxx', 'sel_yyy'] } },
+  ],
+})
+```
+
+Rules are replaced wholesale on update — send the full set you want.
+
+### The four rule types
+
+<details>
+<summary>Product rule — these specific products</summary>
+
+Charges the rate only for the products named.
+
+    Products are stored as real references rather than a list of IDs in a field, so a marketplace naming a thousand products stays workable.
+
+</details>
+
+  <details>
+<summary>Category rule — anything filed here</summary>
+
+Charges the rate for products in the named categories.
+
+    **A category matches its descendants too.** A rate on "Electronics" governs a camera under Electronics → Cameras, so you don't restate the rule every time someone adds a subcategory.
+
+</details>
+
+  <details>
+<summary>Seller rule — these sellers</summary>
+
+Charges the rate only when the seller is one of those named. This is how a negotiated rate for a large vendor is expressed.
+
+    A rule naming nobody narrows nothing — and rather than silently charging every seller, it's treated as not matching.
+
+</details>
+
+  <details>
+<summary>Item total rule — sales in a value band</summary>
+
+Charges the rate only on sales within a value range. "15% under 50, 10% above" is two rates, each holding one of these.
+
+    Bounds are **inclusive at the bottom and exclusive at the top**, so two bands can meet at a number without overlapping or leaving a gap.
+
+    The band is weighed against exactly the same figure the fee is charged on, so a band can never admit a sale the fee then treats as worth something different.
+
+</details>
+
+
+One rule of each type per rate. Rules can only name products and sellers belonging to the same store — pointing one at another marketplace's catalog is refused rather than quietly ignored.
+
+## What the fee is charged on
+
+Two settings on the rate decide the base, and both matter more than they first appear.
+
+### Gross or net
+
+`tax_inclusive` decides whether the fee is charged on the amount including the customer's tax, or excluding it.
+
+**The default is net**, and that default is deliberate: the customer's VAT isn't the seller's revenue, and charging commission on it would tax the same money twice under two different regimes.
+
+Discounts come off either way. Commission is charged on what the customer actually paid, so a promotion is the seller's concession.
+
+### Delivery
+
+`include_shipping` adds a commission on the delivery charge as well as the goods.
+
+> **WARNING:** A **flat** rate cannot commission delivery. A flat fee is charged per sale, so charging the same amount again on the parcel would double it. A marketplace wanting a flat charge on delivery states it as its own rate.
+
+## Amounts and currencies
+
+Money is stated per currency, never converted:
+
+```typescript Admin SDK
+// A percentage, with a floor and a cap in each currency
+await adminClient.commissionRates.create({
+  name: 'Standard',
+  kind: 'percentage',
+  value: 10,
+  bounds: {
+    USD: { min_amount: 1, max_amount: 50 },
+    EUR: { min_amount: 1, max_amount: 45 },
+  },
+})
+
+// A flat fee, stated per currency
+await adminClient.commissionRates.create({
+  name: 'Listing fee',
+  kind: 'fixed',
+  value: 0,
+  amounts: { USD: '5.00', GBP: '4.00' },
+})
+```
+
+- **`amounts`** — what a flat fee charges, per currency
+- **`bounds`** — the floor and cap a percentage charges within, per currency
+
+Both replace the whole set on write, and writing `bounds` never disturbs `amounts`.
+
+Percentages and flat fees behave differently across currencies, for a good reason:
+
+| | Behaviour in a currency with no stated amount |
+|---|---|
+| **Flat rate** | Doesn't apply — resolution falls through to the next rate. Converting one currency's figure into another would invent a fee nobody set. |
+| **Percentage** | Still applies, uncapped. A ratio travels; its floor and cap don't. A marketplace that capped its dollar fees hasn't thereby said it wants no commission on euro sales. |
+
+A flat fee is charged **per unit**, not per line. Otherwise buying three cameras together would earn a third of buying them separately — letting the shopper decide the marketplace's revenue.
+
+## Tax on commission
+
+The commission is the marketplace's own service to the seller. That's a separate taxable supply from the seller's sale to the customer, with its own place of supply — which is why the two taxes are worked out independently and never mix.
+
+The tax rate is resolved in this order:
+
+1. An explicit `commission_tax_rate` on the rate
+2. The store's tax engine, using the **seller's** address
+3. The store's default commission tax rate
+
+> **WARNING:** Commission tax follows the **seller's** jurisdiction, not the shopper's. A German marketplace charging a French seller is a cross-border B2B supply, and the shopper's location has nothing to do with it.
+
+Each line carries a `taxability_reason` — `standard_rated`, `zero_rated`, `reverse_charge` — using the same vocabulary as [tax lines](taxes.md) on goods. An invoice explaining why a marketplace fee was reverse-charged should use the same words as one explaining it for goods.
+
+## Commission lines
+
+When an order is placed, the resolved rate is applied and the result frozen as a commission line — one per item, plus one per delivery where the rate includes it.
+
+| Attribute | Description |
+|---|---|
+| `amount` | The fee |
+| `tax_amount` | Tax on the fee |
+| `total` | The two added together |
+| `rate` / `kind` | A snapshot of what was applied |
+| `tax_rate` / `taxability_reason` | How it was taxed, and why |
+| `country_code` / `state_code` | The seller's jurisdiction |
+| `currency` | The sale's currency |
+| `line_item_id` / `fulfillment_id` | What was commissioned — exactly one |
+| `commission_rate_id` | The rate, if it still exists |
+
+```typescript Admin SDK
+const { data: lines } = await adminClient.commissionLines.list({
+  filter: { seller_id_eq: 'sel_xxx' },
+})
+```
+
+**Every field is a snapshot.** Editing the rate afterwards changes nothing here, and neither does deleting it — a retired rate is soft-deleted precisely so "which rate charged this" stays answerable.
+
+There is **no write path**. Lines are read-only in the API, and correcting a charge means recording a reversal rather than editing history — the discipline any ledger needs.
+
+## What this doesn't do
+
+Commission lines say what the marketplace charged. They don't move money.
+
+> **WARNING:** Open source has **no payout ledger**. Paying sellers means connecting a provider such as Stripe Connect, or building against the commission lines and [payment splits](sellers.md#one-checkout-several-sellers). Scheduled payout runs, refund clawbacks and reconciliation are Enterprise features.
+
+## Related
+
+- [Sellers](sellers.md) — marketplaces, order splitting and payment splits
+- [Taxes](taxes.md) — the tax vocabulary commission lines share
+- [Fees](fees.md) — buyer-facing charges, which commissions are not
+- [Promotions](promotions.md) — the same rules-and-record split, on the buyer side

package/dist/developer/core-concepts/companies.md

@@ -0,0 +1,240 @@
+---
+title: Companies
+description: B2B buyers as organizations — a company tree with members, shared addresses, and purchases made on the company's behalf.
+---
+
+## Overview
+
+Selling to businesses breaks an assumption most storefronts make: that a customer is a person. A business buyer is a person acting *for* an organization — one that has other buyers, several delivery sites, a VAT number, and a finance team who wants to see everything anyone ordered.
+
+A company in Spree models that. And because real organizations aren't flat, a company can be a **tree**: a parent with subsidiaries, divisions, regional units, each with its own people and addresses.
+
+```mermaid
+flowchart TB
+    Root["Acme Group<br/><i>company</i>"]
+    Root --> EU["Acme Europe<br/><i>company</i>"]
+    Root --> US["Acme US<br/><i>company</i>"]
+    EU --> Sales["Sales<br/><i>division</i>"]
+    EU --> Ops["Operations<br/><i>division</i>"]
+
+    style Root fill:#e3f2fd,stroke:#0077ff
+    style EU fill:#e3f2fd,stroke:#0077ff
+    style US fill:#e3f2fd,stroke:#0077ff
+```
+
+A node is one of two kinds, and the difference is about tax, not hierarchy:
+
+| Kind | What it is |
+|---|---|
+| `company` | A legal entity — it can hold a tax registration |
+| `division` | An organizational unit inside one — it cannot |
+
+Trees are capped at five levels, and the root must always be a `company`.
+
+```mermaid
+erDiagram
+    Company ||--o{ Company : "parent of"
+    Company ||--o{ CompanyMembership : "members"
+    Company ||--o{ Address : "address book"
+    Company ||--o{ CompanyInvitation : "pending invites"
+    Company ||--o{ TaxIdentifier : "legal entities only"
+    Company ||--o{ Order : "purchases"
+
+    Company {
+        string name
+        string kind
+        string parent_id
+    }
+    CompanyMembership {
+        string customer_id
+        string email
+    }
+```
+
+## Membership covers a subtree
+
+Someone belongs to a company through a membership, and **that standing reaches everything below the node** — not just the node itself.
+
+So a buyer attached to "Acme Europe" can act for Sales and Operations beneath it, without anyone creating three memberships. Give someone standing at the root and they cover the whole group.
+
+This is why authorization always asks "does this person have standing on this node *or any of its ancestors*", never "is this person a member of exactly this node".
+
+```typescript Store SDK
+// Which companies can this customer act for?
+const { data: memberships } = await client.account.companies()
+
+memberships.forEach((m) => {
+  m.company.name      // "Acme Europe"
+  m.company.ancestors // [{ name: "Acme Group", … }] — the path above it
+})
+```
+
+> **NOTE:** **In open source, every member can do everything within their standing** — buy, see the subtree's orders, and manage addresses and members. There are no company roles; the `role` label on a membership is cosmetic.
+> 
+> To restrict what individual people may do, see [company governance](#company-governance) below.
+
+## Adding people
+
+Both the dashboard and the storefront add members the same way — by email:
+
+```typescript Store SDK
+const result = await client.companies.members.create('comp_xxx', {
+  customer_email: 'buyer@acme.com',
+})
+```
+
+What comes back depends on whether that email is already a customer:
+
+- **An existing customer** becomes a member straight away.
+- **An unknown email** produces an invitation, valid for 30 days, and an email with a link.
+
+You can tell which by the ID prefix — `cmem_` for a membership, `cinv_` for an invitation.
+
+Accepting an invitation either signs an existing customer in, or registers a new account with the invited email. Either way it ends as a membership:
+
+```typescript Store SDK
+// The token comes from the invitation email — no sign-in needed to read it
+const invitation = await client.companyInvitations.lookup(token)
+invitation.company_name
+
+await client.companyInvitations.accept(token, {
+  first_name: 'Dana',
+  last_name: 'Reid',
+  password: 'a-strong-password',
+})
+```
+
+Memberships are always active and always backed by a real customer. Anything still waiting lives on the invitation, so there's no such thing as a half-active member.
+
+## Buying for a company
+
+A cart and an order can name a company. That's what turns a personal purchase into a company one — it decides which addresses are on offer, whose tax registration applies, and who else will see the order.
+
+```typescript Store SDK
+await client.carts.update(cartId, { company_id: 'comp_xxx' })
+```
+
+A buyer with exactly one membership doesn't need to choose; it resolves on its own. A buyer who belongs to several names the node — and it must be one they have standing on.
+
+The company is **frozen onto the order** at completion, like the addresses and prices. Reorganize the tree next year and last year's order still explains itself.
+
+```typescript Store SDK
+// Everything anyone in the subtree has bought
+const { data: orders } = await client.companies.orders.list('comp_xxx')
+```
+
+That subtree rollup is the feature a finance team actually asks for: one place showing what the whole organization spent, without chasing individual accounts.
+
+## The shared address book
+
+A company keeps its own addresses — ship-to sites, a billing address — separate from any individual's. They're labelled, and one of each kind can be the default.
+
+```typescript Store SDK
+await client.companies.addresses.create('comp_xxx', {
+  label: 'Northern Warehouse',
+  first_name: 'Goods',
+  last_name: 'Inwards',
+  address1: '14 Dock Road',
+  city: 'Rotterdam',
+  country_code: 'NL',
+  postal_code: '3011',
+  default_shipping: true,
+})
+```
+
+Note that a delivery site is just an address. Ten warehouses do not mean ten company nodes — nodes exist for organizational and legal structure, addresses for where things go.
+
+## Tax
+
+Tax registrations and exemption certificates live **only on legal entities**, and a purchase resolves tax through the node's nearest `company` ancestor.
+
+```typescript Admin SDK
+await adminClient.companies.taxIdentifiers.create('comp_xxx', {
+  kind: 'eu_vat',
+  value: 'NL123456789B01',
+})
+
+// Validation runs against the official registry, in the background
+await adminClient.companies.taxIdentifiers.validate('comp_xxx', 'txid_xxx')
+```
+
+> **WARNING:** The walk stops at the first `company` node, **whether or not it holds a registration**. A subsidiary with no VAT number of its own therefore has none — it never quietly borrows its parent's, because in most jurisdictions that would be a false declaration.
+
+Exemption certificates hang off a legal entity and are scoped to the country or state that issued them. Check whether a certificate is `active` rather than reading its status — a verified certificate stops exempting once it expires, and `active` accounts for that.
+
+See [Taxes](taxes.md) for how these reach the tax calculation.
+
+## Company governance
+
+Open source deliberately trusts every member equally. That's the right default for a company of five people, and the wrong one for a company of five hundred — where a junior buyer should not be able to place a £40,000 order, remove their manager, or see what another division spent.
+
+Company governance adds that control. It works through the same endpoints and the same data, so nothing about your storefront integration changes when it's switched on — the calls you already make simply start enforcing.
+
+- [Requires a Spree Enterprise licence](https://spreecommerce.org/enterprise/) — Company roles, order approvals, spending limits and governance audit history are part of Spree Enterprise. See what's included, or talk to the team about your use case.
+
+### Company roles
+
+Where open source has a cosmetic label, Enterprise has real roles built from a fixed set of capabilities:
+
+| Capability | Allows |
+|---|---|
+| `place_orders` | Completing a purchase |
+| `approve_orders` | Approving what others submit |
+| `view_node_purchases` | Seeing this node's orders |
+| `view_company_purchases` | Seeing the whole subtree's orders |
+| `manage_company_members` | Adding and removing people |
+| `manage_company_addresses` | Editing the address book |
+
+Roles are **data, edited by the company's own administrator** rather than by your staff — the buying organization manages its own structure, which is the point of self-service. Guards prevent someone granting themselves more than they hold.
+
+These are entirely separate from [staff roles](staff-roles.md). A company role never reaches anything belonging to the store.
+
+### Order approvals
+
+A member without `place_orders` submits their basket instead of completing it. Someone with `approve_orders` reviews and releases it.
+
+```mermaid
+flowchart LR
+    Buyer["Buyer submits"] --> Pending["Awaiting approval"]
+    Pending --> Approved["Approved → order placed"]
+    Pending --> Rejected["Rejected, with a reason"]
+```
+
+Checkout returns a well-known `approval_required` response rather than a generic failure, so a storefront can show the right message and the right next step. The approval history is append-only — who asked, who decided, when.
+
+### Spending limits
+
+Limits are set per member or per node, with a reset period — £5,000 a month for a buyer, £50,000 for a division. They're enforced at completion, alongside approvals, so an over-limit basket is caught before payment rather than after.
+
+### Restricted self-service
+
+The same storefront endpoints — the company directory, address book, member management, order history — become capability-gated. A member without `view_company_purchases` sees their own node's orders and not the group's; a member without `manage_company_members` can read the team but not change it.
+
+> **INFO:** **Nothing about the data model changes.** Governance enforces through a policy layer and the checkout validation hooks, over the same companies, memberships and endpoints described on this page. You can build a B2B storefront against open source today and have it work unchanged when governance is enabled.
+
+Payment terms and net invoicing, quotes, and a packaged buyer portal are on the Enterprise roadmap — [talk to the team](https://spreecommerce.org/enterprise/) if those matter to your timeline.
+
+## Managing companies as staff
+
+```typescript Admin SDK
+// Roots only
+const { data: roots } = await adminClient.companies.list({ parent_id_null: 1 })
+
+// Children of one node
+const { data: children } = await adminClient.companies.list({ parent_id_eq: 'comp_xxx' })
+
+const division = await adminClient.companies.create({
+  name: 'Sales',
+  kind: 'division',
+  parent_id: 'comp_xxx',
+})
+```
+
+Moving a branch is an update with a new `parent_id`. Deleting a node removes its whole subtree, and is refused outright once any order exists beneath it — history doesn't get deleted to tidy up an org chart.
+
+## Related
+
+- [Catalogs](catalogs.md) — giving a company its own range and prices
+- [Customers](customers.md) — the accounts memberships are built on
+- [Taxes](taxes.md) — registrations and exemptions
+- [Orders](orders.md) — company purchases