Stripe pack: from a test-mode key to a first verdict
From a Stripe sandbox's restricted key to a first verdict, command by command: connect, install, activate, act, push one fact, read PASS, then break it once.
Last changed Markdown versionllms.txt
A walk through the Stripe Customer Operations pack with a Stripe sandbox and
nothing else: connect Stripe with a restricted test key, install the pack, let an "agent" (you, with curl) adjust
an invoice, and read the verdict. It uses the adjust_invoice workflow because that one needs only Stripe and one
pushed fact; the other four also read an order system or a help desk
(connector requirements).
You need a CommitLayer workspace on the Builder plan or above in which you are an admin, and a Stripe sandbox. Nothing here moves money: a Stripe sandbox processes no payments, and CommitLayer only reads.
1. In Stripe: a restricted key for CommitLayer
In the sandbox, create a restricted API key with read on Refunds, Credit notes, Subscriptions, Invoices,
Customers and Charges, and no other permission. A sandbox's restricted key starts with rk_test_. This is the
only Stripe credential CommitLayer ever holds; the secret key used in steps 5 and 6 stays on your machine.
2. In the app: connect Stripe and create three keys
- Connections, add Stripe, paste the
rk_test_key. The connection turns healthy and its first sync starts by itself. - Settings, API keys, create three keys: one with the
fullpreset for the setup calls below, one with therecorderpreset, and one with theevidencepreset bound to the sourcemessaging.
Both steps need a person with the admin role: an API key cannot create a connection or another key.
export COMMITLAYER_API="https://api.commitlayer.ai"
export SETUP_KEY="paste-your-full-key"
export RECORDER_KEY="paste-your-recorder-key"
export EVIDENCE_KEY="paste-your-evidence-key"
3. Dry-run the pack, then install it
curl -sS -X POST "$COMMITLAYER_API/v1/packs/stripe_customer_operations/dry-run" \
-H "X-API-Key: $SETUP_KEY" -H "Content-Type: application/json" -d '{}'
The answer ends with "summary": {"total": 73, "ok": 73, "failed": 0}: every fixture case of the five workflows
ran through the engine in your workspace and gave the verdict the pack expects. Nothing was written. If a call
here answers 503 busy (it can while the connection's first sync is writing), it was not applied: send it again.
curl -sS -X POST "$COMMITLAYER_API/v1/packs/stripe_customer_operations/install" \
-H "X-API-Key: $SETUP_KEY" -H "Content-Type: application/json" -d '{"confirm": true}'
The answer lists five contracts saved as drafts at version 1 and the calls that activate them. On the Developer
plan it lists one, scop_refund_order: the refund workflow is open to every plan and the other four need Builder,
and the Stripe connector this walk uses is not on Developer either.
4. Activate the one contract this walk uses
curl -sS -X POST "$COMMITLAYER_API/v1/contracts/scop_adjust_invoice/select?version=1" \
-H "X-API-Key: $SETUP_KEY"
{"ok": true, "contract_id": "scop_adjust_invoice", "version": 1}. The same is the Activate button on the pack's
page in the app.
5. In Stripe: an open invoice to adjust
With your sandbox's secret key, on your own machine, create a customer, an invoice item of 480.00 USD, an invoice
that includes it, and finalize the invoice so that it is open. Stripe takes amounts in the smallest currency
unit, so 480.00 USD is 48000.
export STRIPE_TEST_KEY="paste-your-sandbox-secret-key"
curl https://api.stripe.com/v1/customers -u "$STRIPE_TEST_KEY:" -d name="Walkthrough Customer"
export STRIPE_CUSTOMER="paste-the-cus-id-from-the-answer"
curl https://api.stripe.com/v1/invoiceitems -u "$STRIPE_TEST_KEY:" \
-d customer="$STRIPE_CUSTOMER" -d amount=48000 -d currency=usd
curl https://api.stripe.com/v1/invoices -u "$STRIPE_TEST_KEY:" \
-d customer="$STRIPE_CUSTOMER" -d collection_method=send_invoice -d days_until_due=30 \
-d pending_invoice_items_behavior=include
export STRIPE_INVOICE="paste-the-in-id-from-the-answer"
curl -X POST "https://api.stripe.com/v1/invoices/$STRIPE_INVOICE/finalize" -u "$STRIPE_TEST_KEY:"
The last answer should show "status": "open".
6. The agent acts: record the action, then issue the credit note
Record first. An effect counts only at or after the action's requested_at, which is the moment of this call,
so the action is recorded before the tool runs. The approval here is a reduction of 120.00 USD; the action
carries major units.
curl -sS -X POST "$COMMITLAYER_API/v1/actions" \
-H "X-API-Key: $RECORDER_KEY" -H "Content-Type: application/json" \
-d "{
\"action_id\": \"adjust:$STRIPE_INVOICE\",
\"contract_id\": \"scop_adjust_invoice\",
\"contract_version\": 1,
\"subject_id\": \"$STRIPE_INVOICE\",
\"subject_kind\": \"invoice\",
\"params\": {\"amount\": 120.0, \"currency\": \"usd\", \"invoice_id\": \"$STRIPE_INVOICE\", \"reason\": \"duplicate_line_item\"},
\"environment\": \"test\"
}"
"environment": "test" is what makes a test-mode key the right evidence: an action recorded as production (the
default) and judged on test-mode Stripe records reads UNKNOWN with evidence_mode_mismatch, never PASS or FAIL.
A test action is metered like any other.
201. The verification in the answer is pending: nothing has been seen for this invoice yet. Its provisional
verdict is UNKNOWN with identity_unmatched, because the connector has not read the new invoice; had a sync
run since step 5 it would be a provisional FAIL naming the two effects still missing. Now the adjustment itself, in Stripe, as a credit note of 12000 against the invoice:
curl https://api.stripe.com/v1/credit_notes -u "$STRIPE_TEST_KEY:" \
-d invoice="$STRIPE_INVOICE" -d amount=12000 -d reason=order_change
7. Push the one fact Stripe does not hold
The contract also expects the customer to have been told. That comes from the system that sent the message, through the evidence key:
curl -sS -X POST "$COMMITLAYER_API/v1/facts" \
-H "X-API-Key: $EVIDENCE_KEY" -H "Content-Type: application/json" \
-d "{\"facts\": [{
\"source\": \"messaging\",
\"subject_id\": \"$STRIPE_INVOICE\",
\"subject_kind\": \"invoice\",
\"fact_type\": \"customer_notified\",
\"occurred_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
\"attributes\": {\"channel\": \"email\"}
}]}"
201 with "ingested": 1, "linked": 0, and beside them one result per record: its id, the evidence trust class
it got and why, and whether it is eligible for the contract. This is the step a first integration misses twice over. First, the fact has
to come from an evidence key: pushed with the recorder key it is refused (403 insufficient_scope), and pushed
with a full key it is classed agent_self_report and never counts. Second, a pushed record is eligible only once
its source is attested for the key that sent it: in the app, open Connections, Evidence pipeline, and on the
messaging row of the evidence key choose Attest (an Owner or Admin, signed in), check the confirmation
(the details are behind "Review what this means") and confirm. That is the record's evidence trust class becoming backend_attested; the action is re-verified by
itself. Until then the verdict carries effect_below_trust:messaging.customer_notified.
8. Sync Stripe and read the verdict
The Stripe connector syncs on its own schedule; ask for a sync now rather than wait:
curl -sS "$COMMITLAYER_API/v1/connections" -H "X-API-Key: $SETUP_KEY"
export STRIPE_CONNECTION="paste-the-id-of-the-stripe-connection"
curl -sS -X POST "$COMMITLAYER_API/v1/connections/$STRIPE_CONNECTION/sync" \
-H "X-API-Key: $SETUP_KEY" -H "Content-Type: application/json" -d '{}'
{"job_id": "…"}; the sync runs in the background and takes a few seconds on a small sandbox. Then:
curl -sS "$COMMITLAYER_API/v1/actions/adjust:$STRIPE_INVOICE/wait?timeout=30" \
-H "X-API-Key: $RECORDER_KEY"
"status": "settled", and under lenses both outcome and policy read "verdict": "PASS" with the codes
effect_observed:stripe.credit_note and effect_observed:messaging.customer_notified. summary.headline says
the same in a sentence, and facts lists the Stripe records the verdict rests on. If it still reads pending,
the sync has not finished: run the last command again.
Read through /wait, as here. The plain GET /v1/actions/{id} evaluates nothing: until a wait has seen the
action settle (or the re-check at the end of the window has run) its lenses are still the ones stored in step
6, UNKNOWN with identity_unmatched, under a status and a summary.headline that are rebuilt from the facts
and already read settled and PASS.
9. Break it once
Do steps 5 and 6 again for a second invoice, and this time record an approval of 100.0 while the credit note
is still 12000. After the push and the sync, the same read returns outcome PASS and policy FAIL with
effect_attr_mismatch:stripe.credit_note.amount: the adjustment happened, and it was not the one approved.
Leave amount out of the action altogether and the policy lens reads UNKNOWN with param_missing:amount: the
checks that read the amount did not run. Reading a verdict lists every code the pack can return
and what to do about each; the adjust_invoice page lists everything this contract checks.
How this page was checked
The commands to CommitLayer (steps 3, 4, 6, 7 and 8) were run in this order against the API, and are run again by
the test suite on every change, with a stand-in answering the four lists the Stripe connector reads (refunds,
credit notes, subscriptions, invoices) in the shape Stripe returns them. The verdicts quoted in steps 8 and 9 are
what the engine returned in that run. The same commands were also run with bash and curl against an API process
on a local port, with the same stand-in for Stripe, and gave the same verdicts. The commands to Stripe (steps 5 and 6) follow Stripe's API reference as it
read on 13 November 2026 and were not run against Stripe: no Stripe key was available when this page was written.
The clicks in steps 1 and 2 were not made in a browser; the routes behind them were called with a signed-in
session.