@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.
- package/CHANGELOG.md +16 -0
- package/MIGRATION.md +1 -1
- package/README.md +12 -12
- package/dist/client/usage/subscriptionCheckout.d.ts.map +1 -1
- package/dist/client/usage/subscriptionCheckout.js +2 -0
- package/dist/client/usage/subscriptionCheckout.js.map +1 -1
- package/dist/react/workflows/UsageSummary.d.ts.map +1 -1
- package/dist/react/workflows/UsageSummary.js +4 -1
- package/dist/react/workflows/UsageSummary.js.map +1 -1
- package/docs/README.md +18 -32
- package/docs/architecture.md +40 -21
- package/docs/client-api.md +15 -3
- package/docs/configuration.md +36 -8
- package/docs/development.md +25 -5
- package/docs/evidence/native-metering/product-flows-2026-10-19.json +553 -0
- package/docs/marketplace.md +34 -10
- package/docs/metered-usage.md +1 -1
- package/docs/metering-setup.md +36 -26
- package/docs/overview.md +14 -3
- package/docs/react-api.md +18 -9
- package/docs/testing.md +29 -4
- package/docs/usage-example.md +159 -244
- package/docs/usage-observations.md +5 -2
- package/docs/usage-protocol-diagnostics.md +251 -0
- package/docs/usage-verification.md +31 -0
- package/docs/webhooks.md +45 -7
- package/package.json +15 -60
- package/src/client/usage/subscriptionCheckout.test.ts +13 -0
- package/src/client/usage/subscriptionCheckout.ts +2 -0
- package/src/react/workflows/Usage.test.tsx +15 -0
- package/src/react/workflows/UsageSummary.tsx +5 -2
|
@@ -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
|
+
}
|
package/docs/marketplace.md
CHANGED
|
@@ -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.
|
|
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
|
-
-
|
|
34
|
-
-
|
|
35
|
-
|
|
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
|
-
|
|
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 `
|
|
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
|
-
//
|
|
118
|
+
// Host helper authenticates ctx.auth and authorizes the original seller account.
|
|
103
119
|
export const createDisputeSession = action({
|
|
104
|
-
args: {
|
|
105
|
-
handler: async (ctx
|
|
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? })`
|
|
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`
|
package/docs/metered-usage.md
CHANGED
|
@@ -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.
|
|
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
|
|