# Stripe pack: connector requirements

What the [Stripe Customer Operations pack](/docs/packs/stripe-customer-operations) (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](/docs/connectors/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](/docs/connectors/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](/docs/connectors/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](/docs/connectors/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](/docs/connectors/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](/docs/connectors/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](/docs/packs/stripe-customer-operations/test-mode) 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.
