Skip to content

Spec: the supplier edition (supplier system mode)

Status: proposal. Nothing under "What the edition adds" is implemented. The supplier edition is a tenant running in the supplier system mode, extended so that a supplier or distributor can run its whole rebate operation on the platform: the rebates it pays to its customers and to buying groups, the rebates it collects from its own suppliers, daily transaction feeds in, and line-level results out. The launch customer is a national building-products distributor replacing a dedicated rebate system; the edition is specified generically so it can be sold to other suppliers. Written 3 Nov 2026 at Tom's request.

Who it is for

Persona What they need from the edition
Finance controller Accurate accruals by period, an audit trail per figure, statements and payment runs, reconciliation against what counterparties say
Commercial / buying team Agreements with tiers, pack groups, strung and growth terms; forecasts to the next tier; change history
MIS / data team A daily feed in, a daily feed out, idempotent and monitored, with no manual month-end re-keying
Branch and sales users Their own figures and earnings, without seeing margin or cost they are not entitled to
Counterparties (customers, suppliers, groups) Sign-off, statements, and a place to query a figure

Vocabulary

  • Counterparty — the other party on an agreement: a customer, a buying group, or an upstream supplier. Stored as a company, as today.
  • Direction — whether the tenant pays (out) or collects (in) on an agreement. New field on the deal; the calculation engine ignores it.
  • Member — the tenant's own trading divisions (for example drylining and roofing). Participation, throughput and results are per member, as on a group site. Branches remain a reporting dimension on every line and carry no financials, matching branches.
  • Stream — a turnover stream on a deal, used here as a pack group: one supplier's product group with its own rebateable and stock/direct flags. Products map to streams through a durable product mapping.
  • Line — a sales invoice line, purchase invoice line or goods-received line fed in daily. Lines drive turnover; turnover drives the engine.

What exists today

Verified behaviour the edition builds on; see the linked pages for detail.

  • Supplier mode is already a mode, but a thin one. Ten branches widen deal, turnover, rebate, rebate-calendar and news reads to records held on other tenants where the company's eBizID equals this site, and pin the supplier directory to this site. Payments, figures entry, dashboards and sign-off do not branch on it. A supplier logging into a supplier-mode site therefore sees the group agreements it is party to, read-only, and nothing else from those groups.
  • The calculation engine handles guaranteed, stepped (retrospective or marginal, optionally linear), individual-target and growth elements; percentage, per-unit and lump-sum outputs; strung, compound, catch-up, date and member restrictions; periods from monthly to five-yearly. See engine rules and types and banding.
  • Turnover is monthly per deal, stream and member, entered on the figures screen, by spreadsheet, or cached from ERP lines. The engine sums those rows; it never reads a line.
  • Results are monthly per element, member and period, with OTE estimates from projections, payment states (due, holding, paid), RFPs and remittances.
  • Lines already have a home. The Intact ERP pull and the ledger upload index purchase and sales lines per site, map them to streams by stream code, and cache an ERP total on the monthly figure for reconciliation.
  • Sign-off is a two-party envelope (counterparty signs, then the site's signer) with certificate PDF, reminders and expiry. See signing off a deal.
  • Visibility is deal ACL plus element permissions plus category security. See the permissions matrix.
  • Settings already carry systemMode (group / merchant / supplier) and labels.merchant / supplier / other for relabelling company types. See site settings.

What the edition adds

Each capability states what the user can do, what is reused, what is new, and how we know it is done.

1. Agreements in both directions

User can: create an agreement with any counterparty and mark it out (we pay) or in (we collect). Define streams as pack groups with rebateable and stock/direct flags. Use every existing element type and modifier. Clone, template and version as today.

Reused: deal model, content editor, streams, engine, revisions. New: direction on the deal, defaulting to out on a supplier-mode site; relabelled vocabulary (counterparty, division) via the existing labels setting plus two new labels; the deal browser and dashboard filter by direction. Done when: an out agreement with a stepped, strung pack-group element calculates to the same figures as the equivalent group-site deal, and shows on the payables dashboard rather than the receivables one.

2. Daily transaction feeds in

User can: connect a nightly feed of sales lines, purchase invoice lines and goods-received lines, plus master deltas (products, customers, suppliers, branches), by pushing batches to an API with a service account or by dropping files for the scheduler to collect. Watch each run on the scheduler's active-tasks panel, with counts, rejects and a daily completeness check that alerts when a feed is missing.

Reused: ledger import parsing and bulk indexing, task logging and progress frames, the Intact pull as the scheduler pattern. New: service-account tokens (today's bearer tokens are issued to people only); a grn line type alongside edi and sales; a shared line schema (external key, invoice and posting dates, branch, division, counterparty, product, quantity, net value, cost, stock/direct, source); idempotent upsert on the sender's key so a re-sent batch replaces rather than duplicates; retention by year. Done when: the same batch sent twice leaves one copy of each line, a back-dated line moves the month it belongs to, and a missing feed raises an alert before the next working day.

3. Pack groups: product to stream mapping

User can: load a supplier's product grouping (discount codes, category tree or SKU lists) as the mapping from product to stream; review products the system placed by rule with a confidence; correct a product and have the correction re-stamp its lines and re-aggregate the months affected.

Reused: the design in the stream-matching spec (mapping table, stub products, correction fan-out, PIM as the review surface). New: the loader for supplier-owned grouping tables; stream resolution by invoice date across deal renewals. Done when: every line in a period resolves to a stream or is listed as unplaced with a reason, and a correction changes the next calculation without an import.

4. Lines become turnover

User can: see monthly figures that were built from lines, open a figure to the lines behind it, and never have to key a month by hand. Manual entry is locked on line-derived figures; late lines re-open and re-aggregate the month they belong to and queue the agreement for recalculation.

Reused: turnover rows, the ERP-total refresh, the turnover dashboard drill-down, the invoiced-period lock. New: the nightly aggregation job writing value rather than only the cached external total, a createMethod of lines, and the late-line re-aggregation rule (posting date decides the batch, invoice date decides the month). Done when: a month's figure equals the sum of its lines to the penny, and a line posted 60 days late lands in its invoice month and triggers a recalculation of only that agreement.

5. Calculation and accrual policy

User can: rely on a nightly recalculation of every agreement whose turnover changed, see run history per agreement, and choose per element whether in-period accrual uses the estimated band (today's OTE) or a blended rate (expected earnings weighted across bands), because some counterparties' systems accrue below the headline tier rate.

Reused: engine, projections, OTE, targeting, calc check tasks. New: change-driven scheduling with a bounded worker pool and a run id; the blended-accrual option.

Done when: a 400-agreement estate recalculates inside the nightly window on the sizing environment, and the run log says which agreements ran and why.

6. Line-level results and the feed out

User can: open any calculated rebate line and see the earnings allocated to each transaction line behind it; pull or receive a daily export of line-level results in a stable shape (external key, agreement and element, period, value, units, accrued earnings, confirmed earnings, calculation type and rate, last updated) for stamping back onto their own ledger.

Reused: results rows, the rebate detail panel, the audit index. New: the allocation layer. After each live run, each result line is spread back to its source lines: for retrospective percentage elements the line earns rate × line value exactly; for marginal, lump-sum, per-unit and growth elements the period payable is shared pro rata by line value. Allocations are stored per run in their own table and mirrored as totals on the line document, and the export is incremental by last-updated. Done when: the sum of allocated line earnings equals the result line for every element and period, and a consumer can replay an export window without duplicates.

7. "Why did this figure change"

User can: compare any two calculation runs of an element and period and see the difference broken down into new lines, removed lines, lines that moved stream, rate or band changes, and agreement edits (linked to the revision that caused them), down to product level.

Reused: revisions, change log, allocation snapshots from capability 6. New: run snapshots and the diff view on the rebate detail panel. Done when: a product removed from a pack group shows as the sole cause of the drop in the next run's figure.

8. Payables: what we owe

User can: on out agreements, see accrued, approved and paid amounts per counterparty and period; approve a release (single or batch, with the approval tiers in capability 10); export credit notes or payment instructions to the finance system; send statements; record what was paid and reconcile a counterparty's self-bill against the accrual.

Reused: payment states, remittance PDF, campaign email delivery, QuickBooks link where present. New: the payables dashboard (the receivables dashboard mirrored for out agreements), release approval, finance export, customer statements, self-bill matching. RFPs are hidden on out agreements. Done when: a quarter's customer rebates can be accrued, approved, exported and marked paid without leaving the platform, and the statement a customer receives reconciles to the export.

9. Receivables: what we are owed

User can: on in agreements, run today's collect-side flow unchanged: due, holding, paid, RFPs, chasing, remittances. Upload a supplier's rebate statement, match it to agreement, element and period, see the variance per line, and accept or dispute it in a comment thread.

Reused: the whole receivables flow; the ledger upload wizard; the turnover query, flag and comment mechanics. New: statement upload and matching, the variance grid, dispute state on a result line. Done when: a supplier statement that disagrees by more than a configurable tolerance appears on a work list with the lines in question.

10. Internal approval tiers

User can: define approval rules by agreement value, category or direction (for example, any customer agreement above a threshold needs the finance director), with ordered approvers, delegation, reminders and a record on the agreement. The counterparty envelope opens only when the internal chain is complete.

Reused: the sign-off envelope (signer order is already enforced), workflow tasks with pool and claim, reminders. New: rule configuration, the internal chain as envelope signers ahead of the counterparty, approval history on the deal. Done when: an agreement above the threshold cannot be sent for counterparty signature until the required approvers have signed, and the certificate lists them.

11. Visibility levels

User can: give branch and sales users their own figures and earnings without cost or margin; give buyers agreements without finance screens; give finance everything. Rebate element permissions and category security continue to apply.

Reused: roles, element permissions with server-side redaction, category security. New: a default role set for supplier-mode sites and a cost-hidden view of sales lines. Done when: a branch user opening a sales line sees value and quantity but not cost, and the same request as a finance user shows both.

12. Group agreements, read-only

User can: see the agreements held with buying groups on other tenants where this company is the named supplier, with their figures and rebate lines, exactly as supplier mode shows them today.

Reused: the existing cross-tenant filters. New: nothing in v1. Those agreements are calculated by the group, not here; shadow-calculating what a group owes is out of scope.

Settings

Key Behaviour
systemMode = supplier Enables the edition. Existing value; no change to how it is stored
labels.* Reused for relabelling company types; two new keys for counterparty and division
direction.default out on supplier sites, in elsewhere; per-deal override
accrual.method band (default) or blended, overridable per element
feeds.* Expected feed types, expected daily arrival window, alert recipients
lines.retentionYears How many years of lines stay queryable; results summaries are kept longer

Non-functional requirements

  • Volumes: sized for 300,000 lines a month and 3 to 4 million a year per tenant; 400 agreements; 3,000 rebate elements. Lines live in the search index, one index per year, on the current search backend (version 9), not the legacy 1.4 backend. Monthly turnover and result rows stay small. Line allocations are the one new large table and are partitioned by period.
  • Timeliness: feeds in overnight, recalculation and allocation complete before the start of the next working day, export available by 06:00.
  • Idempotency: every inbound line and every outbound result carries the sender's key; re-sends replace, replays do not duplicate.
  • Isolation: one tenant per supplier with its own indices. Cross-tenant reads are limited to records naming this company, as the existing filters already do.
  • Audit: every figure traces to lines, every result to a run, every run to the agreement revision it used.
  • Operability: every job uses the scheduler with progress, bounded parallelism and a healthcheck panel; long jobs set their own timeout.

Out of scope for the first release

  • Shadow calculation of buying-group agreements held on other tenants.
  • Branch-level participation (branches as members). Revisit if an agreement carries branch-level tiers.
  • Supplier portals for counterparties beyond sign-off, statements and queries.
  • Margin-after-rebate analytics per product (covered by the stream-matching spec's PIM surface; sequence after the edition is live).

Phasing

  1. Both directions for the lead division (capabilities 1 to 12): the launch customer already runs supplier and customer rebates on the incumbent system and its contract covers both, so neither side can lag the cut-over. Parallel run against the incumbent using its own line-level output files as the comparison baseline.
  2. Further divisions onto the same tenant once the first month-end has closed cleanly; no second build of the feeds or the engine.
  3. Edition packaging: naming, pricing, which existing supplier logins on group sites migrate to a supplier-edition tenant, and the stream-matching spec's product surface.

Open questions

  • Blended accrual: required or not (see capability 5).
  • Whether any launch-customer agreement has branch-level tiers.
  • Customer payment mechanism: credit note, bank transfer, statement cadence, and who approves releases.
  • History: how many years of lines to migrate and whether the incumbent's line-level results are available as the parallel-run baseline.
  • Whether the supplier edition and merchant edition share the direction field, so a merchant can also pay customer rebates later.

Rough sizing

First-pass developer days, before contingency, from the launch-customer scoping: feeds and service accounts 13; product mapping 8; lines to turnover 6; scheduling 4; allocation and export 18; change attribution 6; payables and supplier-mode completion 18; supplier reconciliation 10; approval tiers 8; forecasting and visibility 7; migration and parallel-run tooling 15; hardening, test and documentation 20. About 133 days in all; roughly six months for one developer or three and a half for two.