Skip to content
Browse the documentation
Workflow packs

Commercial Account Changes pack

An approved change of account seats verified in billing (Stripe) and in the product the customer uses, by the change's own deadline; an incomplete change stays open with an owner until the systems show it corrected.

Last changed Markdown versionllms.txt

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.
Product access your application product_access.seat_allocation through the product-access interface, 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.

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.

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.