Skip to content
Browse the documentation
Workflow packs

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Activate. POST /v1/contracts/{id}/select per contract, or the Activate button in the app. The route takes the analyst role. The recorder mapping with the versions pinned is served at GET /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_create and stripe.credit_notes_create now read amount in the minor unit. A tool that sent 40 for forty dollars under one of those keys was the only shape that passed on 1.1.0, and it is recorded as 0.4 after the upgrade. Send the minor unit as the Stripe API does, or remove units from 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_ticket resolves 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-mapping replaces it with the annotated document (?annotated=true on the GET) as you edited it: rename a key to your server's tool name, change a path, add a tool. The plain GET is the file for a recorder and holds the recorder's own keys only. Sent back, each rule keeps the units, when_source and describes the stored rule of the same tool name has; a tool you rename needs its units stated 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 follows helpdesk_source when you change it, and has no editor in the app yet.
  • Units. stripe.refunds_create and stripe.credit_notes_create are declared units: {amount: minor}: the tool sends 4000, the action records 40.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 and action.units says 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 under describes. A second call that states a parameter a check reads when the first did not is refused too: a cancellation recorded without refund_amount stays 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_tools every tool in the mapping's consequential_tools, and every tool reported through POST /v1/packs/stripe_customer_operations/observed-tools and not read-only when first reported, that has no rule. A recorder key cannot clear the warning; a person lists the tool under read_only_tools in the mapping. The recorder's --warn-unmapped logs 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_change by its to attribute, as the Zendesk, Intercom, Salesforce and HubSpot connectors record it (version 2.0.0 read a status attribute no connector writes). Set case_resolved_status to the help desk's own word: closed for 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.