Skip to content
Browse the documentation
Workflow packs

Stripe pack: issue a credit note

The issue_credit_note workflow: one credit note on a paid invoice for the approved amount, no cash refund alongside; 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_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:

{
  "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). 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.

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.

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 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