Commitment and agreement cards
/operations/commitments and /operations/agreements represent different layers. A commitment is a derived, read-only passport of what must be delivered; an agreement is a managed commercial arrangement with terms, parties, dates, and lifecycle transitions.
Agreement registry
At /operations/agreements, a staff user with access to the section sees the shared agreement registry; client is an additional filter, not the only list boundary. The status strip filters draft, review, awaiting_signature, active, suspended, expiring, expired, terminated, and superseded. The count covers the full result available for the selected filter, not only the rows loaded so far. Table/Cards changes the view of the same results, and selecting a row opens the agreement passport.
Each row shows direction (Client, Supplier, or Internal) beside the title. The term combines start and end dates; an agreement without an end date is shown as open-ended. Continue through the list until you reach the needed result; a partial page is not the complete registry.
Commitment passport
The passport also shows Created and Updated timestamps as audit metadata; the derived commitment remains read-only.
Open a commitment card from /operations/commitments, or a specific passport at /operations/commitments/:commitmentId, to review obligation type, promised quantity and unit, the effective date when supplied, fulfillment state, work stage, terms basis, and the source order. A current delivery due date may be absent from the passport: do not infer overdue status from missing fields or the Open bucket; verify the delivery date and deadline in the source order and agreement.
The commitment is derived from the order and is not edited on this card. Change quantity, due date, or terms at the source order after checking its permissions and history. Loading error, empty result, and missing source-order enrichment are different states; missing enrichment does not create a new order.
Agreement passport
An agreement card in /operations/agreements shows direction, status, effective dates, legal parties, the current terms version, line count, and whether a signed document is required. Legal-entity names must come from the linked context, never from technical identifiers.
The agreement passport’s prepayment block shows an account bound to this agreement, its specific terms revision, and settlement currency; it is not a client wallet. You cannot enter an amount: to fund it, select a confirmed client payment that is still unallocated and in the same currency. Opening and funding the account require the relevant permissions and may be subject to separation of duties: the person who registered a payment cannot confirm it again. Account/payment loading, an empty list, read failure, a revision conflict, and a pending operation are different states; do not read an empty or unavailable result as a zero balance. This block does not spend funds, create or release a reserve against an invoice line, or issue refunds; it only opens the agreement-bound account, lets you choose a payment, and shows its state. If payment binding succeeds before funding completes, the card keeps that payment selected and asks you to press Pay in again; do not choose another payment. pending_funding or a pending write means wait and reread the card, not a zero balance.
The card’s headline is Available: Available = paid in − held − spent; a non-zero Refunded value is shown separately. It also shows the current terms revision and settlement currency: a superseding revision starts a separate reserve lane, and the prior balance does not move across. “Spent” means linked to an issued invoice line, not that this block can spend it: no spending, reserve creation/release, or refund action is available here.
In awaiting_signature, the agreement waits for signing to be confirmed outside the portal: the portal records that decision but does not make it. There is therefore no separate Activate button here—check the external signing process and the linked document copy. The practical next step is to obtain the signed copy and choose Add in the documents section below; it will not appear automatically.
Below the terms is a separate linked-documents section with Add and View all actions. It may be empty while the signed copy is still pending; that is not an access error. Created and Updated provide additional audit context.
View all opens the document registry in this agreement's context: /documents?sourceType=agreement&sourceId=<agreementId>. The result should contain only this agreement's documents and show a clear localized title, context chip, and empty state; do not treat a technical ID or another agreement's file as a valid filter result.
Transitions require a matching status and the current card version so someone else’s change is not overwritten. Enter a required reason for every transition; it is saved in the agreement history.
You can create an agreement at /operations/agreements/new when you have write access. The form creates a draft; for an agreement in draft or review, open term editing at /operations/agreements/:agreementId/terms, which replaces the current terms. If the card changed or a conflict appears, reread the card and try again. The UI has no separate rollback to an older version; moving review back to draft is part of revising the terms.
After you choose the client and the first offering/price, the portal suggests a title such as “offering — client”. Until you edit it, the suggestion updates when the selection changes; after a manual edit, the portal preserves your text. An agreement title is required, so use a meaningful title instead of invented data; editing an existing agreement does not overwrite its title.
In the current prepayment selector, the payment date may appear as a raw ISO value YYYY-MM-DD instead of the active-locale format. This is a source blocker: do not treat it as localized date evidence, and do not promote a money-bearing frame without currency.expected/currency.observed and matching-build date review.
Allowed transitions
draft→review: Submit for review;review→awaiting_signature: Send for signature;activeorexpiring→suspended: Suspend;suspended→active: Resume;- any mutable state →
terminated: Terminate, an irreversible action.
Activation is not a button on this card: active arrives after legal signing or from an external e-document system. Expiry and replacement transitions are handled by the system, not by manual buttons.
If the card version changed or a transition was not accepted, reload the card and decide using the current information. Never repeat an old action blindly.
Documents and safety
Check the terms version, signed document, legal entity, customer, dates, and access before transitioning. Use fictional contracts, amounts, and parties in training examples; never expose banking data, customer data, or technical identifiers.
Related pages