# Stripe Customer Operations pack

**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](/docs/packs/stripe-customer-operations/refund-order), [cancel a subscription](/docs/packs/stripe-customer-operations/cancel-subscription), [issue a credit note](/docs/packs/stripe-customer-operations/issue-credit-note), [adjust an invoice](/docs/packs/stripe-customer-operations/adjust-invoice), [resolve a customer case](/docs/packs/stripe-customer-operations/resolve-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](/docs/packs/stripe-customer-operations/connectors) | Which connector, which read permissions, what is read, what to push instead |
| [Recorder and OpenTelemetry setup](/docs/packs/stripe-customer-operations/recorder-and-opentelemetry) | 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](/docs/packs/stripe-customer-operations/examples) | The examples that ship in the pack, as tested |
| [From a test-mode key to a first verdict](/docs/packs/stripe-customer-operations/test-mode) | A walk with a Stripe sandbox, command by command |
| [Reading a verdict and its reason codes](/docs/packs/stripe-customer-operations/failures) | 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`](/docs/packs/stripe-customer-operations/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`](/docs/packs/stripe-customer-operations/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`](/docs/packs/stripe-customer-operations/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`](/docs/packs/stripe-customer-operations/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`](/docs/packs/stripe-customer-operations/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](/docs/packs/stripe-customer-operations/refund-order#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](/docs/packs/stripe-customer-operations/connectors) 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](/docs/packs/stripe-customer-operations/refund-order)).

## 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](/docs/packs/stripe-customer-operations/recorder-and-opentelemetry) 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.
