What a contract is
A contract is the source of truth for a customer’s billing relationship in Zenskar. It holds a customer, a start date, an optional end date, and one or more line items — each representing a product the customer is being billed for. Every invoice the contract generates is derived from the contract and stays in sync with it; changing the contract reshapes affected invoices automatically rather than requiring manual reconciliation. This is a deliberate shift from Zenskar’s previous contract model, where the user acted as the orchestrator — setting up products, wiring entitlements, watching invoices, and reaching for credit notes whenever reality drifted from the contract. In the current model, the contract holds the full timeline of past, present, and future invoices. Change a price retroactively and the engine reshapes the affected invoice on its own, adds delta line items where needed, and keeps accounting entries in sync.Line items
Each product added to a contract becomes a line item. A single contract can carry multiple line items — for example, a flat monthly platform fee and a pay-per-use API charge on the same contract. Each line item carries its own pricing model, price versions, billing schedule, discounts, and commitments, so different products on the same contract can behave completely differently from one another.How products get added
There are two ways to add products to a contract:- Auto-populate — the system adds all default products and pricing configured for the customer’s business entity.
- Pick manually — the user chooses which products to add and sets the price for each.
Line item classification: point-in-time vs. period-of-time
Every line item carries one classification, and this single piece of information drives proration, entitlement deduction, accounting treatment, and revenue recognition for that line.| Point-in-time (PIT) | Period-of-time (POT) | |
|---|---|---|
| What’s being charged for | An event that happens at a specific moment | Access or capacity held across a window |
| When the charge accrues | At the moment the event is recorded | Continuously across the period |
| Examples | API call, document generated, SMS sent, payment processed | 50/workspace/month, $200/sandbox/quarter |
| Price | Set per event | Set per period |
| Revenue recognition | Recognized at the moment of occurrence | Recognized uniformly (straight-line) across the service period |
Why the contract holding the truth matters
Because every invoice stays wired to the contract, edits propagate downstream automatically:- Add, remove, or update line items without voiding the original deal.
- Adjust commitments mid-contract — raise or lower minimums, change evaluation mode, extend the commitment window.
- Effective-date control — amendments apply from a specific date forward, and the engine reshapes every affected invoice without manual credit notes or reconciliation.
Invoice corrections on already-approved invoices
Approved invoices can’t be edited directly, so when a retroactive change affects an already-approved period, the system records a correction instead:| Correction type | What it means | How it reaches the customer |
|---|---|---|
| Positive arrear | The customer was under-charged | A separate back-dated invoice for that period (default), or the amount is redated forward onto the next upcoming invoice |
| Negative amount (credit owed) | The customer was over-charged | Carried forward and spread across upcoming invoices (default), or issued as a standalone credit note against the original invoice (placeholder: confirm availability) |
Concurrency and auditability
If two people edit the same contract at the same time, the second save is rejected with a conflict error rather than silently overwriting the first person’s changes. Every change to a contract — who made it and when — is recorded in a full audit trail.What a contract does not yet support
Some contract-level capabilities aren’t available yet:- Quantities are configured at the line item level; contract-level quantity controls aren’t supported.
- Optional line items (turned on or off mid-contract, like premium support billed only when activated) aren’t supported.
- Timezone configuration for billing cycles isn’t supported; cycles currently default to the customer’s or org’s timezone.
- Discounts and minimum commitments work at the product (line item) level only — contract-level discounts and commitments aren’t available yet.
- Custom attributes and tags aren’t available on contracts yet.
- Contract-level settings such as billing address, shipping address, invoice template, and payment method aren’t available yet.
- Contract amendment history (a record of what changed on a contract over time) doesn’t exist yet.
- Lifecycle states such as trial periods, eternal/forever contracts, expiry, pause/suspend, and auto-renewal aren’t configurable yet.
- Billing a parent customer or a designated third-party payer for a child customer’s contract isn’t supported yet.
- (Placeholder: any additional concepts not yet documented.)