Stripe pack: refund an order
The refund_order workflow: one Stripe refund for the approved amount, the order cancelled, the case resolved, 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_refund_order, action type refund_order, settlement window 1h, on every plan. 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 refunds an order through Stripe and is expected to finish the job: cancel the order in the order system, resolve the support case and tell the customer. The refund, the cancellation and the case are one action about one order, whichever tool the agent called first.
In the pack's words: One Stripe refund for the approved amount on the order's payment, the order cancelled, the case resolved, the customer told; no duplicate, no over-refund, no shipment after the refund.
The subject
The order, by the id your order system gives it (the numeric order id for the Shopify connector). The Stripe connector records the refund on the payment it refunds, and the connectors link that payment and the support case to the order from what Stripe, Shopify and the help desk hold (how).
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 250 fails the policy lens; compared with stripe.refund.amount |
currency |
no | recorded with the action; no check reads it |
payment_reference |
no | recorded with the action; no check reads it |
customer_reference |
no | recorded with the action; no check reads it |
refund_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": "refund:ord_1001",
"contract_id": "scop_refund_order",
"subject_id": "ord_1001",
"subject_kind": "order",
"params": {
"amount": 40,
"currency": "usd",
"payment_reference": "pi_1",
"customer_reference": "cus_1",
"support_case_id": "zendesk_ticket_501",
"refund_reason": "damaged"
}
}
Tool calls the recorder maps to it
| Tool key | Subject read from | Action id | Note |
|---|---|---|---|
stripe.refund |
arguments.order_id |
refund:{arguments.order_id} |
|
stripe.refunds_create |
arguments.metadata.order_id |
refund:{arguments.metadata.order_id} |
amount sent in the minor unit, recorded in the major unit |
shopify.refund_order |
arguments.order_id |
refund:{arguments.order_id} |
|
shopify.cancel_order |
arguments.order_id |
refund:{arguments.order_id} |
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.
stripe.refunds_create reads the order id from arguments.metadata.order_id and the other three keys from
arguments.order_id. A call that does not carry the order id is forwarded and not recorded. Whether a given vendor's
refund tool accepts either argument is not verified here.
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.
Limits on what was approved (policy lens)
| Check | Read from | When it goes wrong | Reason code |
|---|---|---|---|
| amount above 250 | the action itself | The refund 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.refund over 24h per subject above 250 | stripe |
Refunds on this order over 24 hours exceed the approved amount | aggregate_exceeded:stripe.refund.amount |
What must be seen afterwards (outcome and policy lens)
| Check | Read from | Trust needed | When it goes wrong | Reason code |
|---|---|---|---|---|
| stripe.refund observed within 1h of the action, from a source rated independent or better, from backend attested evidence or stronger | stripe |
independent | No Stripe refund exists on this order's payment | expected_effect_missing:stripe.refund, effect_below_trust:stripe.refund |
| shopify.order_cancelled observed within 1h of the action, from a source rated independent or better, from backend attested evidence or stronger | shopify |
independent | The order was not cancelled after the refund | expected_effect_missing:shopify.order_cancelled, effect_below_trust:shopify.order_cancelled |
| zendesk.status_change observed within 1h of the action where to=solved, from a source rated shared or better, from backend attested evidence or stronger | 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, from backend attested evidence or stronger | 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.refund effect(s) observed within 1h | stripe |
More than one refund was issued | duplicate_effect:stripe.refund |
| stripe.refund amount differs from the action's amount (tolerance 0.01) | stripe |
The refund amount differs from the approved amount | effect_attr_mismatch:stripe.refund.amount |
| shopify.fulfillment_created observed within 1h of the action | shopify |
A shipment was created after the order was cancelled | effect_observed:shopify.fulfillment_created |
What undoes it later (outcome and policy lens)
| Check | Read from | When it goes wrong | Reason code |
|---|---|---|---|
| stripe.refund_failed observed within 30d of the action, undoing it | stripe |
The refund failed or was reversed | reversed:stripe.refund_failed |
| shopify.order_reopened observed within 30d of the action, undoing it | shopify |
The order was reopened | reversed:shopify.order_reopened |
| zendesk.reopen observed within 30d of the action, undoing it | zendesk |
The support case was reopened | reversed:zendesk.reopen |
| shopify.fulfillment_created observed within 30d of the action, undoing it | shopify |
A shipment was created after the refund | reversed:shopify.fulfillment_created |
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 or shopify 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 or the order system 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 only once those sources are current. The helpdesk and messaging effects are checked on their own sources' watermarks.
A verdict is pending until then, and the pending view shows the provisional verdict of the evidence so far. A refund
that fails or is reversed, an order that is reopened, a case that is reopened or a shipment created within 30 days
re-verifies the action and fails it.
Identity links it needs
| Link | From | To | Who makes it |
|---|---|---|---|
payment_to_order |
stripe payment | shopify order | The Stripe refund is recorded on the payment it refunds (pi_…). The connectors make the link from the systems' own records, so there is nothing to push; the Stripe connector from the order id in the charge's metadata, the Shopify connector from the payments the order's transactions name. Do not push a link from the Stripe customer to the order instead; the order would then see every refund of that customer. |
ticket_to_order |
zendesk ticket | shopify order | Made by the Zendesk or Intercom connector once the help desk's order field is configured (the pack configuration's identity); a help desk you push from sends the link beside the ticket facts. |
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.
How the connectors link the order
An action is judged on the facts of its own subject and of the subjects linked to it. The refund action names the order; each connector links the record it reads to the order from what that system holds, on every sync, whichever syncs first. Nothing is matched by amount, time, email or a model, and a record that names no order is linked to none.
| Connector | Records the refund or case on | Links it makes | Setting and default |
|---|---|---|---|
| Stripe | the refund, on the payment it refunds (pi_…, or the charge without a PaymentIntent) |
charge_to_payment: the charge and its PaymentIntent. payment_to_order: the payment and the order named in the charge's metadata under stripe.order_metadata_key |
stripe.order_metadata_key: order_id; null reads no metadata |
| Shopify | the order | payment_to_order: the order and every Stripe payment its successful transactions name (the authorization code; id, payment_intent, charge, latest_charge in the gateway's receipt), a charge followed to its PaymentIntent |
shopify.payment_references: true |
| Zendesk | the ticket | ticket_to_order: the ticket and the order its configured field holds |
zendesk.order_field: null (off); "external_id" or "custom_field:<field id>" |
| Intercom | the conversation | ticket_to_order: the conversation and the order in its configured custom attribute |
intercom.order_attribute: null (off); the attribute's name |
The refund's own metadata is never read for this: the agent that issues the refund writes it, so an agent that
refunded the wrong payment could otherwise name the order it meant. The charge's metadata is what the shop wrote when
it took the payment. The refund is also kept on the Stripe customer, where the subscription and invoice workflows read
it; an order is linked to its payment, never to the customer, so a refund of the customer's other orders does not
count for this one. Do not push customer_to_order for an order the connectors link: the order would then see every
refund of that customer, and its own twice.
The settings are part of the pack's configuration, under identity, beside the workflows' parameters: {"identity": {"zendesk": {"order_field": "custom_field:360011112222"}}} on the configure, dry-run, install and upgrade routes.
Anything else is refused with invalid_identity. The connectors use the installed configuration from their next sync;
the pack's coverage reports the settings in force and how many links of each kind the connectors have made
(identity). The value the metadata key or the help-desk field holds must be the order id the action names (the
numeric Shopify id): the connectors do not translate an order name such as #1001.
Without an order system, a help desk or a notification system
A check on a system the workspace does not have could only ever read as missing, so the configuration takes it out, and nothing else: every check left is the pack's own, unchanged, and the refund in Stripe is never optional. The guided setup asks which system plays each role and sets these for you, and its confirmation names every check left out. Each of them, set to false, takes out:
order_checks: false: Without an order system, CommitLayer cannot confirm the order was cancelled. Without an order system, CommitLayer cannot see a shipment created after the order was cancelled. Without an order system, CommitLayer cannot see the order reopened later. Without an order system, CommitLayer cannot see a shipment created in the 30 days after the refund.case_checks: false: Without a support system, CommitLayer cannot confirm the support case was resolved. Without a support system, CommitLayer cannot see the support case reopened later.notification_check: false: Without a notification system, CommitLayer cannot confirm the customer was told.
The fixture cases below whose names start with stripe_ run under the configuration of one combination of systems
(Stripe only; Stripe and Shopify; Stripe and Zendesk; Stripe, Shopify and Zendesk): each reaches PASS on a correct
refund and FAIL on a double one.
Parameters and their defaults
Set in the install wizard, or in configuration on the pack's configure, dry-run and install routes as
{"refund_order": {"<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 refund an agent may issue without a person | 250 |
number: at least 1 | 1 |
daily_limit_per_order |
Most an order may be refunded over 24 hours, all refunds together | 250 |
number: at least 1 | 1 |
window |
How long the downstream systems have to show the effects | 1h |
duration | 1 |
order_source |
The system of record for orders | shopify |
source | 5 |
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 |
order_checks |
Check the order in the order system (cancelled, not shipped, not reopened) | true |
boolean | 5 |
case_checks |
Check the support case in the help desk (resolved, not reopened) | true |
boolean | 2 |
notification_check |
Check that the customer was told (a notification your system pushes) | true |
boolean | 1 |
What each failure looks like
The pack's 25 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 |
Refund issued once on the order's payment for the approved amount; order cancelled, case solved, customer told | PASS | PASS | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, effect_observed:messaging.customer_notified |
claimed_only |
The agent says it refunded the order; Stripe, Shopify, the help desk and the messaging system show nothing | FAIL | FAIL | settled | verified_condition_not_met, expected_effect_missing:stripe.refund, expected_effect_missing:shopify.order_cancelled, expected_effect_missing:zendesk.status_change, expected_effect_missing:messaging.customer_notified |
refund_without_cancellation |
Refund succeeds; the order stays active and ships | FAIL | FAIL | settled | verified_condition_not_met, expected_effect_missing:shopify.order_cancelled |
cancellation_without_refund |
Order cancelled; the money never went back | FAIL | FAIL | settled | verified_condition_not_met, expected_effect_missing:stripe.refund |
duplicate_refund |
The retry refunded the customer twice | PASS | FAIL | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, effect_observed:messaging.customer_notified, duplicate_effect:stripe.refund |
wrong_amount |
Stripe refunded a different amount than approved | PASS | FAIL | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, effect_observed:messaging.customer_notified, aggregate_exceeded:stripe.refund.amount, effect_attr_mismatch:stripe.refund.amount |
above_approved_limit |
The agent approved more than its limit | PASS | FAIL | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, effect_observed:messaging.customer_notified, limit_exceeded:amount, aggregate_exceeded:stripe.refund.amount |
wrong_customer |
The refund went to another customer's payment, which is not this order's | FAIL | FAIL | settled | verified_condition_not_met, expected_effect_missing:stripe.refund |
wrong_order |
The customer's other order was refunded: the refund is on the payment of order ord_1002 | FAIL | FAIL | settled | verified_condition_not_met, expected_effect_missing:stripe.refund |
shipment_after_cancellation |
Cancelled, refunded, and the warehouse still shipped it | FAIL | FAIL | settled | reversed:shopify.fulfillment_created, effect_observed:shopify.fulfillment_created |
shipment_days_later |
Refunded and cancelled; the warehouse shipped the order two days later | PASS | PASS | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, effect_observed:messaging.customer_notified |
| the same case after the later record arrives | FAIL | FAIL | settled | reversed:shopify.fulfillment_created |
|
ticket_closed_before_the_money_moved |
The agent closed the case and told the customer; Stripe shows nothing | FAIL | FAIL | settled | verified_condition_not_met, expected_effect_missing:stripe.refund, expected_effect_missing:shopify.order_cancelled |
tool_said_success_but_only_the_agent_says_so |
The refund fact was pushed by the agent's own key, not read from Stripe | FAIL | FAIL | settled | verified_condition_not_met, effect_below_trust:stripe.refund |
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.refund |
source_unavailable |
No Stripe connection at all | UNKNOWN | UNKNOWN | settled | missing_fact_source |
later_reversal |
The refund failed at the bank three days later | PASS | PASS | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, effect_observed:messaging.customer_notified |
| the same case after the later record arrives | FAIL | FAIL | settled | reversed:stripe.refund_failed |
|
case_reopened |
The customer came back: the case was reopened | PASS | PASS | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, effect_observed:messaging.customer_notified |
| the same case after the later record arrives | FAIL | FAIL | settled | reversed:zendesk.reopen |
|
stripe_only_pass |
Stripe only: no order system, no help desk, no notification system. The refund is issued once for the approved amount, and every check kept reads its system | PASS | PASS | settled | effect_observed:stripe.refund |
stripe_only_double_refund |
Stripe only: no order system, no help desk, no notification system. The retry refunded the customer twice | PASS | FAIL | settled | effect_observed:stripe.refund, duplicate_effect:stripe.refund |
stripe_shopify_pass |
Stripe and Shopify: no help desk, no notification system. The refund is issued once for the approved amount, and every check kept reads its system | PASS | PASS | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled |
stripe_shopify_double_refund |
Stripe and Shopify: no help desk, no notification system. The retry refunded the customer twice | PASS | FAIL | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, duplicate_effect:stripe.refund |
stripe_zendesk_pass |
Stripe and Zendesk: no order system, no notification system. The refund is issued once for the approved amount, and every check kept reads its system | PASS | PASS | settled | effect_observed:stripe.refund, effect_observed:zendesk.status_change |
stripe_zendesk_double_refund |
Stripe and Zendesk: no order system, no notification system. The retry refunded the customer twice | PASS | FAIL | settled | effect_observed:stripe.refund, effect_observed:zendesk.status_change, duplicate_effect:stripe.refund |
stripe_shopify_zendesk_pass |
Stripe, Shopify and Zendesk: no notification system. The refund is issued once for the approved amount, and every check kept reads its system | PASS | PASS | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change |
stripe_shopify_zendesk_double_refund |
Stripe, Shopify and Zendesk: no notification system. The retry refunded the customer twice | PASS | FAIL | settled | effect_observed:stripe.refund, effect_observed:shopify.order_cancelled, effect_observed:zendesk.status_change, duplicate_effect:stripe.refund |