# Stripe pack: adjust an invoice

One of the five workflows of the [Stripe Customer Operations pack](/docs/packs/stripe-customer-operations), 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:

```json
{
  "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](/docs/packs/stripe-customer-operations/recorder-and-opentelemetry)). 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.

## Identity links it needs

| 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](/docs/packs/stripe-customer-operations/failures) 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` |
