# Stripe pack: issue a credit note

One of the five workflows of the [Stripe Customer Operations pack](/docs/packs/stripe-customer-operations), version 2.3.0.
Contract `scop_issue_credit_note`, action type `issue_credit_note`, 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 credits a customer for a paid invoice by issuing a Stripe credit note for an approved amount, resolves the
support case and tells the customer. No cash is refunded under this workflow.

In the pack's words: One credit note on the paid invoice for the approved amount, the case resolved, the customer
told; no second credit note, no cash refund alongside.

## 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 100 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": "credit:in_1",
  "contract_id": "scop_issue_credit_note",
  "subject_id": "in_1",
  "subject_kind": "invoice",
  "params": {
    "amount": 30,
    "currency": "usd",
    "invoice_id": "in_1",
    "customer_reference": "cus_1",
    "support_case_id": "zendesk_ticket_701",
    "reason": "order_change"
  }
}
```

## Tool calls the recorder maps to it

| Tool key | Subject read from | Action id | Note |
|---|---|---|---|
| `stripe.credit_notes_create` | `arguments.invoice` | `credit:{arguments.invoice}` | amount sent in the minor unit, recorded in the major unit |

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=paid | `stripe` | The invoice was not paid when the credit was issued; an open invoice is adjusted instead | `precondition_unmet:stripe.invoice_status` |

### Limits on what was approved (policy lens)

| Check | Read from | When it goes wrong | Reason code |
|---|---|---|---|
| amount above 100 | the action itself | The credit 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 1000 | `stripe` | The agent's credits 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 exists for this invoice | `expected_effect_missing:stripe.credit_note`, `effect_below_trust:stripe.credit_note` |
| zendesk.status_change observed within 1h of the action where to=solved, from a source rated shared or better | `zendesk` | shared | The support case was not resolved | `expected_effect_missing:zendesk.status_change`, `effect_below_trust:zendesk.status_change` |
| messaging.customer_notified observed within 1h of the action, from a source rated shared or better | `messaging` | shared | No customer notification was recorded | `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 | `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 amount | `effect_attr_mismatch:stripe.credit_note.amount` |
| stripe.refund observed within 1h of the action | `stripe` | A cash refund was issued as well as the credit | `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` |

**How the case-resolved check reads a help desk.** It looks for a `status_change` whose `to` attribute is the resolved
status (`solved` by default; Intercom closes a conversation, so set `closed` for it), which is how the Zendesk,
Intercom, Salesforce and HubSpot connectors record a status change. A help desk you push from sends `status_change`
with the same `from` and `to` attributes. Version 2.0.0 read a `status` attribute that no connector writes, so a case
solved in a connected help desk read `expected_effect_missing:<help desk>.status_change`. See [connector
requirements](/docs/packs/stripe-customer-operations/connectors).

### 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 the credit note is missing,
duplicated or for another amount.

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, or a case reopened within 14 days, re-verifies the action and fails it.

## 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
`{"issue_credit_note": {"<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 credit an agent may issue without a person | `100` | number: at least 1 | 1 |
| `daily_limit_per_agent` | Most an agent may credit over 24 hours, all credit notes together | `1000` | number: at least 1 | 1 |
| `window` | How long Stripe and the help desk have to show the effects | `1h` | duration | 1 |
| `helpdesk_source` | The system of record for support cases | `zendesk` | source | 2 |
| `case_resolved_status` | The helpdesk status that means the case is resolved | `solved` | string | 1 |

## What each failure looks like

The pack's 13 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` | One credit note on the paid invoice for the approved amount; case solved; customer told | PASS | PASS | settled | `effect_observed:stripe.credit_note`, `effect_observed:zendesk.status_change`, `effect_observed:messaging.customer_notified` |
| `no_credit_note_in_stripe` | The tool reported success; Stripe holds no credit note | FAIL | FAIL | settled | `verified_condition_not_met`, `expected_effect_missing:stripe.credit_note` |
| `duplicate_credit_note` | The retry credited the customer twice | PASS | FAIL | settled | `effect_observed:stripe.credit_note`, `effect_observed:zendesk.status_change`, `effect_observed:messaging.customer_notified`, `duplicate_effect:stripe.credit_note` |
| `wrong_amount` | Stripe shows a credit for a different amount than approved | PASS | FAIL | settled | `effect_observed:stripe.credit_note`, `effect_observed:zendesk.status_change`, `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:zendesk.status_change`, `effect_observed:messaging.customer_notified`, `limit_exceeded:amount` |
| `cash_refund_as_well` | The customer got the credit and a cash refund | PASS | FAIL | settled | `effect_observed:stripe.credit_note`, `effect_observed:zendesk.status_change`, `effect_observed:messaging.customer_notified`, `effect_observed:stripe.refund` |
| `invoice_was_not_paid` | The invoice was still open: an adjustment, not a credit, was the right action | PASS | FAIL | settled | `effect_observed:stripe.credit_note`, `effect_observed:zendesk.status_change`, `effect_observed:messaging.customer_notified`, `precondition_unmet:stripe.invoice_status` |
| `wrong_invoice` | The credit note landed on another invoice of the same customer | FAIL | FAIL | settled | `verified_condition_not_met`, `expected_effect_missing:stripe.credit_note` |
| `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 four days later | PASS | PASS | settled | `effect_observed:stripe.credit_note`, `effect_observed:zendesk.status_change`, `effect_observed:messaging.customer_notified` |
|  | the same case after the later record arrives | FAIL | FAIL | settled | `reversed:stripe.credit_note_voided` |
| `case_reopened` | The customer came back: the case was reopened | PASS | PASS | settled | `effect_observed:stripe.credit_note`, `effect_observed:zendesk.status_change`, `effect_observed:messaging.customer_notified` |
|  | the same case after the later record arrives | FAIL | FAIL | settled | `reversed:zendesk.reopen` |
