Merchant customer (B2B)

The merchant customer module is the B2B layer on top of regular customer records. Where a normal customer is a single buyer with a card, a merchant customer is a business account: multiple users buying on behalf of an organisation, with a spending limit, payment terms (NET-30), an invoice cycle, and an outstanding balance. Use it for wholesale, distributor, or trade-account flows.

Account CRUD

{
  "businessName": "Acme Distribution Co.",
  "contactCustomerId": "cust-acme-primary",
  "spendingLimit": 50000,
  "currency": "USD",
  "paymentTerms": "NET-30",
  "billingCycle": "monthly",
  "creditLimit": 100000,
  "status": "pending"
}

by-customer returns the merchant account a given customer is attached to — a customer can belong to one merchant.

Lifecycle actions

The lifecycle is pending → approved → active → (suspended | closed). A suspended account can still log in but cannot place new orders. A closed account is read-only for historical reporting.

Limits and terms

Spending limits are enforced at checkout — if a new order would push the account over spendingLimit, the order is rejected with a 402-style response. Limit changes write an audit activity (see Activities and audit).

Users on the account

Add a customer to the merchant account, change their role (purchaser, approver, viewer), or remove them. When a user logs in and is attached to a merchant, their orders inherit the merchant's payment terms automatically.

Charges and credits

Manually post a charge or credit against the account balance. Used for fees, adjustments, returns processed outside the normal order flow.

Invoicing

generate rolls up unbilled orders into an invoice for the configured billing cycle. generate-all runs across every merchant — typically scheduled for the first of the month. Once generated, send emails the PDF and posts the invoice ID to the storefront invoice module so the customer can pay it online.

Reminders and statements

Statements are running summaries of invoices, payments, and balance over a date range. Reminders are dunning emails on overdue invoices.

Reporting

The aging report bucket-counts outstanding invoices (current, 1-30 days, 31-60, 61-90, 90+) — the standard A/R aging view.