justin/new-site
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(billing): record Stripe subscription webhook events as ENABLED + api-version caveat

Browse source 
The 3 subscription-lifecycle events (invoice.paid, invoice.payment_failed,
customer.subscription.deleted) are now enabled on the live endpoint
we_1THBjyB46qMvF2jnYyN8IfkK (6 events total). Documents the unpinned-endpoint
api_version caveat (account default 2024-12-18.acacia, not the SDK's dahlia) and
why invoiceSubscriptionId() must read both invoice shapes. Notes that
charge.dispute.created / balance.available are handled in code but not yet
enabled on the endpoint.
This commit is contained in:
justin 2026-06-18 08:45:22 -05:00
parent 8af2685d07
commit 0083bc1354
1 changed files with 22 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/billing.md
View file

@ -203,14 +203,32 @@ Flow:
- `invoice.payment_failed` -> admin alert + first-failure customer nudge. - `invoice.payment_failed` -> admin alert + first-failure customer nudge.
- `customer.subscription.deleted` -> order marked `cancelled`, fulfillment stops. - `customer.subscription.deleted` -> order marked `cancelled`, fulfillment stops.
**Stripe Dashboard webhook events (MUST be enabled on the prod endpoint):** **Stripe webhook events (ENABLED on the live prod endpoint** `we_1THBjyB46qMvF2jnYyN8IfkK`
in addition to the existing `checkout.session.completed`, `payment_intent.*`, = `https://api.performancewest.net/api/v1/webhooks/stripe`**):**
`charge.dispute.created`, `balance.available`, enable: The 6 currently enabled events are `checkout.session.completed`,
`payment_intent.succeeded`, `payment_intent.payment_failed`, plus the three
subscription-lifecycle events added 2026-06-18:
- `invoice.paid` - `invoice.paid`
- `invoice.payment_failed` - `invoice.payment_failed`
- `customer.subscription.deleted` - `customer.subscription.deleted`
Without these three the monthly cycles will charge but never fulfill/alert. Without these three the monthly cycles would charge but never fulfill/alert.
(Note: the code also *handles* `charge.dispute.created` and `balance.available`
but those are NOT yet enabled on the endpoint — enable them if/when needed.)
To add events without clobbering existing ones, read `enabled_events`, union,
and PUT the union back via `POST /v1/webhook_endpoints/{id}` with repeated
`enabled_events[]=` params (re-running is idempotent).
> **API-version caveat (important):** this endpoint has **no pinned
> `api_version`**, so it follows the Stripe *account default* (currently
> `2024-12-18.acacia`), NOT the `2026-03-25.dahlia` the SDK is pinned to. In
> acacia the subscription link is the **top-level `invoice.subscription`**; in
> dahlia it moved to `invoice.parent.subscription_details.subscription`.
> `invoiceSubscriptionId()` in `webhooks.ts` reads **both** shapes so renewals
> map back to the order regardless. If you ever pin the endpoint to dahlia, the
> handler still works; do NOT remove the legacy fallback while the endpoint is
> unpinned.
The `provider-compliance-bundle` ($899/yr) includes **only the first** OIG/SAM The `provider-compliance-bundle` ($899/yr) includes **only the first** OIG/SAM
screening; customers are converted to the $79/mo monitoring subscription after screening; customers are converted to the $79/mo monitoring subscription after