Skip to content
Browse the documentation
Workflow packs

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.

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.

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