Skip to content
Browse the documentation
Workflow packs

Stripe pack: adjust an invoice

The adjust_invoice workflow: an open invoice reduced once by the approved amount and the customer told; every check, its parameters and what each failure looks like.

Last changed Markdown versionllms.txt

One of the five workflows of the Stripe Customer Operations pack, version 2.3.0. Contract scop_adjust_invoice, action type adjust_invoice, settlement window 1h, on the Builder plan and above. This page is generated from the pack's own files (the manifest, the contract, the recorder mapping and the fixture cases as the engine judges them), so it says what the installed pack does.

What the agent does

The agent corrects an invoice the customer has not paid yet. A finalized invoice cannot be edited, so the correction is a credit note against it that lowers what is due, and the customer is told.

In the pack's words: The open invoice reduced once by the approved amount (a credit note against it) and the customer told; not voided, not refunded, not reduced twice.

The subject

The Stripe invoice, by its own id (in_…).

The action record

What POST /v1/actions carries for this workflow, whether it comes from the recorder, an SDK or your own code. A required parameter is one a check reads: an action that would pass without it is UNKNOWN on the policy lens with param_missing:<name>. Amounts are in major units (40.0 for forty dollars).

Parameter Required What reads it
amount yes above 500 fails the policy lens; compared with stripe.credit_note.amount
currency no recorded with the action; no check reads it
invoice_id no recorded with the action; no check reads it
customer_reference no recorded with the action; no check reads it
reason no recorded with the action; no check reads it
support_case_id no recorded with the action; no check reads it

The action of the pack's happy-path fixture, as a request body:

{
  "action_id": "adjust:in_2",
  "contract_id": "scop_adjust_invoice",
  "subject_id": "in_2",
  "subject_kind": "invoice",
  "params": {
    "amount": 120,
    "currency": "usd",
    "invoice_id": "in_2",
    "customer_reference": "cus_1",
    "support_case_id": "zendesk_ticket_801",
    "reason": "duplicate_line_item"
  }
}

Tool calls the recorder maps to it

Tool key Subject read from Action id Note
stripe.invoices_adjust arguments.invoice adjust:{arguments.invoice}
stripe.invoices_void arguments.invoice adjust:{arguments.invoice}

The tool keys and argument names are this pack's convention, not a verified list of any vendor's MCP tools; rename them to what your server exposes (recorder setup). Calls that render the same action id are one action when they agree on every parameter both carry (the reason apart, which the rules list under describes), and the first record stands.

What CommitLayer reads, and from which system

Every check of the contract, in the engine's own description of it, with the reason code it reports when it goes against the action. within times are measured from the action's requested_at.

Before the action (policy lens)

Check Read from When it goes wrong Reason code
latest stripe.invoice_status before the action had status=open stripe The invoice was not open when it was adjusted; a paid invoice takes a credit note that credits the customer precondition_unmet:stripe.invoice_status

Limits on what was approved (policy lens)

Check Read from When it goes wrong Reason code
amount above 500 the action itself The adjustment exceeds the amount an agent may approve limit_exceeded:amount

Totals across actions (policy lens)

Check Read from When it goes wrong Reason code
sum of amount across stripe.credit_note over 24h per agent above 2500 stripe The agent's adjustments over 24 hours exceed the approved total aggregate_exceeded:stripe.credit_note.amount

What must be seen afterwards (outcome and policy lens)

Check Read from Trust needed When it goes wrong Reason code
stripe.credit_note observed within 1h of the action, from a source rated independent or better stripe independent No Stripe credit note reduces this invoice expected_effect_missing:stripe.credit_note, effect_below_trust:stripe.credit_note
messaging.customer_notified observed within 1h of the action, from a source rated shared or better messaging shared The customer was not told of the corrected invoice expected_effect_missing:messaging.customer_notified, effect_below_trust:messaging.customer_notified

What must not be seen (policy lens)

Check Read from When it goes wrong Reason code
more than 1 stripe.credit_note effect(s) observed within 1h stripe More than one credit note was issued against the invoice duplicate_effect:stripe.credit_note
stripe.credit_note amount differs from the action's amount (tolerance 0.01) stripe The credit note amount differs from the approved adjustment effect_attr_mismatch:stripe.credit_note.amount
stripe.invoice_voided observed within 1h of the action stripe The invoice was voided instead of adjusted effect_observed:stripe.invoice_voided
stripe.refund observed within 1h of the action stripe A cash refund was issued on an unpaid invoice effect_observed:stripe.refund

What undoes it later (outcome and policy lens)

Check Read from When it goes wrong Reason code
stripe.credit_note_voided observed within 30d of the action, undoing it stripe The credit note was voided reversed:stripe.credit_note_voided
zendesk.reopen observed within 14d of the action, undoing it zendesk The support case was reopened reversed:zendesk.reopen

What makes it unverifiable

When stripe has never reported in the workspace, both lenses are UNKNOWN with missing_fact_source: there is nothing to judge the action against.

What settles it

Pending while Stripe has not reported past the action's window; until then the view shows a provisional verdict, which reads FAIL for an effect not seen yet. It settles as FAIL once Stripe is current and no credit note reduces the invoice.

A verdict is pending until then, and the pending view shows the provisional verdict of the evidence so far. A credit note voided within 30 days re-verifies the action and fails it: the invoice asks for the full amount again.

Link From To Who makes it
invoice_to_customer stripe invoice stripe customer Made by the Stripe connector on every sync from the invoice's customer, so a cash refund on the customer is visible to a credit or an adjustment. Nothing to push.
ticket_to_invoice zendesk ticket stripe invoice The ticket names the invoice it is about (the Stripe id, in_…); push the link beside the ticket facts or with the action.

A link is pushed in the links field of POST /v1/facts with its link_type. The pack's coverage (GET /v1/packs/stripe_customer_operations/coverage) counts the links it has seen of each type.

Parameters and their defaults

Set in the install wizard, or in configuration on the pack's configure, dry-run and install routes as {"adjust_invoice": {"<key>": <value>}}. A value that makes a check weaker than the default (a higher limit, a longer window) is listed as a warning before anything is saved.

Key What it sets Default Type Places in the contract
approved_limit Largest adjustment an agent may make without a person 500 number: at least 1 1
daily_limit_per_agent Most an agent may adjust over 24 hours, all adjustments together 2500 number: at least 1 1
window How long Stripe has to show the credit note 1h duration 1
helpdesk_source The system of record for support cases (reversal only) zendesk source 1

What each failure looks like

The pack's 12 fixture cases for this workflow, with the verdict the engine returns for each under the default parameters (a case written for one combination of systems under that configuration): the outcome lens (did it happen), the policy lens (was it allowed and done as approved), the status, and the reason codes of both lenses. These are the cases the dry run replays in your workspace. What each code means and what to do about it is on the failure interpretation page.

Case What is staged Outcome Policy Status Reason codes
happy_path The open invoice was reduced by the approved amount; the customer was told PASS PASS settled effect_observed:stripe.credit_note, effect_observed:messaging.customer_notified
adjustment_missing The tool reported the adjustment; the invoice still asks for the full amount FAIL FAIL settled verified_condition_not_met, expected_effect_missing:stripe.credit_note
customer_not_told The invoice was corrected; nobody told the customer FAIL FAIL settled verified_condition_not_met, expected_effect_missing:messaging.customer_notified
duplicate_adjustment The retry reduced the invoice twice PASS FAIL settled effect_observed:stripe.credit_note, effect_observed:messaging.customer_notified, duplicate_effect:stripe.credit_note
wrong_amount The invoice was reduced by a different amount than approved PASS FAIL settled effect_observed:stripe.credit_note, effect_observed:messaging.customer_notified, effect_attr_mismatch:stripe.credit_note.amount
above_approved_limit The agent approved more than its limit PASS FAIL settled effect_observed:stripe.credit_note, effect_observed:messaging.customer_notified, limit_exceeded:amount, aggregate_exceeded:stripe.credit_note.amount
voided_instead_of_adjusted The agent voided the invoice outright PASS FAIL settled effect_observed:stripe.credit_note, effect_observed:messaging.customer_notified, effect_observed:stripe.invoice_voided
invoice_already_paid The invoice had been paid: a credit to the customer, not an adjustment, was the right action PASS FAIL settled effect_observed:stripe.credit_note, effect_observed:messaging.customer_notified, precondition_unmet:stripe.invoice_status
only_the_agent_says_so The credit note fact was pushed by the agent's own key, not read from Stripe FAIL FAIL settled verified_condition_not_met, effect_below_trust:stripe.credit_note
delayed_evidence Stripe has not reported past the action's window yet: nothing is asserted until it does FAIL FAIL pending verified_condition_not_met, expected_effect_missing:stripe.credit_note
source_unavailable No Stripe connection at all UNKNOWN UNKNOWN settled missing_fact_source
credit_note_voided_later Finance voided the credit note: the invoice asks for the full amount again PASS PASS settled effect_observed:stripe.credit_note, effect_observed:messaging.customer_notified
the same case after the later record arrives FAIL FAIL settled reversed:stripe.credit_note_voided