@fantastic.dev/better-stripe 0.71.0 → 0.72.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 +6 -0
- package/README.md +1 -1
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +524 -50
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +246 -9
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +524 -50
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +246 -9
- package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
- package/dist/client/paymentSource/resolver.d.ts +6 -1
- package/dist/client/paymentSource/resolver.d.ts.map +1 -1
- package/dist/client/paymentSource/resolver.js +49 -41
- package/dist/client/paymentSource/resolver.js.map +1 -1
- package/dist/client/processingCostReconciliation/provider.d.ts.map +1 -1
- package/dist/client/processingCostReconciliation/provider.js +14 -2
- package/dist/client/processingCostReconciliation/provider.js.map +1 -1
- package/dist/client/settlement/authorization.fixture.d.ts +26 -0
- package/dist/client/settlement/authorization.fixture.d.ts.map +1 -1
- package/dist/client/settlement/execution.d.ts +2 -0
- package/dist/client/settlement/execution.d.ts.map +1 -1
- package/dist/client/settlement/execution.js.map +1 -1
- package/dist/client/usage/index.d.ts +1 -0
- package/dist/client/usage/index.d.ts.map +1 -1
- package/dist/client/usage/invoiceSale.d.ts +8 -0
- package/dist/client/usage/invoiceSale.d.ts.map +1 -1
- package/dist/client/usage/invoiceSale.js +3 -0
- package/dist/client/usage/invoiceSale.js.map +1 -1
- package/dist/client/usage/mixedInvoice.fixtures.d.ts +315 -0
- package/dist/client/usage/mixedInvoice.fixtures.d.ts.map +1 -0
- package/dist/client/usage/mixedInvoice.fixtures.js +55 -0
- package/dist/client/usage/mixedInvoice.fixtures.js.map +1 -0
- package/dist/client/usage/mixedInvoiceSale.d.ts +6 -0
- package/dist/client/usage/mixedInvoiceSale.d.ts.map +1 -0
- package/dist/client/usage/mixedInvoiceSale.js +160 -0
- package/dist/client/usage/mixedInvoiceSale.js.map +1 -0
- package/dist/client/usage/observationClient.d.ts +2 -2
- package/dist/client/usage/observationClient.d.ts.map +1 -1
- package/dist/client/usage/retainedInvoiceSource.d.ts +20 -0
- package/dist/client/usage/retainedInvoiceSource.d.ts.map +1 -0
- package/dist/client/usage/retainedInvoiceSource.js +92 -0
- package/dist/client/usage/retainedInvoiceSource.js.map +1 -0
- package/dist/client/usage/settlement.d.ts +5 -0
- package/dist/client/usage/settlement.d.ts.map +1 -1
- package/dist/client/usage/settlement.js +28 -9
- package/dist/client/usage/settlement.js.map +1 -1
- package/dist/component/_generated/component.d.ts +65 -0
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
- package/dist/component/balanceFunding/mutations.d.ts +16 -16
- package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
- package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
- package/dist/component/earnings/triggers.d.ts +84 -6
- package/dist/component/earnings/triggers.d.ts.map +1 -1
- package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
- package/dist/component/recoveryWorkflow/helpers.d.ts +13 -0
- package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
- package/dist/component/recoveryWorkflow/mutations.d.ts +13 -0
- package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
- package/dist/component/recoveryWorkflow/queries.d.ts +26 -0
- package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
- package/dist/component/recoveryWorkflow/schema.d.ts +464 -16
- package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
- package/dist/component/schema.d.ts +246 -9
- package/dist/component/settlement/mutations.d.ts +26 -0
- package/dist/component/settlement/mutations.d.ts.map +1 -1
- package/dist/component/settlement/queries.d.ts +13 -0
- package/dist/component/settlement/queries.d.ts.map +1 -1
- package/dist/component/settlement/schema.d.ts +122 -3
- package/dist/component/settlement/schema.d.ts.map +1 -1
- package/dist/component/settlement/schema.js +2 -0
- package/dist/component/settlement/schema.js.map +1 -1
- package/dist/component/usage/allowance.fixtures.d.ts +262 -25
- package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
- package/dist/component/usageCredits/accounting.fixtures.d.ts +246 -9
- package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
- package/dist/shared/usageInvoiceLines.d.ts +32 -0
- package/dist/shared/usageInvoiceLines.d.ts.map +1 -0
- package/dist/shared/usageInvoiceLines.js +13 -0
- package/dist/shared/usageInvoiceLines.js.map +1 -0
- package/docs/evidence/native-metering/mixed-settlement-2026-10-20.json +284 -0
- package/docs/metering-setup.md +3 -2
- package/docs/usage-example.md +24 -5
- package/docs/usage-settlement.md +74 -8
- package/docs/usage-verification.md +22 -2
- package/package.json +1 -1
- package/src/client/paymentSource/resolver.ts +80 -59
- package/src/client/processingCostReconciliation/provider.ts +20 -2
- package/src/client/settlement/execution.ts +2 -0
- package/src/client/usage/index.ts +2 -0
- package/src/client/usage/invoiceSale.ts +10 -0
- package/src/client/usage/mixedInvoice.fixtures.ts +54 -0
- package/src/client/usage/mixedInvoiceSale.test.ts +92 -0
- package/src/client/usage/mixedInvoiceSale.ts +196 -0
- package/src/client/usage/mixedSettlement.test.ts +187 -0
- package/src/client/usage/retainedInvoiceSource.ts +118 -0
- package/src/client/usage/settlement.ts +47 -9
- package/src/component/_generated/component.ts +50 -0
- package/src/component/settlement/schema.ts +2 -0
- package/src/shared/usageInvoiceLines.ts +14 -0
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
{
|
|
2
|
+
"kind": "native-mixed-invoice-settlement",
|
|
3
|
+
"date": "2026-10-20",
|
|
4
|
+
"ticket": "BTS-287",
|
|
5
|
+
"livemode": false,
|
|
6
|
+
"apiVersion": "2026-09-30.endive",
|
|
7
|
+
"method": "Compiled BetterStripe SDK against native Stripe test APIs; isolated Accounts v2 payer/test clock for initial and renewal cash; original product example invoice replay through billing hook and durable settlement workflow. No shared customer clock advancement.",
|
|
8
|
+
"fixture": {
|
|
9
|
+
"runId": "bts287-native-v1",
|
|
10
|
+
"clockId": "clock_1USSD76JR7kThJogiWhQYpXY",
|
|
11
|
+
"sellerAccountId": "acct_1UQ78o7xOsB2U2nM",
|
|
12
|
+
"productId": "prod_VTP1DX2R2js6f5",
|
|
13
|
+
"invoiceId": "in_1USSDC6JR7kThJog3yQnJQdG",
|
|
14
|
+
"input": {
|
|
15
|
+
"scope": {
|
|
16
|
+
"stripeAccountId": "acct_1TEQzE6JR7kThJog",
|
|
17
|
+
"customerAccount": "acct_1USSD78k9tFVeKFN",
|
|
18
|
+
"meterId": "mtr_test_61VbqAVIxs9O0sFgt416JR7kThJogO5w",
|
|
19
|
+
"livemode": false
|
|
20
|
+
},
|
|
21
|
+
"binding": {
|
|
22
|
+
"stripeCustomerId": "cus_VTP1D5rkZMxZHc",
|
|
23
|
+
"stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
|
|
24
|
+
"eventName": "bts287_native_v1",
|
|
25
|
+
"apiVersion": "2026-09-30.endive",
|
|
26
|
+
"plan": {
|
|
27
|
+
"key": "bts287-native-v1",
|
|
28
|
+
"version": "v1",
|
|
29
|
+
"unit": {
|
|
30
|
+
"name": "minute",
|
|
31
|
+
"precision": 0
|
|
32
|
+
},
|
|
33
|
+
"rate": {
|
|
34
|
+
"currency": "usd",
|
|
35
|
+
"unitAmountDecimal": "100"
|
|
36
|
+
},
|
|
37
|
+
"model": "included_overage",
|
|
38
|
+
"includedQuantity": "60",
|
|
39
|
+
"reset": "billing_period"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"subscription": {
|
|
43
|
+
"subscriptionId": "sub_1USSDC6JR7kThJogK1m7V9Q2",
|
|
44
|
+
"subscriptionItemId": "si_VTP1jHuM4LSQWN",
|
|
45
|
+
"stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
|
|
46
|
+
"period": {
|
|
47
|
+
"start": 1792461060,
|
|
48
|
+
"end": 1795139460
|
|
49
|
+
},
|
|
50
|
+
"interval": "month"
|
|
51
|
+
},
|
|
52
|
+
"period": {
|
|
53
|
+
"start": 1792461060,
|
|
54
|
+
"end": 1795139460
|
|
55
|
+
},
|
|
56
|
+
"fixedPrice": {
|
|
57
|
+
"stripePriceId": "price_1USSDA6JR7kThJoguUhyBEXl",
|
|
58
|
+
"subscriptionItemId": "si_VTP18QFXyYFnDo",
|
|
59
|
+
"unitAmount": 2000
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"initial": {
|
|
64
|
+
"sourceChargeId": "ch_3USSDf6JR7kThJog0F5su3xa",
|
|
65
|
+
"paymentIntentId": "pi_3USSDf6JR7kThJog0Zj92PRp",
|
|
66
|
+
"sourceInvoiceId": "in_1USSDC6JR7kThJog3yQnJQdG",
|
|
67
|
+
"usageSource": {
|
|
68
|
+
"customerAccount": "acct_1USSD78k9tFVeKFN",
|
|
69
|
+
"invoiceLines": [
|
|
70
|
+
{
|
|
71
|
+
"amount": 2000,
|
|
72
|
+
"kind": "fixed",
|
|
73
|
+
"lineId": "il_1USSCe6JR7kThJogfcJks0En",
|
|
74
|
+
"period": {
|
|
75
|
+
"end": 1795139460,
|
|
76
|
+
"start": 1792461060
|
|
77
|
+
},
|
|
78
|
+
"quantity": "1",
|
|
79
|
+
"stripePriceId": "price_1USSDA6JR7kThJoguUhyBEXl",
|
|
80
|
+
"stripeProductId": "prod_VTP1DX2R2js6f5",
|
|
81
|
+
"subscriptionItemId": "si_VTP18QFXyYFnDo"
|
|
82
|
+
}
|
|
83
|
+
],
|
|
84
|
+
"invoicePaymentId": "inpay_1USSDf6JR7kThJogCongDU4L",
|
|
85
|
+
"livemode": false,
|
|
86
|
+
"meterId": "mtr_test_61VbqAVIxs9O0sFgt416JR7kThJogO5w",
|
|
87
|
+
"model": "included_overage",
|
|
88
|
+
"period": {
|
|
89
|
+
"end": 1795139460,
|
|
90
|
+
"start": 1792461060
|
|
91
|
+
},
|
|
92
|
+
"stripeAccountId": "acct_1TEQzE6JR7kThJog",
|
|
93
|
+
"stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
|
|
94
|
+
"stripeProductId": "prod_VTP1DX2R2js6f5",
|
|
95
|
+
"subscriptionId": "sub_1USSDC6JR7kThJogK1m7V9Q2",
|
|
96
|
+
"subscriptionItemId": "si_VTP1jHuM4LSQWN"
|
|
97
|
+
},
|
|
98
|
+
"gross": 2000,
|
|
99
|
+
"currency": "usd",
|
|
100
|
+
"processingFee": 88,
|
|
101
|
+
"platformNet": 92,
|
|
102
|
+
"transfers": [
|
|
103
|
+
{
|
|
104
|
+
"amount": 1820,
|
|
105
|
+
"destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
|
|
106
|
+
"role": "store"
|
|
107
|
+
}
|
|
108
|
+
],
|
|
109
|
+
"status": "settled",
|
|
110
|
+
"executedTransfers": [
|
|
111
|
+
{
|
|
112
|
+
"stripeTransferId": "tr_3USSDf6JR7kThJog0X6GYuWa",
|
|
113
|
+
"destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
|
|
114
|
+
"role": "store",
|
|
115
|
+
"amount": 1820
|
|
116
|
+
}
|
|
117
|
+
]
|
|
118
|
+
},
|
|
119
|
+
"renewalInvoice": {
|
|
120
|
+
"id": "in_1USSEa6JR7kThJogK6C02ulM",
|
|
121
|
+
"status": "open",
|
|
122
|
+
"total": 3500,
|
|
123
|
+
"paid": 0,
|
|
124
|
+
"reason": "subscription_cycle",
|
|
125
|
+
"lines": [
|
|
126
|
+
{
|
|
127
|
+
"id": "il_1Udgye6JR7kThJogo8mem1ju",
|
|
128
|
+
"amount": 0,
|
|
129
|
+
"quantity": "60",
|
|
130
|
+
"period": {
|
|
131
|
+
"end": 1795139460,
|
|
132
|
+
"start": 1792461060
|
|
133
|
+
},
|
|
134
|
+
"price": "price_1USSDA6JR7kThJogT3xsgBd6"
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
"id": "il_1Udgyf6JR7kThJogGYOwmntt",
|
|
138
|
+
"amount": 1500,
|
|
139
|
+
"quantity": "15",
|
|
140
|
+
"period": {
|
|
141
|
+
"end": 1795139460,
|
|
142
|
+
"start": 1792461060
|
|
143
|
+
},
|
|
144
|
+
"price": "price_1USSDA6JR7kThJogT3xsgBd6"
|
|
145
|
+
},
|
|
146
|
+
{
|
|
147
|
+
"id": "il_1Udgyg6JR7kThJog3UoOkXqt",
|
|
148
|
+
"amount": 2000,
|
|
149
|
+
"quantity": "1",
|
|
150
|
+
"period": {
|
|
151
|
+
"end": 1797731460,
|
|
152
|
+
"start": 1795139460
|
|
153
|
+
},
|
|
154
|
+
"price": "price_1USSDA6JR7kThJoguUhyBEXl"
|
|
155
|
+
}
|
|
156
|
+
]
|
|
157
|
+
},
|
|
158
|
+
"renewal": {
|
|
159
|
+
"sourceChargeId": "ch_3USSEg6JR7kThJog1TT4PblE",
|
|
160
|
+
"paymentIntentId": "pi_3USSEg6JR7kThJog1beR1tZF",
|
|
161
|
+
"sourceInvoiceId": "in_1USSEa6JR7kThJogK6C02ulM",
|
|
162
|
+
"usageSource": {
|
|
163
|
+
"customerAccount": "acct_1USSD78k9tFVeKFN",
|
|
164
|
+
"invoiceLines": [
|
|
165
|
+
{
|
|
166
|
+
"amount": 0,
|
|
167
|
+
"kind": "metered",
|
|
168
|
+
"lineId": "il_1Udgye6JR7kThJogo8mem1ju",
|
|
169
|
+
"period": {
|
|
170
|
+
"end": 1795139460,
|
|
171
|
+
"start": 1792461060
|
|
172
|
+
},
|
|
173
|
+
"quantity": "60",
|
|
174
|
+
"stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
|
|
175
|
+
"stripeProductId": "prod_VTP1DX2R2js6f5",
|
|
176
|
+
"subscriptionItemId": "si_VTP1jHuM4LSQWN"
|
|
177
|
+
},
|
|
178
|
+
{
|
|
179
|
+
"amount": 1500,
|
|
180
|
+
"kind": "metered",
|
|
181
|
+
"lineId": "il_1Udgyf6JR7kThJogGYOwmntt",
|
|
182
|
+
"period": {
|
|
183
|
+
"end": 1795139460,
|
|
184
|
+
"start": 1792461060
|
|
185
|
+
},
|
|
186
|
+
"quantity": "15",
|
|
187
|
+
"stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
|
|
188
|
+
"stripeProductId": "prod_VTP1DX2R2js6f5",
|
|
189
|
+
"subscriptionItemId": "si_VTP1jHuM4LSQWN"
|
|
190
|
+
},
|
|
191
|
+
{
|
|
192
|
+
"amount": 2000,
|
|
193
|
+
"kind": "fixed",
|
|
194
|
+
"lineId": "il_1Udgyg6JR7kThJog3UoOkXqt",
|
|
195
|
+
"period": {
|
|
196
|
+
"end": 1797731460,
|
|
197
|
+
"start": 1795139460
|
|
198
|
+
},
|
|
199
|
+
"quantity": "1",
|
|
200
|
+
"stripePriceId": "price_1USSDA6JR7kThJoguUhyBEXl",
|
|
201
|
+
"stripeProductId": "prod_VTP1DX2R2js6f5",
|
|
202
|
+
"subscriptionItemId": "si_VTP18QFXyYFnDo"
|
|
203
|
+
}
|
|
204
|
+
],
|
|
205
|
+
"invoicePaymentId": "inpay_1USSEh6JR7kThJogqGqDt0l7",
|
|
206
|
+
"livemode": false,
|
|
207
|
+
"meterId": "mtr_test_61VbqAVIxs9O0sFgt416JR7kThJogO5w",
|
|
208
|
+
"model": "included_overage",
|
|
209
|
+
"period": {
|
|
210
|
+
"end": 1795139460,
|
|
211
|
+
"start": 1792461060
|
|
212
|
+
},
|
|
213
|
+
"stripeAccountId": "acct_1TEQzE6JR7kThJog",
|
|
214
|
+
"stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
|
|
215
|
+
"stripeProductId": "prod_VTP1DX2R2js6f5",
|
|
216
|
+
"subscriptionId": "sub_1USSDC6JR7kThJogK1m7V9Q2",
|
|
217
|
+
"subscriptionItemId": "si_VTP1jHuM4LSQWN"
|
|
218
|
+
},
|
|
219
|
+
"gross": 3500,
|
|
220
|
+
"currency": "usd",
|
|
221
|
+
"processingFee": 132,
|
|
222
|
+
"platformNet": 183,
|
|
223
|
+
"transfers": [
|
|
224
|
+
{
|
|
225
|
+
"amount": 3185,
|
|
226
|
+
"destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
|
|
227
|
+
"role": "store"
|
|
228
|
+
}
|
|
229
|
+
],
|
|
230
|
+
"status": "settled",
|
|
231
|
+
"executedTransfers": [
|
|
232
|
+
{
|
|
233
|
+
"stripeTransferId": "tr_3USSEg6JR7kThJog11S3kprM",
|
|
234
|
+
"destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
|
|
235
|
+
"role": "store",
|
|
236
|
+
"amount": 3185
|
|
237
|
+
}
|
|
238
|
+
]
|
|
239
|
+
},
|
|
240
|
+
"replay": "Second native settle returned the same original tr_3USSEg6JR7kThJog11S3kprM, amount3185, with no additional transfer.",
|
|
241
|
+
"automaticProductExample": {
|
|
242
|
+
"sourceInvoiceId": "in_1USC3M6JR7kThJog1yJkx0lS",
|
|
243
|
+
"stripeSubscriptionId": "sub_1USC3O6JR7kThJogep66wAiF",
|
|
244
|
+
"chargeId": "ch_3USC3N6JR7kThJog1kfdYxoa",
|
|
245
|
+
"paymentIntentId": "pi_3USC3N6JR7kThJog1dIMNxz8",
|
|
246
|
+
"gross": 2000,
|
|
247
|
+
"processingFee": 88,
|
|
248
|
+
"sellingFee": 180,
|
|
249
|
+
"platformNet": 92,
|
|
250
|
+
"sellerNet": 1820,
|
|
251
|
+
"costRecoveryAmount": 0,
|
|
252
|
+
"status": "settled",
|
|
253
|
+
"sellerTransferId": "tr_3USC3N6JR7kThJog1DrgShEg",
|
|
254
|
+
"stripeProductId": "prod_VQz7JDdU8Tr7GZ"
|
|
255
|
+
},
|
|
256
|
+
"partialRefund": {
|
|
257
|
+
"id": "re_3USSEg6JR7kThJog14TYHCy7",
|
|
258
|
+
"amount": 700,
|
|
259
|
+
"status": "succeeded"
|
|
260
|
+
},
|
|
261
|
+
"refundAudit": {
|
|
262
|
+
"invoiceId": "in_1USSEa6JR7kThJogK6C02ulM",
|
|
263
|
+
"paymentIntentId": "pi_3USSEg6JR7kThJog1beR1tZF",
|
|
264
|
+
"chargeId": "ch_3USSEg6JR7kThJog1TT4PblE",
|
|
265
|
+
"refunded": 700,
|
|
266
|
+
"transfersComplete": true,
|
|
267
|
+
"transfers": [
|
|
268
|
+
{
|
|
269
|
+
"id": "tr_3USSEg6JR7kThJog11S3kprM",
|
|
270
|
+
"amount": 3185,
|
|
271
|
+
"reversed": 637,
|
|
272
|
+
"sourceChargeId": "ch_3USSEg6JR7kThJog1TT4PblE"
|
|
273
|
+
}
|
|
274
|
+
],
|
|
275
|
+
"cost": {
|
|
276
|
+
"status": "ready",
|
|
277
|
+
"gross": 3500,
|
|
278
|
+
"fee": 132,
|
|
279
|
+
"refundAdjustment": 0,
|
|
280
|
+
"principalReturned": 700
|
|
281
|
+
}
|
|
282
|
+
},
|
|
283
|
+
"cleanup": "The isolated subscription is cancel_at_period_end=true; original financial evidence and test resources retained."
|
|
284
|
+
}
|
package/docs/metering-setup.md
CHANGED
|
@@ -115,8 +115,9 @@ configure the admin's own Store analytics reports product and verify that work i
|
|
|
115
115
|
held before a paid grant and denied after credit exhaustion.
|
|
116
116
|
|
|
117
117
|
Follow [the product walkthrough](usage-example.md) for exact steps, authorization,
|
|
118
|
-
payment verification, retained history and
|
|
119
|
-
|
|
118
|
+
payment verification, retained history and automatic mixed-invoice seller
|
|
119
|
+
settlement. Activate the seller's paid store plan and complete Stripe recipient onboarding
|
|
120
|
+
before accepting new customer payments. Product subscriptions use actual native billing periods and the
|
|
120
121
|
customer's original account; this flow does not advance shared test clocks.
|
|
121
122
|
|
|
122
123
|
For isolated clock-driven renewal, correction and cleanup checks, use Admin →
|
package/docs/usage-example.md
CHANGED
|
@@ -120,11 +120,30 @@ is retained and the native invoice preview remains available; the example does
|
|
|
120
120
|
not round a billing period and claim an exact reconciliation. Credit grants also keep their original
|
|
121
121
|
price and ownership terms.
|
|
122
122
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
123
|
+
Paid product invoices route automatically through the original managed Checkout,
|
|
124
|
+
enrollment and seller-owned product. The example settles the initial monthly fee
|
|
125
|
+
and later monthly-plus-overage invoices only after verifying complete native
|
|
126
|
+
lines, a single full captured payment and actual processing costs. The seller's product fee policy applies to the whole mixed invoice. Product enrollments
|
|
127
|
+
have no referral attribution; SDK hosts can authorize affiliates explicitly. Metadata
|
|
128
|
+
locates the managed intent; it never chooses the seller or payout amount.
|
|
129
|
+
|
|
130
|
+
New seller Checkout sessions use the same active paid-plan and Stripe recipient
|
|
131
|
+
readiness checks as the ordinary storefront. Unready stores are hidden from new
|
|
132
|
+
buyers; original enrollments remain readable. Completed Checkout reconciliation
|
|
133
|
+
and existing renewals preserve original purchased terms after a store lapses. The
|
|
134
|
+
enrollment pins that plan as a fallback for already-purchased terms; renewals use
|
|
135
|
+
the current seller tier or retained purchased tier, as ordinary store sales do.
|
|
136
|
+
The existing settlement workflow reserves owned recovery obligations, persists
|
|
137
|
+
complete original line provenance, and reauthorizes the seller and cash proof
|
|
138
|
+
before each new transfer. `invoice.paid`, `payment_intent.succeeded` and
|
|
139
|
+
`charge.updated` all route through original invoice funding. Pending fees retry;
|
|
140
|
+
replayed events retain the same allocation and transfer IDs. Issuer-owned services
|
|
141
|
+
retain their proceeds without creating a seller transfer.
|
|
142
|
+
|
|
143
|
+
Foreign products/items, incomplete funding, discounts/taxes/credits, prorations,
|
|
144
|
+
refunded/disputed new sales and unsupported recipient configurations remain held.
|
|
145
|
+
See [native usage settlement](usage-settlement.md) for the SDK contract and
|
|
146
|
+
[verification evidence](usage-verification.md) for actual test-mode economics.
|
|
128
147
|
|
|
129
148
|
## Package APIs and UI implementations
|
|
130
149
|
|
package/docs/usage-settlement.md
CHANGED
|
@@ -82,14 +82,52 @@ payments, unrelated priced invoice lines, proration, mismatched original periods
|
|
|
82
82
|
converted settlement currencies and automatic destination/on-behalf-of charges
|
|
83
83
|
are held through explicit non-ready outcomes. The method does not guess a
|
|
84
84
|
multi-product allocation or take over existing destination-charge fee handling.
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
85
|
+
For a mixed invoice, provide the original monthly item explicitly:
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
const mixedOriginal = {
|
|
89
|
+
...original,
|
|
90
|
+
fixedPrice: {
|
|
91
|
+
stripePriceId: originalMonthlyPriceId,
|
|
92
|
+
subscriptionItemId: originalMonthlyItemId,
|
|
93
|
+
unitAmount: 2000, // USD 20; quantity must be one
|
|
94
|
+
},
|
|
95
|
+
};
|
|
96
|
+
const source = await stripe.usage.getInvoiceSale(ctx, mixedOriginal, provider);
|
|
97
|
+
// Pass mixedOriginal to settleInvoice with the same server-authorized policy.
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
This supports one original product with one licensed monthly item and one metered
|
|
101
|
+
item. The initial invoice may contain only the monthly fee. Renewals may contain
|
|
102
|
+
that fee plus a metered line, or a zero included tier and a paid overage tier.
|
|
103
|
+
Every native line must match the pinned product, price and subscription item;
|
|
104
|
+
complete bounded pagination is mandatory. A USD 20 base plus USD 15 overage is
|
|
105
|
+
one USD 35 cash sale with one actual processing fee and one conserved allocation.
|
|
106
|
+
Fixed fees are billed in advance and usage in arrears, so each original native
|
|
107
|
+
line period is retained separately. No minute rounding or current-price lookup
|
|
108
|
+
is used to reconstruct historical periods. `invoiceLines` retains every line's
|
|
109
|
+
identity, amount, exact quantity and period in the immutable charge allocation.
|
|
110
|
+
|
|
111
|
+
Additional products/items, discounts, taxes, credits, negative adjustments,
|
|
112
|
+
prorations, partial or multiple funding, and automatic destination charges remain
|
|
113
|
+
held. Single-meter settlement without `fixedPrice` keeps its existing stricter
|
|
114
|
+
period and line rules. A ready read proves proceeds; it does not authorize a
|
|
115
|
+
recipient by itself.
|
|
116
|
+
|
|
117
|
+
Use `authorize` on `settleInvoice` to recheck original ownership and sealed
|
|
118
|
+
allocation after reads and immediately before each new transfer. Throw to hold a
|
|
119
|
+
changed seller or liability policy. For host-owned recovery workflows, the
|
|
120
|
+
optional `allocation` accepts the same conserved allocation as `settleSale`,
|
|
121
|
+
including `policyContext` and `adjustmentAmount`. The host owns commission
|
|
122
|
+
selection for that resolved allocation. Retain the complete `usageSource` when
|
|
123
|
+
passing it to a durable recovery workflow; do not reconstruct it from metadata.
|
|
124
|
+
Mixed-invoice processing-cost reconciliation checks the sealed original lines and
|
|
125
|
+
InvoicePayment again, so refunds/disputes cannot substitute a new funding receipt.
|
|
126
|
+
Mixed invoices with pre-payment or post-payment credit notes are held for both
|
|
127
|
+
new transfers and retained-source cost reconciliation, including credit notes
|
|
128
|
+
that issue customer-balance or out-of-band credit without refunding the charge.
|
|
129
|
+
Credit-note-backed refunds require separate native credit-note-to-refund proof;
|
|
130
|
+
this flow supports ordinary cash refunds and disputes without credit notes.
|
|
93
131
|
|
|
94
132
|
## Prepaid issuer-service revenue
|
|
95
133
|
|
|
@@ -165,3 +203,31 @@ provenance, fractional quantity, included tiers, zero-first-invoice commission,
|
|
|
165
203
|
transfer-success/persistence-failure, replay, prepaid purchase consumption and
|
|
166
204
|
refund guards. These tests are not a new native financial sandbox execution;
|
|
167
205
|
project-wide native acceptance is recorded separately.
|
|
206
|
+
|
|
207
|
+
## Verify mixed billing in development
|
|
208
|
+
|
|
209
|
+
Use the example's existing Stripe test key and a test seller with active transfer
|
|
210
|
+
capability. Run commands from `example/` against the intended development
|
|
211
|
+
Convex deployment. The internal `meteredProducts/mixedProof` fixture rejects live
|
|
212
|
+
keys and creates its own clock and Accounts v2 payer. Do not advance the shared
|
|
213
|
+
example customer's clock.
|
|
214
|
+
|
|
215
|
+
1. Call `meteredProducts/mixedProof:prepare` with a unique `runId` starting with
|
|
216
|
+
`mixed-proof-`, a minute-aligned UNIX `start` timestamp, and the test
|
|
217
|
+
`sellerAccountId`. Retain its returned JSON as `fixtureJson` for later calls.
|
|
218
|
+
2. Call `meteredProducts/mixedProof:run` with `fixtureJson` and `phase: "usage"`
|
|
219
|
+
to record 75 minutes, then `phase: "pay"` to pay the initial USD 20 invoice
|
|
220
|
+
with the fixture's synthetic test payment method. `phase: "settle"` verifies
|
|
221
|
+
actual processing costs and creates the original seller transfer.
|
|
222
|
+
3. Call `phase: "advance"` once. Inspect with `phase: "inspect"` until the
|
|
223
|
+
clock is ready and the renewal contains USD 20 base plus USD 15 overage.
|
|
224
|
+
Pass that original renewal `invoiceId` to `pay`, then `settle` twice.
|
|
225
|
+
Both settlement results must retain the same transfer ID.
|
|
226
|
+
4. `phase: "refund"` issues a USD 7 test refund on the selected invoice.
|
|
227
|
+
`phase: "audit"` reads complete native transfers and processing costs.
|
|
228
|
+
Verify proportional reversal against the original allocation, then call
|
|
229
|
+
`phase: "cancel"` to stop future renewals. Retain financial evidence.
|
|
230
|
+
|
|
231
|
+
These internal fixtures are developer verification tools. The product UI uses
|
|
232
|
+
original Checkout enrollments, with seller/customer authorization in the host.
|
|
233
|
+
The fixture does not substitute for testing the application's authentication.
|
|
@@ -88,8 +88,8 @@ comes from the product example, separately from the isolated protocol fixtures a
|
|
|
88
88
|
|
|
89
89
|
These are test-mode observations, not finalized renewal or seller-settlement
|
|
90
90
|
proof. Exact native meter summaries reject partial-minute subscription boundaries.
|
|
91
|
-
The draft invoices remain estimates.
|
|
92
|
-
|
|
91
|
+
The draft invoices remain estimates. That run preceded mixed-invoice settlement
|
|
92
|
+
support; the later mixed-invoice proof below verifies original paid cash and transfers. The earlier unsupported automatic-collection prepaid test enrollment was
|
|
93
93
|
retained and its renewal canceled; corrected enrollments use `send_invoice`.
|
|
94
94
|
|
|
95
95
|
The product regression suite covers store enablement, ownership, immutable
|
|
@@ -146,3 +146,23 @@ worker/DB failures, retained quota limits and API-version refusals use determini
|
|
|
146
146
|
SDK/component tests. No load or sustained throughput certification is claimed.
|
|
147
147
|
These checks authorize neither live billing nor automatic production migration,
|
|
148
148
|
publication or replay of unknown historical provider writes.
|
|
149
|
+
|
|
150
|
+
## Mixed monthly fee and usage settlement
|
|
151
|
+
|
|
152
|
+
The isolated 2026-10-20 native Stripe test uses a separate Accounts v2 payer and
|
|
153
|
+
minute-aligned test clock. It leaves the product example customer's clock intact.
|
|
154
|
+
[Retained native evidence](evidence/native-metering/mixed-settlement-2026-10-20.json)
|
|
155
|
+
records the original complete line periods, funding, actual fees and transfer IDs.
|
|
156
|
+
|
|
157
|
+
| Original invoice | Paid | Actual processing | Platform net | Seller transfer |
|
|
158
|
+
| ----------------------------------------------------------- | --------: | ----------------: | -----------: | --------------: |
|
|
159
|
+
| Initial monthly fee | USD 20.00 | USD 0.88 | USD 0.92 | USD 18.20 |
|
|
160
|
+
| Renewal: next monthly fee + 15 prior-period overage minutes | USD 35.00 | USD 1.32 | USD 1.83 | USD 31.85 |
|
|
161
|
+
|
|
162
|
+
The renewal contains three native lines: 60 included minutes at zero, 15 extra
|
|
163
|
+
minutes at USD 1, and the next USD 20 monthly fee. Replaying settlement returned
|
|
164
|
+
the same transfer ID. A native USD 7 partial refund reversed USD 6.37 of
|
|
165
|
+
the USD 31.85 seller transfer. The actual product example's initial USD 20 invoice
|
|
166
|
+
also settled through the billing hook and durable recovery workflow. SDK regressions also cover complete pagination, foreign
|
|
167
|
+
lines, taxes/credits/prorations, reauthorization, lost transfer receipts, sealed
|
|
168
|
+
funding identity and refund/dispute cost observations.
|
package/package.json
CHANGED
|
@@ -50,8 +50,13 @@ export async function resolveVerifiedPaymentSource(
|
|
|
50
50
|
stripe: Stripe,
|
|
51
51
|
input: VerifiedPaymentSourceOptions,
|
|
52
52
|
eligibility?: {
|
|
53
|
-
requirePayable:
|
|
53
|
+
requirePayable: boolean;
|
|
54
54
|
customerId: string;
|
|
55
|
+
/** Internal native-line verifier; never exposed as browser input. */
|
|
56
|
+
verifyInvoiceLines?: (
|
|
57
|
+
invoice: Stripe.Invoice,
|
|
58
|
+
lines: Stripe.InvoiceLineItem[],
|
|
59
|
+
) => { stripePriceId: string; stripeProductId: string } | null;
|
|
55
60
|
invoiceLine?: {
|
|
56
61
|
id: string;
|
|
57
62
|
zeroAmountLineIds?: string[];
|
|
@@ -132,12 +137,13 @@ export async function resolveVerifiedPaymentSource(
|
|
|
132
137
|
);
|
|
133
138
|
const customerAccountId = payment.customer_account!;
|
|
134
139
|
if (eligibility) {
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
charge.
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
140
|
+
if (eligibility.requirePayable)
|
|
141
|
+
requireSource(
|
|
142
|
+
charge.amount_refunded === 0 &&
|
|
143
|
+
charge.disputed === false &&
|
|
144
|
+
charge.refunded === false,
|
|
145
|
+
reject("payment_not_payable"),
|
|
146
|
+
);
|
|
141
147
|
requireSource(
|
|
142
148
|
objectId(payment.customer) === eligibility.customerId &&
|
|
143
149
|
objectId(charge.customer) === eligibility.customerId,
|
|
@@ -326,63 +332,78 @@ export async function resolveVerifiedPaymentSource(
|
|
|
326
332
|
),
|
|
327
333
|
);
|
|
328
334
|
if (lines.status !== "complete") return lines;
|
|
329
|
-
const
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
: lines.data[0];
|
|
333
|
-
requireSource(
|
|
334
|
-
line &&
|
|
335
|
-
(zeroIds.length
|
|
336
|
-
? zeroTierLinesMatch(lines.data, line, zeroIds)
|
|
337
|
-
: lines.data.length === 1),
|
|
338
|
-
reject("unsupported_source"),
|
|
339
|
-
);
|
|
340
|
-
if (!line) return reject("unsupported_source");
|
|
341
|
-
requireSource(
|
|
342
|
-
line.object === "line_item" &&
|
|
343
|
-
line.invoice === invoice.id &&
|
|
344
|
-
line.livemode === payment.livemode,
|
|
345
|
-
identity(),
|
|
335
|
+
const verifiedLines = eligibility?.verifyInvoiceLines?.(
|
|
336
|
+
invoice,
|
|
337
|
+
lines.data,
|
|
346
338
|
);
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
);
|
|
357
|
-
const parent = line.parent;
|
|
358
|
-
if (eligibility?.invoiceLine) {
|
|
359
|
-
const expected = eligibility.invoiceLine;
|
|
339
|
+
if (eligibility?.verifyInvoiceLines)
|
|
340
|
+
requireSource(verifiedLines, reject("unsupported_source"));
|
|
341
|
+
let priceId = verifiedLines?.stripePriceId;
|
|
342
|
+
let productId = verifiedLines?.stripeProductId;
|
|
343
|
+
if (!verifiedLines) {
|
|
344
|
+
const zeroIds = eligibility?.invoiceLine?.zeroAmountLineIds ?? [];
|
|
345
|
+
const line = zeroIds.length
|
|
346
|
+
? lines.data.find((row) => row.id === eligibility!.invoiceLine!.id)
|
|
347
|
+
: lines.data[0];
|
|
360
348
|
requireSource(
|
|
361
|
-
line
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
349
|
+
line &&
|
|
350
|
+
(zeroIds.length
|
|
351
|
+
? zeroTierLinesMatch(lines.data, line, zeroIds)
|
|
352
|
+
: lines.data.length === 1),
|
|
353
|
+
reject("unsupported_source"),
|
|
354
|
+
);
|
|
355
|
+
if (!line) return reject("unsupported_source");
|
|
356
|
+
requireSource(
|
|
357
|
+
line.object === "line_item" &&
|
|
358
|
+
line.invoice === invoice.id &&
|
|
359
|
+
line.livemode === payment.livemode,
|
|
366
360
|
identity(),
|
|
367
361
|
);
|
|
362
|
+
requireSource(
|
|
363
|
+
line.currency === opts.currency,
|
|
364
|
+
reject("currency_mismatch"),
|
|
365
|
+
);
|
|
366
|
+
requireSource(
|
|
367
|
+
integer(line.amount) &&
|
|
368
|
+
line.amount > 0 &&
|
|
369
|
+
(line.quantity_decimal != null
|
|
370
|
+
? /^\d{1,30}(\.\d{1,12})?$/.test(
|
|
371
|
+
line.quantity_decimal.toString(),
|
|
372
|
+
) && /[1-9]/.test(line.quantity_decimal.toString())
|
|
373
|
+
: Number.isSafeInteger(line.quantity) && line.quantity! > 0),
|
|
374
|
+
reject("unsupported_source"),
|
|
375
|
+
);
|
|
376
|
+
const parent = line.parent;
|
|
377
|
+
if (eligibility?.invoiceLine) {
|
|
378
|
+
const expected = eligibility.invoiceLine;
|
|
379
|
+
requireSource(
|
|
380
|
+
line.id === expected.id &&
|
|
381
|
+
line.parent?.subscription_item_details?.subscription_item ===
|
|
382
|
+
expected.subscriptionItemId &&
|
|
383
|
+
line.period.start === expected.period.start &&
|
|
384
|
+
line.period.end === expected.period.end,
|
|
385
|
+
identity(),
|
|
386
|
+
);
|
|
387
|
+
}
|
|
388
|
+
const lineSubscription =
|
|
389
|
+
parent?.subscription_item_details?.subscription ??
|
|
390
|
+
parent?.invoice_item_details?.subscription ??
|
|
391
|
+
undefined;
|
|
392
|
+
requireSource(lineSubscription === subscriptionId, identity());
|
|
393
|
+
requireSource(
|
|
394
|
+
!parent?.subscription_item_details?.proration &&
|
|
395
|
+
!parent?.invoice_item_details?.proration,
|
|
396
|
+
reject("unsupported_source"),
|
|
397
|
+
);
|
|
398
|
+
const price = line.pricing?.price_details;
|
|
399
|
+
priceId = objectId(price?.price);
|
|
400
|
+
productId = objectId(price?.product);
|
|
401
|
+
requireSource(
|
|
402
|
+
line.pricing?.type === "price_details" && priceId && productId,
|
|
403
|
+
reject("unsupported_source"),
|
|
404
|
+
);
|
|
368
405
|
}
|
|
369
|
-
|
|
370
|
-
parent?.subscription_item_details?.subscription ??
|
|
371
|
-
parent?.invoice_item_details?.subscription ??
|
|
372
|
-
undefined;
|
|
373
|
-
requireSource(lineSubscription === subscriptionId, identity());
|
|
374
|
-
requireSource(
|
|
375
|
-
!parent?.subscription_item_details?.proration &&
|
|
376
|
-
!parent?.invoice_item_details?.proration,
|
|
377
|
-
reject("unsupported_source"),
|
|
378
|
-
);
|
|
379
|
-
const price = line.pricing?.price_details;
|
|
380
|
-
const priceId = objectId(price?.price);
|
|
381
|
-
const productId = objectId(price?.product);
|
|
382
|
-
requireSource(
|
|
383
|
-
line.pricing?.type === "price_details" && priceId && productId,
|
|
384
|
-
reject("unsupported_source"),
|
|
385
|
-
);
|
|
406
|
+
requireSource(priceId && productId, reject("unsupported_source"));
|
|
386
407
|
return {
|
|
387
408
|
status: "ready",
|
|
388
409
|
value: {
|