Stripe pack: connector requirements
Which connectors the Stripe pack needs, the read permissions to grant on each, what is read through it, and what to push instead when a system has no connector.
Last changed Markdown versionllms.txt
What the Stripe Customer Operations pack (version 2.3.0) needs connected before its verdicts mean anything: which connector, with which read permissions, what is read through it, and what to push instead when you do not use it. Generated from the pack's manifest; the permissions are the least-privilege ones on each connector's own page, which also says what is never read or stored.
Connectors
| Connector | For this pack | Read permissions to grant | What the pack reads | Workflows | Without it |
|---|---|---|---|---|---|
| stripe | required | Refunds: read, Credit notes: read, Subscriptions: read, Invoices: read, Customers: read, Charges: read | Refunds and failed refunds on the customer; credit notes and voids on the invoice; subscription status and cancellations; invoice status, payment and voiding; the links from a subscription or an invoice to its customer. | refund_order, cancel_subscription, issue_credit_note, adjust_invoice | Required. Stripe facts cannot be pushed in its place: the contracts accept them from the connector only, and without a connection the four workflows are UNKNOWN (missing_fact_source). |
| shopify | optional | read_orders | Cancellations (order_cancelled) and fulfilments (fulfillment_created, forbidden in the window and a reversal for 30 days) of an order, on the numeric order id. The connector records no order_reopened, so the reversal on a reopened order can only come from a pushed order system. |
refund_order | Name your own order system as order_source and push order_cancelled, fulfillment_created and order_reopened for it with an evidence key. The refund contract asks backend_attested evidence of the order source, so an Owner or Admin attests the pushed source for that key; until then the cancellation reads effect_below_trust. |
| zendesk | optional | tickets:read, ticket_audits:read, satisfaction_ratings:read, users:read | Status changes (status_change, read by to), reopenings (reopen) and escalations of a ticket (zendesk_ticket_{id}). |
all five (reversal only for adjust_invoice) | Push status_change with from and to attributes, and reopen, for the help-desk source with an evidence key, and have an Owner or Admin attest the help-desk source for that key. |
| intercom | optional | Read conversations, Read contacts, Read admins, Read conversation ratings | Closes (status_change to closed) and reopenings of a conversation (intercom_conv_{id}). |
as Zendesk, when helpdesk_source is intercom |
As Zendesk. |
| salesforce | optional | api | Status history of a case (sf_case_{Id}), as status_change with to. |
as Zendesk, when helpdesk_source is salesforce |
As Zendesk. |
| hubspot | optional | tickets | Pipeline-stage history of a ticket (hubspot_ticket_{id}), as status_change with the stage in to. |
as Zendesk, when helpdesk_source is hubspot |
As Zendesk. |
Every connector is read-only; CommitLayer never writes to Stripe, Shopify or a help desk and never holds a Stripe
secret key. The Stripe key is a restricted key, and a restricted key of a Stripe sandbox (rk_test_…) is accepted
like a live one (rk_live_…), which is how the test-mode walkthrough works. Customers: read and
Charges: read are needed because the refund list is read with the charge's customer expanded, to place a refund on its
customer. A key without Invoices: read still syncs the rest, and the sync note says what to grant. One help desk is
read per workflow: the one named as helpdesk_source (zendesk by default).
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.
Evidence each source must bring
| Source | Trust required | Classes accepted | Note |
|---|---|---|---|
stripe |
independent | native_connector, customer_backend |
Refunds, credit notes, subscriptions and invoices are read by the Stripe connector. For refund_order, a backend may push refunds instead, through an evidence key an Owner or Admin attested for the source (backend_attested); a record the agent's own key sends never counts. |
shopify |
independent | native_connector, customer_backend |
Order state, cancellations and fulfilments from the Shopify connector, or pushed by your backend through an attested evidence key (backend_attested). Replace the source with your own order system in the wizard. |
zendesk |
shared | native_connector, customer_backend |
Case state from Zendesk, Intercom, Salesforce or HubSpot by connector, or your helpdesk through the facts API. The wizard's help-desk source renames every help-desk reference in a contract. |
messaging |
shared | customer_backend, provider_webhook |
Customer notifications, pushed by the system that sent them, on the subject the action names (the order, the subscription, the invoice or the ticket). |
messaging has no connector: the system that sent the notification pushes customer_notified through POST /v1/facts with an evidence key bound to that source. A pushed record counts only once an Owner or Admin attests
its source for that key (in the app: Connections, "Evidence pipeline", Attest, with the one confirmation; or POST /v1/evidence/attestations, signed in). Until then the effect reads effect_below_trust. A fact pushed by a key that
can also record actions is classed agent_reported and never satisfies these contracts, whatever is attested.
Identity links
| Link | Joins | Needed by | Who makes it |
|---|---|---|---|
payment_to_order |
stripe payment to shopify order | refund_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 to shopify order | refund_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. |
subscription_to_customer |
stripe subscription to stripe customer | cancel_subscription | Made by the Stripe connector on every sync from the subscription's customer, so a refund on the customer is visible to a cancellation. Nothing to push. |
invoice_to_customer |
stripe invoice to stripe customer | issue_credit_note, adjust_invoice | Made by the Stripe connector on every sync from the invoice's customer, so a cash refund on the customer is visible to a credit or an adjustment. Nothing to push. |
ticket_to_subscription |
zendesk ticket to stripe subscription | cancel_subscription | The ticket names the subscription it is about (the Stripe id, sub_…); push the link beside the ticket facts or with the action. |
ticket_to_invoice |
zendesk ticket to stripe invoice | issue_credit_note, adjust_invoice | The ticket names the invoice it is about (the Stripe id, in_…); push the link beside the ticket facts or with the action. |
How the connectors link the order
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.
GET /v1/packs/stripe_customer_operations/coverage shows, for the workspace as it is, which sources are covered and
at what trust, how old each watermark is, and how many links of each type have been seen. It reports the pack's
default sources: a workspace that named another order or help-desk source in the wizard still sees shopify and
zendesk listed there.