# Commercial Account Changes pack

**Version 1.0.0 (beta) · Builder plan and above · requires the Stripe connector (or an attested billing evidence key) and the product-access interface**

For teams whose customer accounts span separate commercial, billing and product systems. An approved change to an
account (the first workflow is a change of seats) has to land in billing and in the product the customer uses.
This pack checks that it did, by the change's own deadline, whoever performed it: an agent, an automation or a
person. It keeps an incomplete change open with an owner until the systems show it corrected, and records the
correction beside the original outcome.

## What it does not do

CommitLayer never changes a subscription, never provisions access and never calls your application. It reads
billing on a restricted read-only Stripe key and receives product access from your backend. It does not tell you
why a change did not land, what it cost, or whether an amount is recoverable: it says which system showed what,
when, for which account.

## Workflow

| Workflow | Contract | Must be true at the deadline | Fails it afterwards |
|---|---|---|---|
| `change_account_seats` | `cac_change_account_seats` v1 | the account's Stripe subscription shows the approved quantity (and price, when the approval names one); the account in your application shows the approved number of seats (and plan, when named) | for 30 days, a record in either system that shows other values, unless a later approved change for the account took over |

Each system is read as a **state**: the latest eligible record at the deadline is the one that counts. An earlier
record of the old state is not a finding. A change that was made and undone before the deadline is. A record dated
after the deadline never makes a late change on time.

**A change is decided at its deadline, never before.** Until then it reads Scheduled or Pending, and what the
systems show so far is provisional. A change that is in place early still completes on time, at the deadline.

## The three inputs

| Input | From | How |
|---|---|---|
| The approved change (a **commitment**) | the approving side: your CRM, CPQ, approval workflow, or a person in the app | `POST /v1/commitments` with a key created with the `approver` preset. A key that may record actions is refused. |
| Billing | Stripe | the Stripe connector writes `stripe.subscription_configuration` (quantity, price, status). With **Events: read** on the restricted key each change is dated by Stripe's own event; without it, at the read that first saw it. See [the Stripe connector](/docs/connectors/stripe). |
| Product access | your application | `product_access.seat_allocation` through the [product-access interface](/docs/product-access), by an evidence key attested for `product_access`. Push only. |

Identity is exact, and it is CommitLayer's own. The commitment names the subscription (`account.billing_ref`) and
the account's id in your application (`account.product_ref`); its checks read those two subjects and nothing else.
Another account with the same plan, the same customer or the same numbers is never read for it, and no pushed,
imported or connector-made identity link can attach another record to a commitment: a link that names a commitment
is refused on every evidence route, whoever sends it.

## Setup

1. Connect Stripe with a restricted key: Subscriptions: read, Events: read. *(Admin.)*
2. Create an evidence key bound to `product_access` and attest it. Wire your application's backend to
   `POST /v1/product-access/seat-allocations`. *(Admin; a technical administrator for the wiring.)*
3. Install the pack and select its contract. *(Analyst.)*
4. Create an `approver` key for the system that approves changes, or create commitments in the app. *(Admin.)*

`GET /v1/commitments/readiness` shows which of these are in place, what each system can check and what is
missing.

## What a commitment reads as

| Status | When |
|---|---|
| Scheduled | not effective yet; never late |
| Pending | effective and not decided yet: the deadline is ahead (even if the change is already in place), or a system has not reported past it yet |
| Complete | both systems showed the approved values at the deadline |
| Incomplete | one did not; an exception is open, with an owner once assigned, and a resolution condition (`product_access account seats = 40`). Also a complete or corrected change that a system later showed undone |
| Corrected and verified | the systems showed the approved values later; the outcome at the deadline stays on the record (a missed deadline stays missed) and is frozen |
| Exception accepted | an Admin or Owner decided to live with it, with a reason; never counted as complete |
| Not verifiable | a system could not be checked (not supplied, or it stopped reporting); never counted as failed |
| Superseded | a later revision of the same approved change replaced it, or a later approved change for the same account took over before it was in place |

**Two changes open at once on one account.** When a later change for the same account is approved before an
earlier one's deadline, the earlier one is judged on what the systems showed when the later one was approved:
complete if it was in place by then; otherwise superseded by the later change (each links to the other), never a
missed deadline, and no exception asks for values that would undo the later change. A commitment that had already
missed its deadline stays a recorded miss, in the summary too, when it is superseded afterwards.

**After the deadline** both systems are watched for 30 days. A change after a complete outcome, after a cleared
exception or after a verified correction opens a new exception; the earlier one stays in the commitment's history.
Once an exception is corrected and verified, or accepted, the outcome at the deadline is frozen: a record that
arrives later and is dated inside the deadline is kept as an event and changes nothing.

The full shapes are in the [API reference](/docs/api#commitments).

## Try it first: the guided sample

A signed-in person can run the whole journey in their own workspace before anything is set up, on any plan: Account
A approved from 25 to 40 account seats, an automation's "completed" report, billing at 40, product access still at
25, the exception, an owner, a simulated correction, and "Corrected and verified" with the missed deadline kept. The
sample runs under this pack's own contract through the same code as a real commitment; only its evidence is the
sample's, kept to its run, so it can never satisfy a real commitment and nothing real can satisfy it. It is never
metered, summarised or announced. The routes are in the [API reference](/docs/api#account-change-sample).

## Scenarios

Nineteen scenarios over sixteen fixture cases, each run through the engine on every change: both systems right;
billing right and access wrong; reported complete and nothing changed; the change applied twice; another account
got the seats; the wrong number; the wrong price; undone before the deadline; undone after it; product access
behind at the deadline (pending); product access gone quiet (UNKNOWN, not FAIL); nothing supplying product access;
only the performing side saying so; the same change submitted twice; corrected after the deadline (the action
stays FAIL; the commitment reads corrected). `POST /v1/packs/commercial_account_changes/dry-run` runs them in your
workspace and persists nothing.

## Limits

- One subscription item per account change. A subscription with several items is read as the sum of their
  quantities with no price, so a change that names a price never passes on it by accident.
- Product access is reported by your application, never read by a connector. `effective_at` on its records is
  your application's own statement of when an allocation took effect.
- A change undone more than 30 days after its deadline is not seen.
- Without **Events: read** on the Stripe key a change is dated at the read that first saw it: a change made before
  its deadline and first read after it reads as late, and a change made and undone between two reads is not seen.
  `GET /v1/commitments/readiness` says when the key cannot read events. The subscriptions that open commitments
  name are read by id on every sync, whatever their age.
- An earlier change that was overtaken by a later one stays superseded even if a record that arrives afterwards
  shows it had been in place when the later one was approved.
- "Check again now" (`POST /v1/commitments/{ref}/verify`) checks against the latest records received and asks the
  billing connection for a fresh read; it cannot make your application report.
- Scheduled changes held inside Stripe (subscription schedules, pending updates) are not read ahead of time: the
  subscription is read as it is in effect.
- Activation, reduction with proration rules, suspension and termination are not workflows of this version.
