@fantastic.dev/better-stripe 0.68.0 → 0.69.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,553 @@
1
+ {
2
+ "kind": "product-metered-example-native-test-mode",
3
+ "date": "2026-10-19",
4
+ "ticket": "BTS-284",
5
+ "livemode": false,
6
+ "method": "Public host adapter actions backed by the compiled BetterStripe package, plus actual browser actions with Stripe synthetic test cards. Retained IDs are test resources, not credentials.",
7
+ "included_overage": {
8
+ "snapshot": {
9
+ "summary": {
10
+ "status": "available",
11
+ "observedAt": 1792399339,
12
+ "value": {
13
+ "period": {
14
+ "end": 1795077380,
15
+ "start": 1792398980
16
+ },
17
+ "observedAt": 1792399322,
18
+ "complete": true,
19
+ "eventCount": 1,
20
+ "groups": [
21
+ {
22
+ "binding": {
23
+ "stripeCustomerId": "cus_VQz6jBP5zWlyWS",
24
+ "stripePriceId": "price_1USBuv6JR7kThJogV6whMAi1",
25
+ "eventName": "bs_ms7b7j76syc0fyd0qtes5k80eh8gks2f_product_usage_v1",
26
+ "apiVersion": "2026-09-30.endive",
27
+ "plan": {
28
+ "key": "demo_ms7b7j76syc0fyd0qtes5k80eh8gks2f_coaching-minutes",
29
+ "version": "v1",
30
+ "unit": {
31
+ "name": "minute",
32
+ "precision": 0
33
+ },
34
+ "rate": {
35
+ "currency": "usd",
36
+ "unitAmountDecimal": "100"
37
+ },
38
+ "model": "included_overage",
39
+ "includedQuantity": "60",
40
+ "reset": "billing_period"
41
+ }
42
+ },
43
+ "subscription": {
44
+ "subscriptionId": "sub_1USC3O6JR7kThJogep66wAiF",
45
+ "subscriptionItemId": "si_VT8KdSgYvRPsno",
46
+ "stripePriceId": "price_1USBuv6JR7kThJogV6whMAi1",
47
+ "period": {
48
+ "start": 1792398980,
49
+ "end": 1795077380
50
+ },
51
+ "interval": "month"
52
+ },
53
+ "acceptedScaledQuantity": "75",
54
+ "providerAcceptedScaledQuantity": "75",
55
+ "acceptedQuantity": "75",
56
+ "canceledQuantity": "0",
57
+ "effectiveQuantity": "75",
58
+ "effectiveScaledQuantity": "75",
59
+ "providerAcceptedQuantity": "75",
60
+ "eventCount": 1,
61
+ "validationErrorEventCount": 0,
62
+ "deliveryQuantities": {
63
+ "canceled": "0",
64
+ "queued": "0",
65
+ "sending": "0",
66
+ "provider_accepted": "75",
67
+ "rejected": "0",
68
+ "unknown": "0",
69
+ "held": "0"
70
+ },
71
+ "included": {
72
+ "status": "available",
73
+ "observedAt": 1792399322,
74
+ "value": {
75
+ "included": "60",
76
+ "consumed": "75",
77
+ "remaining": "0",
78
+ "overage": "15"
79
+ }
80
+ },
81
+ "estimate": {
82
+ "status": "available",
83
+ "observedAt": 1792399322,
84
+ "value": {
85
+ "amountDecimal": "1500",
86
+ "currency": "usd"
87
+ }
88
+ },
89
+ "credits": {
90
+ "status": "unavailable",
91
+ "reason": "not_prepaid_model",
92
+ "retryable": false
93
+ }
94
+ }
95
+ ]
96
+ }
97
+ },
98
+ "provider": {
99
+ "status": "unsupported",
100
+ "reason": "minute_alignment_required",
101
+ "retryable": false
102
+ },
103
+ "allowance": {
104
+ "status": "available",
105
+ "observedAt": 1792399339,
106
+ "value": {
107
+ "revision": 1,
108
+ "observedAt": 1792399322,
109
+ "period": {
110
+ "start": 1792398980,
111
+ "end": 1795077380
112
+ },
113
+ "accepting": true,
114
+ "policy": {
115
+ "reset": "billing_period",
116
+ "rollover": "none",
117
+ "entitled": true,
118
+ "overage": "allow",
119
+ "limit": {
120
+ "mode": "none"
121
+ }
122
+ },
123
+ "consumedQuantity": "75",
124
+ "reservedQuantity": "0",
125
+ "includedQuantity": "60",
126
+ "remainingIncludedQuantity": "0",
127
+ "billableOverageQuantity": "15",
128
+ "softLimitReached": false,
129
+ "hardLimitRemainingQuantity": null,
130
+ "committedEstimate": {
131
+ "amountDecimal": "1500",
132
+ "currency": "usd"
133
+ },
134
+ "projectedEstimate": {
135
+ "amountDecimal": "1500",
136
+ "currency": "usd"
137
+ },
138
+ "cashCollection": "none"
139
+ }
140
+ }
141
+ },
142
+ "draftInvoice": {
143
+ "status": "available",
144
+ "observedAt": 1792399620,
145
+ "value": {
146
+ "kind": "preview",
147
+ "invoiceId": "upcoming_in_1USCDh6JR7kThJogeQSM3lb9",
148
+ "status": "draft",
149
+ "finalized": false,
150
+ "amountDue": "3500",
151
+ "amountPaid": "0",
152
+ "total": "3500",
153
+ "currency": "usd",
154
+ "linesComplete": true,
155
+ "lines": [
156
+ {
157
+ "lineId": "il_tmp_1UdQpM6JR7kThJog44zlqj8J",
158
+ "stripePriceId": "price_1USBuv6JR7kThJogV6whMAi1",
159
+ "subscriptionItemId": "si_VT8KdSgYvRPsno",
160
+ "amount": "0",
161
+ "currency": "usd",
162
+ "quantity": "60",
163
+ "providerQuantityDecimal": "60",
164
+ "unitAmountDecimal": "0",
165
+ "creditAppliedAmount": "0",
166
+ "nativePeriod": {
167
+ "start": 1792398960,
168
+ "end": 1795077360
169
+ },
170
+ "proration": false
171
+ },
172
+ {
173
+ "lineId": "il_tmp_1UdQpN6JR7kThJog7GhXQIFU",
174
+ "stripePriceId": "price_1USBuv6JR7kThJogV6whMAi1",
175
+ "subscriptionItemId": "si_VT8KdSgYvRPsno",
176
+ "amount": "1500",
177
+ "currency": "usd",
178
+ "quantity": "15",
179
+ "providerQuantityDecimal": "15",
180
+ "unitAmountDecimal": "100",
181
+ "creditAppliedAmount": "0",
182
+ "nativePeriod": {
183
+ "start": 1792398960,
184
+ "end": 1795077360
185
+ },
186
+ "proration": false
187
+ }
188
+ ],
189
+ "meterAmount": {
190
+ "status": "available",
191
+ "observedAt": 1792399620,
192
+ "value": {
193
+ "amount": "1500",
194
+ "currency": "usd"
195
+ }
196
+ },
197
+ "paymentEvidence": "not_resolved"
198
+ }
199
+ }
200
+ },
201
+ "pay_as_you_go": {
202
+ "snapshot": {
203
+ "summary": {
204
+ "status": "available",
205
+ "observedAt": 1792401070,
206
+ "value": {
207
+ "period": {
208
+ "end": 1795079307,
209
+ "start": 1792400907
210
+ },
211
+ "observedAt": 1792401070,
212
+ "complete": true,
213
+ "eventCount": 1,
214
+ "groups": [
215
+ {
216
+ "binding": {
217
+ "stripeCustomerId": "cus_VQz6jBP5zWlyWS",
218
+ "stripePriceId": "price_1USCW26JR7kThJogaEsW4mQ4",
219
+ "eventName": "bs_ms7d7x1q5f0sc6j39d7eyzx5yx8gkkgq_product_usage_v1",
220
+ "apiVersion": "2026-09-30.endive",
221
+ "plan": {
222
+ "key": "demo_ms7d7x1q5f0sc6j39d7eyzx5yx8gkkgq_coaching-minutes",
223
+ "version": "v1",
224
+ "unit": {
225
+ "name": "minute",
226
+ "precision": 0
227
+ },
228
+ "rate": {
229
+ "currency": "usd",
230
+ "unitAmountDecimal": "100"
231
+ },
232
+ "model": "pay_as_you_go"
233
+ }
234
+ },
235
+ "subscription": {
236
+ "subscriptionId": "sub_1USCYT6JR7kThJogAVHowKNq",
237
+ "subscriptionItemId": "si_VT8qEOi3dr7ejz",
238
+ "stripePriceId": "price_1USCW26JR7kThJogaEsW4mQ4",
239
+ "period": {
240
+ "start": 1792400907,
241
+ "end": 1795079307
242
+ },
243
+ "interval": "month"
244
+ },
245
+ "acceptedScaledQuantity": "5",
246
+ "providerAcceptedScaledQuantity": "5",
247
+ "acceptedQuantity": "5",
248
+ "canceledQuantity": "0",
249
+ "effectiveQuantity": "5",
250
+ "effectiveScaledQuantity": "5",
251
+ "providerAcceptedQuantity": "5",
252
+ "eventCount": 1,
253
+ "validationErrorEventCount": 0,
254
+ "deliveryQuantities": {
255
+ "canceled": "0",
256
+ "queued": "0",
257
+ "sending": "0",
258
+ "provider_accepted": "5",
259
+ "rejected": "0",
260
+ "unknown": "0",
261
+ "held": "0"
262
+ },
263
+ "included": {
264
+ "status": "unavailable",
265
+ "reason": "not_included_model",
266
+ "retryable": false
267
+ },
268
+ "estimate": {
269
+ "status": "available",
270
+ "observedAt": 1792401070,
271
+ "value": {
272
+ "amountDecimal": "500",
273
+ "currency": "usd"
274
+ }
275
+ },
276
+ "credits": {
277
+ "status": "unavailable",
278
+ "reason": "not_prepaid_model",
279
+ "retryable": false
280
+ }
281
+ }
282
+ ]
283
+ }
284
+ },
285
+ "provider": {
286
+ "status": "unsupported",
287
+ "reason": "minute_alignment_required",
288
+ "retryable": false
289
+ },
290
+ "allowance": {
291
+ "status": "available",
292
+ "observedAt": 1792401070,
293
+ "value": {
294
+ "revision": 1,
295
+ "observedAt": 1792401070,
296
+ "period": {
297
+ "start": 1792400907,
298
+ "end": 1795079307
299
+ },
300
+ "accepting": true,
301
+ "policy": {
302
+ "reset": "billing_period",
303
+ "rollover": "none",
304
+ "entitled": true,
305
+ "overage": "allow",
306
+ "limit": {
307
+ "mode": "none"
308
+ }
309
+ },
310
+ "consumedQuantity": "5",
311
+ "reservedQuantity": "0",
312
+ "includedQuantity": "0",
313
+ "remainingIncludedQuantity": "0",
314
+ "billableOverageQuantity": "5",
315
+ "softLimitReached": false,
316
+ "hardLimitRemainingQuantity": null,
317
+ "committedEstimate": {
318
+ "amountDecimal": "500",
319
+ "currency": "usd"
320
+ },
321
+ "projectedEstimate": {
322
+ "amountDecimal": "500",
323
+ "currency": "usd"
324
+ },
325
+ "cashCollection": "none"
326
+ }
327
+ }
328
+ },
329
+ "draftInvoice": {
330
+ "status": "available",
331
+ "observedAt": 1792401103,
332
+ "value": {
333
+ "kind": "preview",
334
+ "invoiceId": "upcoming_in_1USCbc6JR7kThJogAiHQO5yP",
335
+ "status": "draft",
336
+ "finalized": false,
337
+ "amountDue": "500",
338
+ "amountPaid": "0",
339
+ "total": "500",
340
+ "currency": "usd",
341
+ "linesComplete": true,
342
+ "lines": [
343
+ {
344
+ "lineId": "il_tmp_1UdRKR6JR7kThJogLvBYjTiq",
345
+ "stripePriceId": "price_1USCW26JR7kThJogaEsW4mQ4",
346
+ "subscriptionItemId": "si_VT8qEOi3dr7ejz",
347
+ "amount": "500",
348
+ "currency": "usd",
349
+ "quantity": "5",
350
+ "providerQuantityDecimal": "5",
351
+ "unitAmountDecimal": "100",
352
+ "creditAppliedAmount": "0",
353
+ "nativePeriod": {
354
+ "start": 1792400880,
355
+ "end": 1795079280
356
+ },
357
+ "proration": false
358
+ }
359
+ ],
360
+ "meterAmount": {
361
+ "status": "available",
362
+ "observedAt": 1792401103,
363
+ "value": {
364
+ "amount": "500",
365
+ "currency": "usd"
366
+ }
367
+ },
368
+ "paymentEvidence": "not_resolved"
369
+ }
370
+ }
371
+ },
372
+ "prepaid": {
373
+ "snapshot": {
374
+ "summary": {
375
+ "status": "available",
376
+ "observedAt": 1792400668,
377
+ "value": {
378
+ "period": {
379
+ "end": 1795078860,
380
+ "start": 1792400460
381
+ },
382
+ "observedAt": 1792400668,
383
+ "complete": true,
384
+ "eventCount": 1,
385
+ "groups": [
386
+ {
387
+ "binding": {
388
+ "stripeCustomerId": "cus_VQz7dXpr24DfqB",
389
+ "stripePriceId": "price_1USCMU6JR7kThJogBWNtUi8l",
390
+ "eventName": "bs_ms7c2p22z5hrpev8mfds4efh3h8gk2a7_product_usage_v1",
391
+ "apiVersion": "2026-09-30.endive",
392
+ "plan": {
393
+ "key": "demo_ms7c2p22z5hrpev8mfds4efh3h8gk2a7_report-credits",
394
+ "version": "v1",
395
+ "unit": {
396
+ "name": "report",
397
+ "precision": 0
398
+ },
399
+ "rate": {
400
+ "currency": "usd",
401
+ "unitAmountDecimal": "100"
402
+ },
403
+ "model": "prepaid",
404
+ "insufficientBalance": "reject"
405
+ }
406
+ },
407
+ "subscription": {
408
+ "subscriptionId": "sub_1USCRE6JR7kThJogachZOokb",
409
+ "subscriptionItemId": "si_VT8iAGyjWDamzd",
410
+ "stripePriceId": "price_1USCMU6JR7kThJogBWNtUi8l",
411
+ "period": {
412
+ "start": 1792400460,
413
+ "end": 1795078860
414
+ },
415
+ "interval": "month"
416
+ },
417
+ "acceptedScaledQuantity": "10",
418
+ "providerAcceptedScaledQuantity": "10",
419
+ "acceptedQuantity": "10",
420
+ "canceledQuantity": "0",
421
+ "effectiveQuantity": "10",
422
+ "effectiveScaledQuantity": "10",
423
+ "providerAcceptedQuantity": "10",
424
+ "eventCount": 1,
425
+ "validationErrorEventCount": 0,
426
+ "deliveryQuantities": {
427
+ "canceled": "0",
428
+ "queued": "0",
429
+ "sending": "0",
430
+ "provider_accepted": "10",
431
+ "rejected": "0",
432
+ "unknown": "0",
433
+ "held": "0"
434
+ },
435
+ "included": {
436
+ "status": "unavailable",
437
+ "reason": "not_included_model",
438
+ "retryable": false
439
+ },
440
+ "estimate": {
441
+ "status": "unavailable",
442
+ "reason": "credit_balance_requires_scoped_reader",
443
+ "retryable": false
444
+ },
445
+ "credits": {
446
+ "status": "unavailable",
447
+ "reason": "credit_balance_requires_scoped_reader",
448
+ "retryable": false
449
+ }
450
+ }
451
+ ]
452
+ }
453
+ },
454
+ "provider": {
455
+ "status": "unavailable",
456
+ "reason": "aggregation_pending",
457
+ "retryable": true
458
+ },
459
+ "credits": {
460
+ "status": "available",
461
+ "observedAt": 1792400668,
462
+ "value": {
463
+ "availableQuantity": "0",
464
+ "cashCollection": "none",
465
+ "consumedQuantity": "10",
466
+ "currency": "usd",
467
+ "expiredQuantity": "0",
468
+ "frozenQuantity": "0",
469
+ "precision": 0,
470
+ "reservedQuantity": "0",
471
+ "status": "available",
472
+ "unit": "report"
473
+ }
474
+ }
475
+ },
476
+ "draftInvoice": {
477
+ "status": "available",
478
+ "observedAt": 1792400846,
479
+ "value": {
480
+ "kind": "preview",
481
+ "invoiceId": "upcoming_in_1USCXT6JR7kThJogvouGEyfX",
482
+ "status": "draft",
483
+ "finalized": false,
484
+ "amountDue": "0",
485
+ "amountPaid": "0",
486
+ "total": "0",
487
+ "currency": "usd",
488
+ "linesComplete": true,
489
+ "lines": [
490
+ {
491
+ "lineId": "il_tmp_1UdRDE6JR7kThJogIcCFjRhw",
492
+ "stripePriceId": "price_1USCMU6JR7kThJogBWNtUi8l",
493
+ "subscriptionItemId": "si_VT8iAGyjWDamzd",
494
+ "amount": "1000",
495
+ "currency": "usd",
496
+ "quantity": "10",
497
+ "providerQuantityDecimal": "10",
498
+ "unitAmountDecimal": "100",
499
+ "creditAppliedAmount": "1000",
500
+ "nativePeriod": {
501
+ "start": 1792400460,
502
+ "end": 1795078860
503
+ },
504
+ "proration": false
505
+ }
506
+ ],
507
+ "meterAmount": {
508
+ "status": "available",
509
+ "observedAt": 1792400846,
510
+ "value": {
511
+ "amount": "1000",
512
+ "currency": "usd"
513
+ }
514
+ },
515
+ "paymentEvidence": "not_resolved"
516
+ }
517
+ },
518
+ "originalPurchase": {
519
+ "purchaseId": "product_mx72qwxptr9y0bmrv38e1bf1v58gk88y",
520
+ "state": "ready",
521
+ "paymentIntentId": "pi_3USCTy6JR7kThJog0BOrUg5Q",
522
+ "creditGrantId": "credgr_test_61VbaRMpI1AJxgkMW416JR7kThJogLbc",
523
+ "quantity": "10",
524
+ "amount": 1000,
525
+ "currency": "usd"
526
+ },
527
+ "work": {
528
+ "status": "accepted",
529
+ "work": "completed_once",
530
+ "receiptId": "ss784ertb6b065ppxm7psr5zv58gj2x6"
531
+ },
532
+ "sameRequestReplay": {
533
+ "status": "accepted",
534
+ "work": "already_completed",
535
+ "receiptId": "ss784ertb6b065ppxm7psr5zv58gj2x6"
536
+ },
537
+ "eleventhReport": {
538
+ "status": "denied",
539
+ "work": "not_performed"
540
+ }
541
+ },
542
+ "cancellation": {
543
+ "cancelAtPeriodEnd": true,
544
+ "status": "active"
545
+ },
546
+ "limitations": [
547
+ "Draft invoice amounts are estimates, not collected funds or executed seller transfers.",
548
+ "Ordinary Checkout subscription boundaries have partial minutes. Exact provider aggregate is explicitly unsupported; no billing-period rounding is used.",
549
+ "Mixed base-fee and usage invoices remain ineligible for automatic seller settlement under the current verifier.",
550
+ "Original prepaid checkout test enrollment was held, its renewal canceled and its history retained. New prepaid enrollments use send_invoice; no original identity was rebound.",
551
+ "No shared customer test clock was advanced; no live money, production migration or npm publication."
552
+ ]
553
+ }
@@ -1,6 +1,6 @@
1
1
  # Marketplace economics
2
2
 
3
- The platform is always the merchant of record (Skool-style marketplace model): sellers are Connect recipients, not merchants. This section covers the fee, split, payout, dispute, and refund/descriptor primitives that implement that model. All amounts are minor units (cents).
3
+ The platform is always the merchant of record (Skool-style marketplace model): sellers are Connect recipients, not merchants. This section covers the fee, split, payout, dispute, and refund/descriptor primitives that implement that model. Amounts use the currency's minor units, cents for USD. Do not assume two decimal places for every currency.
4
4
 
5
5
  ### Fee Model
6
6
 
@@ -30,9 +30,19 @@ const { feeAmount, percentApplied, fixedApplied, tier } = computeFee(2999, {
30
30
 
31
31
  **How the fee is charged** depends on shape and charge type:
32
32
 
33
- - **Percent-only** fees (`isPercentOnlyFee(config)` — no `fixed`, no `tiers`) map directly to Stripe's `application_fee_percent` on the subscription/PaymentIntent — no per-invoice computation needed.
34
- - **Fixed or tiered** fees can't be expressed as a flat Stripe percentage, so they're computed and applied per invoice (`applyPerInvoiceFee`, at `invoice.created`) or per one-time charge (`applyPerChargeFee`) in the webhook processor, via `application_fee_amount`.
35
- - For synchronously finalized first invoices, `invoice.paid` collects the missed fixed/tiered fee through a partial destination-transfer reversal. See [first-invoice fee handling](overview.md#roadmap--known-gaps).
33
+ - Percent-only subscription fees use `application_fee_percent`.
34
+ - A one-time destination charge with a known amount computes
35
+ `application_fee_amount` before confirmation, including percent-only rates.
36
+ - Fixed/tiered subscription fees are computed on draft `invoice.created` and set
37
+ as `application_fee_amount`. A synchronously finalized first invoice misses
38
+ that draft window; `invoice.paid` collects its fee through a retained partial
39
+ destination-transfer reversal.
40
+ - A deferred one-time fee cannot be attached to a succeeded PaymentIntent as
41
+ `application_fee_amount`. The webhook processor collects it through a partial
42
+ reversal of the original destination transfer with retained recovery evidence.
43
+
44
+ See [first-invoice fee handling](overview.md#roadmap--known-gaps) for replay
45
+ and duplicate-collection guards.
36
46
 
37
47
  Fees only apply to **destination charges** (`destinationAccountId` set, or a single-recipient `split`). The **separate-charges-and-transfers** path (multi-recipient `split`) never uses `application_fee` — the platform's cut is realized by transferring less than was charged (see Split Engine below).
38
48
 
@@ -86,7 +96,13 @@ const result = computeSplit(10000, { percent: 10 }, [
86
96
 
87
97
  ### Payouts
88
98
 
89
- Payouts are **automatic and rolling** (Stripe-managed schedule, via hosted Express onboarding) — there is no manual-withdrawal API. `listPayouts`/`createPayout` track/trigger payouts for a Connect account; `PayoutSchedule` (React) and `useEarnings` (React) surface the recipient's balance and next expected payout, with a link out to the hosted Express dashboard for details. See [React Hooks](react-api.md#react-hooks) and [React Components](react-api.md#react-components).
99
+ Stripe-managed automatic payouts are the default. `listPayouts` reads history
100
+ and `createPayout` submits an authorized payout. The package also supports
101
+ explicit recipient-held custom policies, verified manual schedule changes and
102
+ automatic workers. Those require consent, source/recovery verification and
103
+ the [payout policy controls](settlement.md#recipient-held-payout-policy-controls).
104
+ The presentational `PayoutSchedule` component shows a supplied balance and next
105
+ payout; that component offers no withdrawal command. See [React workflows](react-workflows.md#payout-settings).
90
106
 
91
107
  ### Disputes
92
108
 
@@ -94,21 +110,29 @@ The platform is merchant of record, so a chargeback lands on the platform's Stri
94
110
 
95
111
  1. **Clawback** — a monetary `charge.dispute.created` event uses the disputed charge's original gross amount to calculate affiliate commission exposure. Inquiry/warning, prevented, and already-won payloads do not trigger recovery. Affiliate legs share the original-principal exposure axis with refunds; seller and other legs retain the existing reversal allocation. The dispute ID identifies the operation, and a missing authoritative charge amount causes recovery to retry.
96
112
  2. **Reinstatement** — if the dispute is won (`.closed` with `status: "won"`, or `.funds_reinstated`), the existing `reinstateTransfers` path creates new transfers from the platform balance. Affiliate restoration uses exact reversal/offset receipts, preserves independent successful refunds, and cancels unpaid dispute debt. Failed or uncertain restoration remains visible until reconciled. See [recovery limitations](affiliate-clawbacks.md#verification-evidence).
97
- 3. **Auto-cancel** — on dispute open, the disputed subscription (resolved PaymentIntent → invoice → subscription) is canceled by default (`registerRoutes`'s `autoCancelOnDispute`, default `true`; pairs with `cancelDisputeAtPeriodEnd`, default `false` → cancel-at-period-end, matching the Skool model of "cancel now, remove access at cycle end").
113
+ 3. **Auto-cancel** — on dispute open, the disputed subscription (resolved PaymentIntent → invoice → subscription) is canceled by default (`registerRoutes`'s `autoCancelOnDispute`, default `true`; pairs with `cancelDisputedSubscriptionImmediately`, default `false` → cancel-at-period-end, matching the Skool model of "cancel now, remove access at cycle end").
98
114
 
99
115
  Sellers respond to their own disputes without platform staff involvement, via an embedded Stripe Connect session:
100
116
 
101
117
  ```typescript
102
- // server: expose the account session
118
+ // Host helper authenticates ctx.auth and authorizes the original seller account.
103
119
  export const createDisputeSession = action({
104
- args: { stripeAccountId: v.string() },
105
- handler: async (ctx, args) => stripe.createDisputeSession(ctx, args),
120
+ args: {},
121
+ handler: async (ctx) => {
122
+ const stripeAccountId = await requireAuthorizedSellerAccount(ctx);
123
+ return stripe.createDisputeSession(ctx, { stripeAccountId });
124
+ },
106
125
  });
107
126
  ```
108
127
 
109
128
  `stripe.createDisputeSession(ctx, { stripeAccountId })` creates an Account Session scoped to `disputes_list`/`payment_disputes` — mount it with the `ConnectProvider`/`EmbeddedDisputes` React components (see [Embedded Disputes](react-api.md#embedded-disputes-stripe-connect)), or build a custom UI on `updateDispute`/`closeDispute` plus the headless `DisputesList`/`DisputeDetail`/`EvidenceForm` components and `buildDisputeEvidence`/`disputeEvidenceCountdown` helpers (see [React Components](react-api.md#react-components)).
110
129
 
111
- `stripe.reverseTransfers(ctx, { sourceChargeId, percent?, amount? })` is also exposed directly, for manual clawback outside the automatic dispute flow (e.g. a support-initiated partial reversal). The internal engine additionally accepts an `operationId` for a stable Stripe idempotency key (used by the automatic dispute flow); the public method doesn't expose it yet, so a manual call relies on Stripe's default request idempotency.
130
+ `stripe.reverseTransfers(ctx, { sourceChargeId, percent?, amount?, operationId? })`
131
+ exposes the existing reversal primitive. Supply a stable, server-derived
132
+ `operationId` to retain original slices and idempotency keys across retries.
133
+ Without it the call is a one-shot reversal with no idempotency protection; an
134
+ uncertain outcome must not be blindly retried. Authorize the original charge,
135
+ amount and recovery policy before invoking it.
112
136
 
113
137
  For commissions tracked by the recovery ledger, generic manual reversal is
114
138
  rejected. Use `createRefund` for a real refund or `stripe.affiliateRecovery.retry`
@@ -21,7 +21,7 @@ is included.
21
21
  | `included_overage` | Gets included units each verified monthly period, then pays for overage | Atomic included/overage reservations, hard or soft limits, separate period counters |
22
22
  | `prepaid` | Buys units before consumption | Verified original payment and price-scoped grant, atomic reservation/consumption, exhaustion and recovery |
23
23
 
24
- Developers choose the unit, precision, price and policy. This example uses whole
24
+ Developers choose the unit, precision, price and policy. The recipe below uses whole
25
25
  requests at USD 1 per request. Rates are decimal strings of **minor currency
26
26
  units per whole billable unit**, so USD `"100"` means USD 1, not USD 100.
27
27