Stripe Customer Operations pack
Five workflows for customer-operations agents (refund an order, cancel a subscription, issue a credit note, adjust an invoice, resolve a case) verified against Stripe, Shopify and the help desk; installs as drafts, a person activates.
Last changed Markdown versionllms.txt
Version 2.3.0 (beta) · the refund workflow on every plan, the other four on Builder and above · reads Stripe by its connector, or by your backend's push on Developer
For teams whose agents do customer-operations work: refunds, subscription changes, billing corrections and support cases, through Stripe, Shopify and a help desk (Zendesk, Intercom, Salesforce or HubSpot), with the agent's own order and messaging systems around them.
The pack verifies that the agent completed the whole business outcome, not the step its tool reported: the
Stripe object exists once and matches what was approved, the order or case moved to the right state, the customer
was told, and nothing forbidden happened. Stripe and Shopify are read by their connectors; the help desk by its
connector or by a push from your own system (see the known limits for which checks each can satisfy today).
Nothing the agent says about its own work counts as evidence: a fact pushed by a key that can also record actions
is classed agent_self_report and never satisfies an effect that needs shared or independent evidence.
The pages of this pack
| Page | What it holds |
|---|---|
| Refund an order, cancel a subscription, issue a credit note, adjust an invoice, resolve a customer case | One page per workflow: what the agent does, the subject, the action record, every check with the system it is read from, what settles it, its parameters and defaults, and what each failure looks like |
| Connector requirements | Which connector, which read permissions, what is read, what to push instead |
| Recorder and OpenTelemetry setup | The MCP recorder's command line, the mapping and how to change it, the warning for unmapped tools, what OpenTelemetry does and does not do |
| REST, Python, TypeScript and MCP examples | The examples that ship in the pack, as tested |
| From a test-mode key to a first verdict | A walk with a Stripe sandbox, command by command |
| Reading a verdict and its reason codes | Every verdict and code the pack can return, what it means, what to do |
What it does not do
CommitLayer never issues a refund, cancels a subscription, writes to Stripe or holds a Stripe secret key. It reads Stripe with a restricted read-only key, records what the agent was approved to do, and compares. Installing the pack creates drafts and activates nothing.
Workflows
| Workflow | Subject | Approved parameters | Must be true afterwards | Fails the action |
|---|---|---|---|---|
refund_order |
the order | amount (required), currency, payment_reference, customer_reference, support_case_id |
one Stripe refund for the amount on the order's payment (independent), the order cancelled (independent), the case solved (shared), the customer told (shared) | a second refund, another amount, over the agent's limit or the order's 24-hour total, a shipment after the cancellation or within 30 days of the refund, a refund that later fails, an order or case reopened |
cancel_subscription |
the subscription (sub_…) |
subscription_id, cancel_at_period_end (required), support_case_id, reason |
the subscription active beforehand; Stripe shows it cancelled with the approved timing; the case solved; the customer told | cancelled immediately when the end of the period was approved (or the reverse), a refund issued with it, a case reopened within 14 days |
issue_credit_note |
the invoice (in_…) |
amount (required), currency, invoice_id, support_case_id, reason |
the invoice paid beforehand; one credit note for the amount; the case solved; the customer told | a second credit note, another amount, over the agent's limit or 24-hour total, a cash refund alongside, a credit note voided within 30 days, a case reopened |
adjust_invoice |
the invoice (in_…) |
amount (required), currency, invoice_id, reason |
the invoice open beforehand; one credit note reducing it by the amount; the customer told | a second reduction, another amount, over the limits, the invoice voided instead, a cash refund, a credit note voided within 30 days |
resolve_customer_case |
the ticket | support_case_id, resolution_kind (required) |
the case solved in the help desk within a day; the customer told | a resolution kind the agent may not apply, the case solved twice in the window (reopened and closed again), escalated after being marked solved, reopened within 14 days |
Money movements that resolve a case are their own actions: an agent that refunds and closes the ticket records a
refund_order and a resolve_customer_case, and each is verified under its own contract.
A parameter marked required is one a check reads (a limit, or a comparison with what Stripe shows) and the
contract lists under required_params. An action
recorded without it is not passed on the strength of the checks that could run: where it would have passed, the
policy lens is UNKNOWN with param_missing:<name>. A failure another check found stays a failure, and the outcome
lens is not affected. Amounts are in major units (40.0 for forty dollars), the unit the connector's facts use.
Why these subjects
The Stripe connector records refunds on the payment they refund (pi_…) and on the Stripe customer
(stripe_customer_…), credit notes on the invoice,
subscription state on the subscription and invoice state on the invoice, using the Stripe id itself for
subscriptions and invoices. An agent's tool call names those ids (cancel_subscription(subscription="sub_…")), so
the recorder passes them through and the action matches the evidence without any link. The refund workflow is the
one that needs links: the action is about an order, Stripe holds the refund and the help desk the case. The Stripe
connector also records each refund on the payment it refunds (pi_…, or the charge without a PaymentIntent), and
the connectors link that payment and the case to the order from what the systems themselves hold: the Stripe ids
named by the Shopify order's transactions, the order id in the charge's metadata (order_id by default), and the
help-desk field you name as holding the order id. Nothing is matched by amount, time or email, and the refund's own
metadata, which the agent writes, is never read for it. The keys are set under identity in the pack's
configuration; how the connectors link the order
has the settings and their defaults. An order is linked to its payment, never to the customer, so a refund of the
same customer's other order does not count for it; do not also push customer_to_order for an order the connectors
link.
The connector also links every subscription and invoice to its customer on each sync, which is how a cancellation or a credit "sees" a cash refund the approval did not cover.
UNKNOWN, settlement and reversal
A verdict stays pending while Stripe (or the order system) has not synced past the action's window, and a
missing effect becomes FAIL only once the source is current: the connector's watermark is the clock, never the
agent's claim. No Stripe connection at all is UNKNOWN (missing_fact_source), and so is the policy lens of an
action that left out a parameter a check reads (param_missing). Reversals re-verify a settled action after the
fact: a refund that fails at the bank, a credit note voided, an order or a case reopened. Stripe records a
scheduled cancellation at once (canceled_at with cancel_at_period_end: true), so an end-of-period cancellation
settles like an immediate one and the flag is compared with the approval. An effect counts only at or after the
action's requested_at, so an action is recorded before the tool runs, or with the time the tool started.
Install
- Connectors. Stripe is required (restricted key with read on refunds, credit notes, subscriptions, invoices,
customers and charges; a sandbox's
rk_test_key is accepted). Shopify and a help desk are optional; without them the wizard points the order and help-desk sources at your own systems, which push their state through the facts API. Connector requirements has the permissions per connector. - Contracts. Five action contracts are shown with every check they make. Install saves them as drafts in your workspace, pinned by version, and activates none.
- Parameters. Limits (
approved_limit, the 24-hour totals), windows, the order and help-desk sources, the status that means "solved", the subscription status an agent may cancel from. Each value is applied at one or more places in the contract, and a value that weakens a check (a raised limit, a longer window) is flagged before you continue. The defaults are on each workflow's page. - Dry run. Every fixture case (73 fixture cases across the five workflows) runs through the engine against
your configured contracts, in a savepoint, and nothing is written. Each case names the failure it stages and
the verdict and reason codes expected. The cases stage the pack's default sources (
shopify,zendesk): under a configuration that names another order or help-desk source, the cases of the workflows that read it come back UNKNOWN (missing_fact_source) and are marked as written for the default configuration. - Activate.
POST /v1/contracts/{id}/selectper contract, or the Activate button in the app. The route takes the analyst role. The recorder mapping with the versions pinned is served atGET /v1/packs/stripe_customer_operations/recorder-mapping.
Plans
The refund workflow (refund_order) is open to every plan; the other four need Builder or above. Installing on
Developer writes the refund workflow's draft and nothing else, its recorder mapping records only the refund tools,
and a later install or reconfiguration on Builder adds the other four. Developer has no connectors
(allowed_sources is the facts API, CSV files and OpenTelemetry), so on Developer the refund's records are pushed
through the facts API under the connectors' own source names (stripe, shopify, zendesk), as the guided
setup's evidence code shows. GET /v1/packs/stripe_customer_operations gives each workflow's minimum_plan, and
requirements.plan.workflows the ones the workspace's plan may install.
Evidence trust classes on the refund workflow (2.3.0)
Release 2.3.0 states, on each expected effect of refund_order, the least evidence trust class it accepts:
min_trust_class: backend_attested. A record a CommitLayer connector read (commitlayer_connector) meets it, and so
does a record your backend pushed through an evidence-only key that an Owner or Admin attested for that source
(backend_attested, docs/onboarding/refund/trust/attestation-flow.md). A record the agent's own key or runtime sent
(agent_reported) never does. Each effect keeps its min_trust, so a source nobody attested evaluates exactly as it
did under 2.2.0 during the deprecation window of the legacy rating. The window stays 1h. stripe and shopify
now list customer_backend among their accepted classes, which is what the Developer plan's refund path has done
since 2.2.0.
The refund workflow for the systems you have
Release 2.2.0 adds three switches to refund_order: order_checks, case_checks and notification_check, all
true by default. Set to false, each takes out the checks that read that system, and nothing else: every check left
is the pack's own, word for word, the refund in Stripe and its limits are never optional, and the source the order
check needs is no longer one the contract cannot decide without. The configure, dry-run and install routes answer
dropped_checks, one plain sentence per check taken out ("Without an order system, CommitLayer cannot confirm the
order was cancelled."). The guided setup sets the switches from the systems a person says the workspace has, and
its confirmation names each check left out. Eight fixture cases prove the four combinations: Stripe only; Stripe
and Shopify; Stripe and Zendesk; Stripe, Shopify and Zendesk each reach PASS on a correct refund and FAIL on a
double one (the refund page).
Upgrading from 2.1.0
Nothing changes for an installation that keeps the defaults: the switches are on, and the contracts are those of 2.1.0. The upgrade preview lists the three new parameters as added.
Upgrading from 1.1.0
This release is a major one by the pack rules, because the five contracts gain a check: each lists the parameter
its limit or comparison reads under required_params (amount, cancel_at_period_end, resolution_kind). An
installation of 1.1.0 keeps its drafts, its mapping and its verdicts until you upgrade it; nothing already
recorded is judged again by the new text. The upgrade preview (GET /v1/packs/stripe_customer_operations/upgrade)
shows the contracts as strengthened and, under mapping, what happens to the
recorder mapping. Three changes there alter how a call you already record is read:
stripe.refunds_createandstripe.credit_notes_createnow readamountin the minor unit. A tool that sent40for forty dollars under one of those keys was the only shape that passed on 1.1.0, and it is recorded as0.4after the upgrade. Send the minor unit as the Stripe API does, or removeunitsfrom the rule in your mapping.- The help-desk rules for the sources your contract does not read are no longer served, so a bare
update_ticketresolves to your own help desk's rule. - An action recorded without a required parameter is UNKNOWN on policy where 1.1.0 passed it.
A mapping you replaced yourself is kept as it is by the upgrade, and the preview says so (kept: true).
Recorder mapping
The tool keys the pack maps, and the contract each records under:
| Tool key | Contract | Subject | Action id |
|---|---|---|---|
stripe.refund, stripe.refunds_create, shopify.refund_order, shopify.cancel_order |
scop_refund_order |
the order id | refund:{order_id}: the cancel and the refund are one action |
stripe.subscriptions_cancel |
scop_cancel_subscription |
arguments.subscription |
cancel:{subscription} |
stripe.credit_notes_create |
scop_issue_credit_note |
arguments.invoice |
credit:{invoice} |
stripe.invoices_adjust, stripe.invoices_void |
scop_adjust_invoice |
arguments.invoice |
adjust:{invoice} |
zendesk.update_ticket, intercom.close_conversation, salesforce.update_case, hubspot.update_ticket |
scop_resolve_customer_case |
the help desk's subject | resolve:… |
The keys and argument names are this pack's convention, not a verified list of any vendor's MCP tool names. Recorder and OpenTelemetry setup says how to run the recorder and what to check first. In short:
- It is your workspace's mapping. Once the pack is installed the served mapping is the workspace's own copy.
PUT /v1/packs/stripe_customer_operations/recorder-mappingreplaces it with the annotated document (?annotated=trueon theGET) as you edited it: rename a key to your server's tool name, change a path, add a tool. The plainGETis the file for a recorder and holds the recorder's own keys only. Sent back, each rule keeps theunits,when_sourceanddescribesthe stored rule of the same tool name has; a tool you rename needs itsunitsstated again, so edit the annotated document when you rename. Storing needs a key with every scope. The stored copy is kept through an upgrade and a rollback, except that the help desk's rule followshelpdesk_sourcewhen you change it, and has no editor in the app yet. - Units.
stripe.refunds_createandstripe.credit_notes_createare declaredunits: {amount: minor}: the tool sends4000, the action records40.0. Every other key is read as sent, in major units. The conversion goes by the call's currency: divided by 100, and taken as sent for the currencies Stripe's currency page lists as zero-decimal (JPY and KRW among them), which is also how the connector now reads Stripe's amounts. A call that states no currency is read as hundredths andaction.unitssays so. Three-decimal currencies are read as hundredths on both sides, so a limit for one has to be written ten times smaller. - A repeat is the same action. A retried call, or a second mapped tool for the same order, renders the same
action id; the first record stands and nothing is added to it. The same id with another amount, customer,
payment, support case or subject, or a request time outside the first one's window, is a different action and
is refused (
409 conflict); only the reason may differ, because the rules list it underdescribes. A second call that states a parameter a check reads when the first did not is refused too: a cancellation recorded withoutrefund_amountstays UNKNOWN on policy, and the refund that follows with an amount is not merged into it. - One help desk. A workspace is served the rule of the help desk its contract reads, not the other three.
- Tools without a rule. The pack's coverage lists under
unmapped_consequential_toolsevery tool in the mapping'sconsequential_tools, and every tool reported throughPOST /v1/packs/stripe_customer_operations/observed-toolsand not read-only when first reported, that has no rule. A recorder key cannot clear the warning; a person lists the tool underread_only_toolsin the mapping. The recorder's--warn-unmappedlogs such calls locally; it does not report them to the API yet.
Evidence and trust
| Source | Read by | Trust required | Classes accepted |
|---|---|---|---|
stripe |
the Stripe connector | independent | native_connector |
shopify (or your order system) |
the Shopify connector, or your facts push rated independent by an admin |
independent | native_connector (a pushed order system is customer_backend) |
zendesk (or Intercom, Salesforce, HubSpot, your help desk) |
the help desk's connector, or your facts push with the same from and to attributes |
shared | native_connector, customer_backend |
messaging |
your messaging system's facts push | shared | customer_backend, provider_webhook |
Push facts with an evidence key (facts:write and read scopes, never actions:record). A key that holds actions:record produces
agent_self_report (agent_reported), which never counts whatever is attested for the source. A pushed record
counts only once an Owner or Admin attests its source for the evidence key that sent it (Refund setup's real-workflow evidence screen, or
Connections, "Evidence pipeline"); until then the effect reads effect_below_trust.
Fixtures and scenarios
The pack ships 73 fixture cases and 91 scenarios over them. Each workflow has PASS, FAIL, UNKNOWN, duplicate, delayed-evidence and reversal cases, plus the failures named in the brief: the refund that succeeded while the order stayed active and shipped; the ticket closed before the money moved; the cancellation Stripe applied immediately when the end of the period was approved; the credit note with a cash refund alongside; the invoice voided instead of adjusted; the case solved twice. A scenario labels a fixture case with one of the sixteen shared failure modes and carries the expectation the engine's verdict must meet; several scenarios can share a case, so some failure modes of a workflow are the same staged facts read under another label. A dry run that disagrees with an expectation is a bug in the pack, never a reason to edit the expectation.
Six scenarios state both lenses and every reason code, and a test pins each: the refund that succeeded with the order still active, the order cancelled with no refund, the duplicate refund, the refund to the wrong customer, the subscription cancelled with the wrong timing, and the ticket closed before the money moved. The verdict the engine returns for every case is on the workflow's page.
Known limits of this version
- The case-resolved check reads a help desk's
status_changeby itstoattribute, as the Zendesk, Intercom, Salesforce and HubSpot connectors record it (version 2.0.0 read astatusattribute no connector writes). Setcase_resolved_statusto the help desk's own word:closedfor Intercom, the pipeline stage for HubSpot. - Fulfilment is checked by the shipments Shopify records (
fulfillment_created): one in the window fails the policy lens, one within 30 days of the refund fails the action after the fact. A fulfilment still open but not yet created, or cancelled later, is not read. - The Shopify connector records no
order_reopened, so the reversal on a reopened order needs a pushed order system. - A refund that went to the wrong customer or the wrong order and an order with no refund at all return the same verdict and code
(
expected_effect_missing:stripe.refund): the pack does not report the refund that landed elsewhere. - A rule fires on every call of its tool. A general update tool (
zendesk.update_ticket,salesforce.update_case,hubspot.update_ticket) is recorded as a resolution whenever it is called. - The help-desk rules build the subject from a template, which the published recorders (0.1.1 on PyPI, 0.1.2 on npm) do not read; those calls are forwarded unrecorded until a release with subject templates is published.
- OpenTelemetry ingestion does not record a pack action; its facts are runtime context no check reads.
- Activation is not reserved to people: the select route accepts an API key that holds every scope. A key on
one side of the line, the recorder's key and the evidence key among them, is refused (
insufficient_scope), as it is on saving a contract and on installing, upgrading or rolling back a pack. - Coverage reports the pack's default sources, and the dry run stages them, whatever sources the configuration names.
- A subscription resumed after a scheduled cancellation is not visible to the connector; status changes on subscriptions and invoices created more than 35 days before the connection's watermark are missed until the connector reads Stripe's events list; a currency mismatch is caught through the amount comparison in the invoice's or order's currency, not as its own check.