generated from coulomb/repo-seed
Resolve Customer Account question; add commercial subscription research
Record B2B SaaS subscriber tenancy and Stripe billing source notes. Resolve the Customer Account open question: reject it as canonical, add Commercial Record and Commercial Relationship to the Record and relationship layers, and document Subscriber as a convenience term only.
This commit is contained in:
@@ -49,6 +49,11 @@ The repository is focused on research and terminology. The corpus should collect
|
||||
- `synonymity-assertions.md`
|
||||
- `gdpr-pseudonymization.md`
|
||||
|
||||
### commercial-subscription
|
||||
|
||||
- `b2b-saas-subscriber-tenancy.md`
|
||||
- `stripe-customer-billing.md`
|
||||
|
||||
## Source Note Template
|
||||
|
||||
Each source note should capture:
|
||||
|
||||
102
research/commercial-subscription/b2b-saas-subscriber-tenancy.md
Normal file
102
research/commercial-subscription/b2b-saas-subscriber-tenancy.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# B2B SaaS Subscriber and Organization Tenancy
|
||||
|
||||
## Source Type
|
||||
|
||||
Product documentation and industry practice synthesis. Auth0 Organizations and
|
||||
B2B SaaS multi-tenancy guidance; Stytch B2B Auth School org-tenancy model.
|
||||
|
||||
## Domain
|
||||
|
||||
B2B SaaS identity, organization tenancy, subscriber administration, and
|
||||
vendor/customer delineation in IAM products.
|
||||
|
||||
## Why This Source Matters
|
||||
|
||||
IAM vendors explicitly separate the subscribing party (customer/subscriber) from
|
||||
login accounts and from billing records. This source clarifies why "customer
|
||||
account" overloads identity, commercial, and access semantics.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **Subscriber**: Auth0-preferred term for the immediate B2B customer — the
|
||||
party that holds a provisioned tenant and subscription.
|
||||
- **Vendor**: provider of the B2B SaaS application (platform operator).
|
||||
- **Organization tenancy**: architecture where organizations are first-class
|
||||
entities; members are scoped to their organization.
|
||||
- **Member**: end user with membership in an organization (Stytch); distinct
|
||||
from platform-wide user identity.
|
||||
- **Tenant / tenancy holder**: operational partition occupied by a subscriber.
|
||||
- **Org discovery**: determining which organization a user authenticates into.
|
||||
- **Membership control**: granting/revoking which users may access a subscriber's
|
||||
tenant.
|
||||
- **Identity isolation**: per-subscriber credential and IdP configuration vs.
|
||||
platform-wide user population.
|
||||
- **B2B2C / B2B2B variants**: additional "customer" and "consumer" layers below
|
||||
the subscribing organization.
|
||||
|
||||
## Relevant Terminology
|
||||
|
||||
| Term | Source meaning |
|
||||
| --- | --- |
|
||||
| Subscriber | B2B customer occupying a tenant; Auth0 avoids "customer" label. |
|
||||
| Vendor | SaaS platform provider. |
|
||||
| Organization | First-class customer entity; "the organization is the customer" (Stytch). |
|
||||
| Member | Employee or invited user within an organization. |
|
||||
| Tenant | Isolation boundary for subscriber data, branding, and config. |
|
||||
| Customer (informal) | Often used interchangeably with subscriber or organization. |
|
||||
| User | Login identity; may belong to multiple organizations. |
|
||||
| Consumer | End user in B2B2C scenarios below the subscriber org. |
|
||||
|
||||
## Modeling Assumptions
|
||||
|
||||
- **The subscribing company is modeled as an organization**, not as a user
|
||||
account or billing record.
|
||||
- **One human can be a member of multiple subscriber organizations** (contractors,
|
||||
agencies).
|
||||
- **Platform stores users globally**; membership scopes them to subscriber orgs.
|
||||
- **Billing is subscription-based** but handled outside core IAM in most products.
|
||||
- **Vendor administration** may cross tenant boundaries with subscriber consent;
|
||||
subscriber administration does not.
|
||||
- **No IAM product defines "Customer Account"** as a separate entity type.
|
||||
|
||||
## Identity-Canon Implications
|
||||
|
||||
- **Subscriber** maps to **Organization** actor in **Customer Relationship**
|
||||
with vendor + **Tenant** Scope — not a canonical noun.
|
||||
- **Member** maps to **Account** + **Membership Relationship** to Organization.
|
||||
- **Vendor** maps to **Vendor Relationship** role on vendor Organization actor.
|
||||
- Supports S04, S05 without Customer Account concept.
|
||||
- Individual (B2C-style) subscriber maps to **Natural Person** + **Tenant**
|
||||
Scope, still without Customer Account.
|
||||
|
||||
## Terminology Conflicts
|
||||
|
||||
- **Customer vs. Subscriber vs. Organization**: three labels for overlapping B2B
|
||||
party; IAM prefers organization or subscriber.
|
||||
- **Customer vs. Consumer**: B2B2C uses both; subscriber org vs. end consumer.
|
||||
- **Tenant vs. Organization**: Stytch equates customer to organization; tenant
|
||||
is the isolation fabric they occupy.
|
||||
- **Account**: must not be used for subscriber org or billing party.
|
||||
|
||||
## Candidate Canonical Mappings
|
||||
|
||||
| B2B SaaS IAM concept | Candidate canonical concept |
|
||||
| --- | --- |
|
||||
| Subscriber | Organization + Customer Relationship role |
|
||||
| Organization (tenant holder) | Organization + Tenant Scope |
|
||||
| Member | Account + Membership Relationship |
|
||||
| Vendor (platform) | Organization + Vendor Relationship role |
|
||||
| Tenant | Tenant (Scope) |
|
||||
| User (login) | Account |
|
||||
| Consumer (B2B2C) | Natural Person or Account (context-dependent) |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None blocking Customer Account resolution. Commercial billing layer documented
|
||||
separately in `stripe-customer-billing.md`.
|
||||
|
||||
## References
|
||||
|
||||
- Auth0: Demystifying Multi-Tenancy in B2B SaaS — https://auth0.com/blog/demystifying-multi-tenancy-in-b2b-saas/
|
||||
- Auth0 Organizations — https://auth0.com/docs/manage-users/organizations
|
||||
- Stytch: Organization tenancy — https://stytch.com/blog/organization-tenancy/
|
||||
102
research/commercial-subscription/stripe-customer-billing.md
Normal file
102
research/commercial-subscription/stripe-customer-billing.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Stripe Customer and Subscription Billing
|
||||
|
||||
## Source Type
|
||||
|
||||
Product API documentation and SaaS architecture practice. Stripe Customer object
|
||||
and B2B subscription billing integration patterns.
|
||||
|
||||
## Domain
|
||||
|
||||
Commercial billing, payment methods, subscriptions, and tenant-to-billing linkage
|
||||
in multi-tenant SaaS.
|
||||
|
||||
## Why This Source Matters
|
||||
|
||||
Stripe's Customer object is the most widely deployed example of a **billing
|
||||
customer** that is explicitly not a login account. It demonstrates why
|
||||
"customer account" must be split into commercial records vs. identity records.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **Customer (Stripe)**: billing entity with email, name, payment methods,
|
||||
subscriptions, balance, and invoice settings.
|
||||
- **Subscription**: recurring billing agreement tied to a Customer.
|
||||
- **Payment method**: card or bank source attached to Customer for charges.
|
||||
- **Metadata**: key-value pairs linking Stripe Customer to app tenant ID.
|
||||
- **Delinquent**: billing health flag on Customer from invoice state.
|
||||
- **Business name / individual name**: Customer may represent company or person.
|
||||
- **customer_account (Stripe API)**: newer field referencing an Account object
|
||||
representing a customer — explicit split from legacy Customer.
|
||||
- **Webhook-driven sync**: Stripe owns payment state; app database owns business
|
||||
state; webhooks bridge them.
|
||||
- **Tenant mapping**: standard pattern stores `stripe_customer_id` on tenant record.
|
||||
|
||||
## Relevant Terminology
|
||||
|
||||
| Term | Source meaning |
|
||||
| --- | --- |
|
||||
| Customer | Stripe billing object; not authentication identity. |
|
||||
| Subscription | Recurring charge agreement. |
|
||||
| Invoice | Bill document; drives delinquent state. |
|
||||
| Payment method | Stored payment instrument. |
|
||||
| Balance | Credit or amount owed on Customer. |
|
||||
| Metadata | App-defined correlation (e.g., tenant_id). |
|
||||
| customer_account | Stripe Account representing customer (newer API). |
|
||||
| Tenant (app) | Application isolation unit linked via metadata. |
|
||||
|
||||
## Modeling Assumptions
|
||||
|
||||
- **Billing state lives in payment provider**; app caches plan/feature access.
|
||||
- **One Stripe Customer per tenant** is the common B2B pattern (not per login user).
|
||||
- **B2B Customer** often has `business_name`; B2C may use `individual_name`.
|
||||
- **Customer email** is billing contact, not necessarily login email.
|
||||
- **Commercial identity can exist without Organization** (sole proprietor, individual
|
||||
plan).
|
||||
- **CRM "Account"** (Salesforce-style) follows similar commercial-record pattern.
|
||||
|
||||
## Identity-Canon Implications
|
||||
|
||||
- Stripe **Customer** maps to **Commercial Record** in Record layer — not Account,
|
||||
not Customer Account, not Organization.
|
||||
- Link Commercial Record to **Tenant** Scope and/or **Organization** / **Natural
|
||||
Person** actor via **Commercial Relationship** or Identifier binding.
|
||||
- Stripe **customer_account** field reinforces separate commercial vs. identity
|
||||
account split at API level.
|
||||
- **Subscription state** is Lifecycle State on Commercial Record (downstream).
|
||||
- Supports S04 when billing is modeled alongside vendor/customer orgs.
|
||||
|
||||
## Terminology Conflicts
|
||||
|
||||
- **Customer (Stripe) vs. Customer (relationship role)**: same word, different
|
||||
layers — billing object vs. vendor/customer commercial role.
|
||||
- **Customer vs. Account**: Stripe uses "customer" and emerging "customer_account"
|
||||
deliberately separate from login accounts.
|
||||
- **Customer vs. Tenant**: integration stores stripe ID on tenant; not same entity.
|
||||
- **CRM Account vs. Account (login)**: Salesforce Account = commercial record.
|
||||
|
||||
## Candidate Canonical Mappings
|
||||
|
||||
| Stripe / billing concept | Candidate canonical concept |
|
||||
| --- | --- |
|
||||
| Customer object | Commercial Record |
|
||||
| Subscription | Commercial Record lifecycle / entitlement metadata |
|
||||
| Payment method | Credential (payment instrument) — downstream |
|
||||
| Metadata.tenant_id | Identifier binding to Tenant Scope |
|
||||
| business_name | Commercial Record attribute |
|
||||
| individual_name | Commercial Record attribute (person-backed) |
|
||||
| customer_account (API) | Commercial Record variant / provider projection |
|
||||
| Delinquent / balance | Lifecycle State on Commercial Record |
|
||||
| Webhook event | Evidence Source for billing state change |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should payment methods on Commercial Record map to Credential in canon, or
|
||||
remain strictly downstream PCI-scoped artifacts?
|
||||
- Does sole-proprietor billing (person-backed Commercial Record without
|
||||
Organization) need a distinct pattern in scenario tests?
|
||||
|
||||
## References
|
||||
|
||||
- Stripe Customer object — https://docs.stripe.com/api/customers/object
|
||||
- Stripe Billing — https://docs.stripe.com/billing
|
||||
- Stripe org customer sharing — https://docs.stripe.com/get-started/account/orgs/sharing/customers-payment-methods
|
||||
Reference in New Issue
Block a user