B2B account-management service for the Equinox v9 commerce platform.
Overview
The Account Service is the system of record for B2B (business-to-business) accounts on the Equinox platform. In a B2B storefront, the customer is not a single consumer but an organization (a company) with many buyers, internal structure (teams, cost centres), spending controls (budgets, contracts, credit limits), and negotiated commercial terms (payment terms). This service models all of that and exposes the APIs the storefront, admin console, and order/checkout systems call to create accounts, manage their people, and validate that a given order is allowed (budget available, contract active, credit limit not exceeded).
Everything is multi-tenant: every business resource is scoped to an instanceId (a tenant). An InstanceContext pre-handler resolves the instance on each request, caches it, and blocks operations on INACTIVE instances.
Business Value
| Capability | Business outcome |
|---|---|
| Account hierarchy (parent/child) | Model corporate structures — parent company with subsidiary/branch accounts, with materialized hierarchy paths |
| Account users (buyers/sellers) + teams | Organize the people who transact on behalf of an account and group them into teams |
| Cost centres + budgets | Departmental spend controls; each budget tracks amount vs spent |
| Budget transactions (DEBIT/CREDIT) | Idempotent ledger that draws down / restores budget as orders are placed and cancelled |
| Contracts + credit limits | Negotiated purchasing agreements with validity windows and credit ceilings |
Order validation (/validate) |
Single call that gates checkout on active contract + active budget + budget headroom + credit limit |
| Payment methods & payment terms | Stored B2B payment instruments and net-terms (e.g. NET30) |
| Self-registration & admin invite | Public B2B sign-up (PENDING account) and admin-invited onboarding with email activation |
| Attributes | Tenant-defined custom fields attached to accounts and other entities |
| Per-tenant extensions | Pluggable validators (and an app/module lifecycle model) configured per instance |
Who Uses It
| Persona | How they interact |
|---|---|
| B2B buyer (storefront) | Registers a company, is invited to teams, places orders that hit /validate |
| Account administrator | Manages users/teams/cost-centres/budgets/contracts for their account; invites buyers |
| Platform/tenant admin | Manages instances, account types, attributes, and instance-level plugin config |
| Checkout / OMS systems | Call POST …/validate before accepting an order; post budget DEBIT/CREDIT transactions |
| Storefront UI | Reads the account dashboard, buyer lists, and hierarchy |
| Downstream services | Consume EventBridge events (accountservice/*) for projections/notifications |
Related Resources
README.md,QUICK_START.md,Account seller.md— repo-level guidesdocs/— story blueprints and registration-flow analysiscdk/— AWS CDK infrastructure (API Gateway + Lambda + EventBridge)- Swagger UI — live API reference at
{base}/documentation
Core Features
| # | Domain / Feature | Description |
|---|---|---|
| 1 | Instances | Per-tenant configuration container; holds instance properties + pluginConfig |
| 2 | Instance attributes | Attribute definitions surfaced at the instance level |
| 3 | Accounts | B2B company records with status lifecycle and parent/child hierarchy |
| 4 | Account registration | Public self-registration + admin-invite onboarding (orchestrates user + foundation services) |
| 5 | Account types | Categorization of accounts (e.g. distributor, reseller) |
| 6 | Account users | Links platform users to accounts as BUYER or SELLER, optionally on a team |
| 7 | Teams | Named groups of account users within an account |
| 8 | Addresses | Account addresses (billing/shipping/etc.) |
| 9 | Cost centres & budgets | Departmental spend units; budgets track amount vs spent over a period |
| 10 | Contracts & documents | Purchasing agreements with validity windows, credit limits, and attached documents |
| 11 | Payments & payment terms | Stored payment methods and net-terms definitions |
| 12 | Attributes | Tenant-defined custom fields |
| 13 | Account actions | Storefront-compatible flows: dashboard, buyer list, team invite/membership, order validation |
Revision History
2026-08-05 | AN – Page created and uploaded the contents