@spree/docs 0.1.180 → 0.1.181
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Companies & Catalogs
|
|
3
|
+
description: How Spree models B2B buyer organizations — a multi-level company tree with members and an address book — and the catalogs that decide what each audience sees and pays.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Overview
|
|
7
|
+
|
|
8
|
+
A business customer in Spree is a **tree of company nodes**, not a flat account. One node can stand alone — a company with a few members and addresses — or grow into a group: subsidiaries, divisions, regional units, each with its own buyers and ship-to sites.
|
|
9
|
+
|
|
10
|
+
```mermaid
|
|
11
|
+
erDiagram
|
|
12
|
+
Company ||--o{ Company : "parent of"
|
|
13
|
+
Company ||--o{ CompanyMembership : "has many"
|
|
14
|
+
Company ||--o{ CompanyAddress : "has many"
|
|
15
|
+
Company ||--o{ CompanyInvitation : "has many"
|
|
16
|
+
Company ||--o{ TaxIdentifier : "legal entities only"
|
|
17
|
+
Company ||--o{ TaxExemptionCertificate : "legal entities only"
|
|
18
|
+
|
|
19
|
+
Company {
|
|
20
|
+
string name
|
|
21
|
+
string kind "company | division"
|
|
22
|
+
string external_id
|
|
23
|
+
}
|
|
24
|
+
CompanyMembership {
|
|
25
|
+
string role "cosmetic label"
|
|
26
|
+
}
|
|
27
|
+
CompanyAddress {
|
|
28
|
+
string label
|
|
29
|
+
boolean default_billing
|
|
30
|
+
boolean default_shipping
|
|
31
|
+
}
|
|
32
|
+
CompanyInvitation {
|
|
33
|
+
string email
|
|
34
|
+
string token
|
|
35
|
+
datetime expires_at
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Three ideas carry the whole model:
|
|
40
|
+
|
|
41
|
+
- **The tree is structure.** `Spree::Company` is self-referential (`parent_id`), store-scoped, and shallow — depth is capped at five levels. How many ship-to sites a node has never dictates how many nodes exist; addresses are just an address book.
|
|
42
|
+
- **Nodes are typed, and the type decides tax.** A `company` node is a legal entity; a `division` is an organizational unit. Tax registrations and exemption certificates exist only on legal entities, and a purchase's tax always resolves through the node's `legal_entity` — for a `company` that is the node itself, and for a `division` it is its nearest `company` ancestor, whose registrations then cover the division's purchases. The walk stops at that first `company` node whether or not it holds any registration, so a subsidiary with no VAT number of its own has none — it never borrows its parent's.
|
|
43
|
+
- **Membership is standing over a subtree.** A `CompanyMembership` joins a customer to a node, and that standing covers the node and everything below it. Any authorization question — "may this customer act for node N?" — is a membership check on N and its ancestors, never an equality check on one node.
|
|
44
|
+
|
|
45
|
+
## Members and invitations
|
|
46
|
+
|
|
47
|
+
People join by email, from either side — staff in the dashboard or an existing member on the storefront. An email that matches a store customer becomes a membership immediately; an unknown email becomes a `Spree::CompanyInvitation` — a plaintext-token record with a 30-day expiry, whose invite email links to the storefront acceptance page. Accepting either registers a new account (through the standard customer-creation flow, with the invited email) or binds the invitation to the signed-in customer, and lands as a membership either way.
|
|
48
|
+
|
|
49
|
+
Memberships stay always-active and always customer-backed: the pending state lives on the invitation, never as a status on the membership.
|
|
50
|
+
|
|
51
|
+
**In open source, every member can do everything within their standing** — buy, see the subtree's purchases, manage addresses and members. There are no company roles; the `role` string on a membership is a cosmetic label. Finer control (roles, approvals, spending limits) is an Enterprise layer that enforces through the storefront access policy class (`Spree::Dependencies.storefront_access_policy_class`) and the checkout `validate` hooks — injection points that are deliberate no-ops in OSS.
|
|
52
|
+
|
|
53
|
+
## Purchases
|
|
54
|
+
|
|
55
|
+
Carts and orders carry a `company_id` pointing at any node — buying *for* a division means pointing at it. A buyer with exactly one membership resolves to it automatically; a buyer with several names the node on their cart (the `company_id` param on cart update, validated against their standing). The node is frozen onto the order at completion, like every other order attribute, so a placed order's tax treatment stays explainable no matter how the tree changes later.
|
|
56
|
+
|
|
57
|
+
Exemption certificates and the company's tax registration always resolve through `company.legal_entity` — see [Taxes, Discounts & Fees](/docs/developer/core-concepts/taxes-discounts-fees) for how they reach the tax provider.
|
|
58
|
+
|
|
59
|
+
## Catalogs
|
|
60
|
+
|
|
61
|
+
A `Spree::Catalog` narrows what an audience sees and — through an optional price list — what they pay.
|
|
62
|
+
|
|
63
|
+
```mermaid
|
|
64
|
+
erDiagram
|
|
65
|
+
Catalog ||--o{ CatalogProduct : "assortment"
|
|
66
|
+
Catalog ||--o{ CatalogAssignment : "audiences"
|
|
67
|
+
Catalog }o--o| PriceList : "optional pricing"
|
|
68
|
+
CatalogAssignment }o--|| Company : "or"
|
|
69
|
+
CatalogAssignment }o--|| CustomerGroup : "or"
|
|
70
|
+
CatalogAssignment }o--|| Market : "or"
|
|
71
|
+
CatalogAssignment }o--|| Channel : "or"
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- **Assortment** — a positioned product join, and the switch between a catalog's two modes. A *curated* assortment restricts: the audience sees only what's in it. An *empty* assortment is a pricing-only overlay: the attached price list applies and nothing is hidden — which is how "everyone sees the public store, this company just gets special prices" is expressed. An explicit import action copies the price list's products into the assortment when a restrictive catalog should start from the priced range.
|
|
75
|
+
- **Audiences** — assignments to a channel, a customer group, a market, or a company node. A company assignment covers the node's **subtree**: assign the group-wide catalog once at the root, and a branch adds its own extra catalog without re-assigning the shared one.
|
|
76
|
+
- **Visibility** — a buyer resolving to a company node sees the union of the effective catalogs on the node and its ancestors; otherwise their customer group's catalogs apply; otherwise every channel listing (narrowed to the channel's default catalog when one is set). Any effective catalog with an empty assortment lifts the restriction — the union then includes the whole range. Gated storefront access runs first — a login-gated guest never reaches this resolution.
|
|
77
|
+
- **Pricing** — the effective catalogs' price lists are checked nearest node first (the purchase node's own assignments before its parent's), then the ordinary rule-matched price lists, then base prices. A price list attached to a catalog applies *because the catalog applies* — its own rules are not consulted, and it is excluded from generic rule matching so a rule-less list cannot leak to every shopper.
|
|
78
|
+
|
|
79
|
+
## Storefront self-service
|
|
80
|
+
|
|
81
|
+
The Store API ships a full company directory for members: their memberships with ancestor paths (`GET /store/account/companies`), node details and renaming, the address book, members and invitations, and the subtree's completed orders. Authorization on every endpoint is **standing plus the access policy** — never roles, never CanCanCan. The deliberate trade-off: within a company, OSS trusts every member; merchants who need restraint layer the Enterprise governance on the same injection points, with no schema changes.
|