@fantastic.dev/better-stripe 0.54.0 → 0.56.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 +12 -0
- package/README.md +3 -1
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +264 -8
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +132 -4
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +264 -8
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +132 -4
- package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
- package/dist/client/index.d.ts +9 -0
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -0
- package/dist/client/index.js.map +1 -1
- package/dist/client/usage/catalogPrices.d.ts +2 -0
- package/dist/client/usage/catalogPrices.d.ts.map +1 -1
- package/dist/client/usage/catalogPrices.js +15 -0
- package/dist/client/usage/catalogPrices.js.map +1 -1
- package/dist/client/usage/client.d.ts +2 -2
- package/dist/client/usage/client.d.ts.map +1 -1
- package/dist/client/usage/client.js +2 -2
- package/dist/client/usage/client.js.map +1 -1
- package/dist/client/usage/deliveryProvider.d.ts.map +1 -1
- package/dist/client/usage/deliveryProvider.js +26 -1
- package/dist/client/usage/deliveryProvider.js.map +1 -1
- package/dist/client/usage/index.d.ts +9 -0
- package/dist/client/usage/index.d.ts.map +1 -1
- package/dist/client/usage/index.js +1 -0
- package/dist/client/usage/index.js.map +1 -1
- package/dist/client/usage/invoiceObservation.d.ts +38 -0
- package/dist/client/usage/invoiceObservation.d.ts.map +1 -0
- package/dist/client/usage/invoiceObservation.js +157 -0
- package/dist/client/usage/invoiceObservation.js.map +1 -0
- package/dist/client/usage/observationClient.d.ts +83 -0
- package/dist/client/usage/observationClient.d.ts.map +1 -0
- package/dist/client/usage/observationClient.js +157 -0
- package/dist/client/usage/observationClient.js.map +1 -0
- package/dist/client/usage/observationTypes.d.ts +63 -0
- package/dist/client/usage/observationTypes.d.ts.map +1 -0
- package/dist/client/usage/observationTypes.js +59 -0
- package/dist/client/usage/observationTypes.js.map +1 -0
- package/dist/client/usage/providerObservation.d.ts +4 -0
- package/dist/client/usage/providerObservation.d.ts.map +1 -0
- package/dist/client/usage/providerObservation.js +96 -0
- package/dist/client/usage/providerObservation.js.map +1 -0
- package/dist/client/usage/reconciliation.d.ts +12 -0
- package/dist/client/usage/reconciliation.d.ts.map +1 -0
- package/dist/client/usage/reconciliation.js +48 -0
- package/dist/client/usage/reconciliation.js.map +1 -0
- package/dist/client/usage/subscription.fixtures.d.ts +118 -0
- package/dist/client/usage/subscription.fixtures.d.ts.map +1 -0
- package/dist/client/usage/subscription.fixtures.js +84 -0
- package/dist/client/usage/subscription.fixtures.js.map +1 -0
- package/dist/client/usage/subscriptionAbandonment.d.ts +8 -0
- package/dist/client/usage/subscriptionAbandonment.d.ts.map +1 -0
- package/dist/client/usage/subscriptionAbandonment.js +82 -0
- package/dist/client/usage/subscriptionAbandonment.js.map +1 -0
- package/dist/client/usage/subscriptionCancellation.d.ts +9 -0
- package/dist/client/usage/subscriptionCancellation.d.ts.map +1 -0
- package/dist/client/usage/subscriptionCancellation.js +39 -0
- package/dist/client/usage/subscriptionCancellation.js.map +1 -0
- package/dist/client/usage/subscriptionCheckout.d.ts +52 -0
- package/dist/client/usage/subscriptionCheckout.d.ts.map +1 -0
- package/dist/client/usage/subscriptionCheckout.js +94 -0
- package/dist/client/usage/subscriptionCheckout.js.map +1 -0
- package/dist/client/usage/subscriptionClient.d.ts +267 -0
- package/dist/client/usage/subscriptionClient.d.ts.map +1 -0
- package/dist/client/usage/subscriptionClient.js +93 -0
- package/dist/client/usage/subscriptionClient.js.map +1 -0
- package/dist/client/usage/subscriptionErrors.d.ts +5 -0
- package/dist/client/usage/subscriptionErrors.d.ts.map +1 -0
- package/dist/client/usage/subscriptionErrors.js +9 -0
- package/dist/client/usage/subscriptionErrors.js.map +1 -0
- package/dist/client/usage/subscriptionInvoiceSchema.d.ts +203 -0
- package/dist/client/usage/subscriptionInvoiceSchema.d.ts.map +1 -0
- package/dist/client/usage/subscriptionInvoiceSchema.js +108 -0
- package/dist/client/usage/subscriptionInvoiceSchema.js.map +1 -0
- package/dist/client/usage/subscriptionLifecycle.d.ts +80 -0
- package/dist/client/usage/subscriptionLifecycle.d.ts.map +1 -0
- package/dist/client/usage/subscriptionLifecycle.js +87 -0
- package/dist/client/usage/subscriptionLifecycle.js.map +1 -0
- package/dist/client/usage/subscriptionProvider.d.ts +111 -0
- package/dist/client/usage/subscriptionProvider.d.ts.map +1 -0
- package/dist/client/usage/subscriptionProvider.js +147 -0
- package/dist/client/usage/subscriptionProvider.js.map +1 -0
- package/dist/client/usage/subscriptionTerms.d.ts +161 -0
- package/dist/client/usage/subscriptionTerms.d.ts.map +1 -0
- package/dist/client/usage/subscriptionTerms.js +242 -0
- package/dist/client/usage/subscriptionTerms.js.map +1 -0
- package/dist/client/usage/subscriptionTransport.fixtures.d.ts +25 -0
- package/dist/client/usage/subscriptionTransport.fixtures.d.ts.map +1 -0
- package/dist/client/usage/subscriptionTransport.fixtures.js +203 -0
- package/dist/client/usage/subscriptionTransport.fixtures.js.map +1 -0
- package/dist/client/usage/summary.d.ts +50 -0
- package/dist/client/usage/summary.d.ts.map +1 -0
- package/dist/client/usage/summary.js +110 -0
- package/dist/client/usage/summary.js.map +1 -0
- package/dist/client/webhooks/processors.d.ts.map +1 -1
- package/dist/client/webhooks/processors.js +2 -0
- package/dist/client/webhooks/processors.js.map +1 -1
- package/dist/client/webhooks/usageSubscriptions.d.ts +5 -0
- package/dist/client/webhooks/usageSubscriptions.d.ts.map +1 -0
- package/dist/client/webhooks/usageSubscriptions.js +54 -0
- package/dist/client/webhooks/usageSubscriptions.js.map +1 -0
- package/dist/component/_generated/api.d.ts +22 -0
- package/dist/component/_generated/api.d.ts.map +1 -1
- package/dist/component/_generated/api.js.map +1 -1
- package/dist/component/_generated/component.d.ts +255 -5
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/accountClosure/mutations.d.ts.map +1 -1
- package/dist/component/accountClosure/mutations.js +10 -0
- package/dist/component/accountClosure/mutations.js.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/stateHandlers.d.ts +8 -8
- package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
- package/dist/component/earnings/triggers.d.ts +296 -22
- package/dist/component/earnings/triggers.d.ts.map +1 -1
- package/dist/component/payoutRelease/queries.d.ts +2 -2
- package/dist/component/payoutRelease/queries.d.ts.map +1 -1
- package/dist/component/refundHistory/queries.d.ts +1 -1
- package/dist/component/schema.d.ts +132 -4
- package/dist/component/schema.js +8 -0
- package/dist/component/schema.js.map +1 -1
- package/dist/component/usage/mutations.d.ts.map +1 -1
- package/dist/component/usage/mutations.js +5 -0
- package/dist/component/usage/mutations.js.map +1 -1
- package/dist/component/usage/queries.d.ts +2 -0
- package/dist/component/usage/queries.d.ts.map +1 -1
- package/dist/component/usage/schema.d.ts +21 -9
- package/dist/component/usage/schema.d.ts.map +1 -1
- package/dist/component/usage/schema.js +5 -1
- package/dist/component/usage/schema.js.map +1 -1
- package/dist/component/usageDelivery/fields.d.ts +4 -2
- package/dist/component/usageDelivery/fields.d.ts.map +1 -1
- package/dist/component/usageDelivery/fields.js +3 -1
- package/dist/component/usageDelivery/fields.js.map +1 -1
- package/dist/component/usageDelivery/helpers.d.ts +5 -3
- package/dist/component/usageDelivery/helpers.d.ts.map +1 -1
- package/dist/component/usageDelivery/mutations.d.ts +3 -3
- package/dist/component/usageDelivery/mutations.d.ts.map +1 -1
- package/dist/component/usageDelivery/mutations.js +8 -1
- package/dist/component/usageDelivery/mutations.js.map +1 -1
- package/dist/component/usageDelivery/queries.d.ts +19 -3
- package/dist/component/usageDelivery/queries.d.ts.map +1 -1
- package/dist/component/usageDelivery/queries.js +20 -3
- package/dist/component/usageDelivery/queries.js.map +1 -1
- package/dist/component/usageDelivery/schema.d.ts +2 -2
- package/dist/component/usageDelivery/steps.d.ts +1 -1
- package/dist/component/usageDelivery/steps.d.ts.map +1 -1
- package/dist/component/usageDelivery/steps.js +20 -2
- package/dist/component/usageDelivery/steps.js.map +1 -1
- package/dist/component/usageObservations/helpers.d.ts +38 -0
- package/dist/component/usageObservations/helpers.d.ts.map +1 -0
- package/dist/component/usageObservations/helpers.js +80 -0
- package/dist/component/usageObservations/helpers.js.map +1 -0
- package/dist/component/usageObservations/history.d.ts +6 -0
- package/dist/component/usageObservations/history.d.ts.map +1 -0
- package/dist/component/usageObservations/history.js +29 -0
- package/dist/component/usageObservations/history.js.map +1 -0
- package/dist/component/usageObservations/mutations.d.ts +6 -0
- package/dist/component/usageObservations/mutations.d.ts.map +1 -0
- package/dist/component/usageObservations/mutations.js +39 -0
- package/dist/component/usageObservations/mutations.js.map +1 -0
- package/dist/component/usageObservations/queries.d.ts +78 -0
- package/dist/component/usageObservations/queries.d.ts.map +1 -0
- package/dist/component/usageObservations/queries.js +131 -0
- package/dist/component/usageObservations/queries.js.map +1 -0
- package/dist/component/usageObservations/schema.d.ts +72 -0
- package/dist/component/usageObservations/schema.d.ts.map +1 -0
- package/dist/component/usageObservations/schema.js +29 -0
- package/dist/component/usageObservations/schema.js.map +1 -0
- package/dist/component/usageSubscriptions/abandonment.d.ts +4 -0
- package/dist/component/usageSubscriptions/abandonment.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/abandonment.js +59 -0
- package/dist/component/usageSubscriptions/abandonment.js.map +1 -0
- package/dist/component/usageSubscriptions/acceptance.d.ts +11 -0
- package/dist/component/usageSubscriptions/acceptance.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/acceptance.js +38 -0
- package/dist/component/usageSubscriptions/acceptance.js.map +1 -0
- package/dist/component/usageSubscriptions/helpers.d.ts +39 -0
- package/dist/component/usageSubscriptions/helpers.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/helpers.js +28 -0
- package/dist/component/usageSubscriptions/helpers.js.map +1 -0
- package/dist/component/usageSubscriptions/history.d.ts +46 -0
- package/dist/component/usageSubscriptions/history.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/history.js +46 -0
- package/dist/component/usageSubscriptions/history.js.map +1 -0
- package/dist/component/usageSubscriptions/mutations.d.ts +64 -0
- package/dist/component/usageSubscriptions/mutations.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/mutations.js +252 -0
- package/dist/component/usageSubscriptions/mutations.js.map +1 -0
- package/dist/component/usageSubscriptions/queries.d.ts +81 -0
- package/dist/component/usageSubscriptions/queries.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/queries.js +70 -0
- package/dist/component/usageSubscriptions/queries.js.map +1 -0
- package/dist/component/usageSubscriptions/retirement.d.ts +4 -0
- package/dist/component/usageSubscriptions/retirement.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/retirement.js +80 -0
- package/dist/component/usageSubscriptions/retirement.js.map +1 -0
- package/dist/component/usageSubscriptions/schema.d.ts +191 -0
- package/dist/component/usageSubscriptions/schema.d.ts.map +1 -0
- package/dist/component/usageSubscriptions/schema.js +69 -0
- package/dist/component/usageSubscriptions/schema.js.map +1 -0
- package/dist/test.d.ts +6 -0
- package/dist/test.d.ts.map +1 -0
- package/dist/test.js +15 -0
- package/dist/test.js.map +1 -0
- package/docs/README.md +4 -0
- package/docs/evidence/native-metering/clock-finalization-run.json +129 -0
- package/docs/evidence/native-metering/clock-lag-run.json +111 -0
- package/docs/evidence/native-metering/paid-run.json +107 -0
- package/docs/evidence/native-metering/promotional-run.json +103 -0
- package/docs/metered-usage.md +14 -0
- package/docs/metering-setup.md +7 -1
- package/docs/usage-observations.md +152 -0
- package/docs/usage-subscriptions.md +278 -0
- package/package.json +5 -2
- package/src/client/index.ts +26 -0
- package/src/client/usage/catalogPrices.ts +21 -0
- package/src/client/usage/client.ts +2 -2
- package/src/client/usage/deliveryProvider.test.ts +70 -1
- package/src/client/usage/deliveryProvider.ts +43 -2
- package/src/client/usage/index.ts +27 -0
- package/src/client/usage/invoiceObservation.test.ts +195 -0
- package/src/client/usage/invoiceObservation.ts +203 -0
- package/src/client/usage/observationClient.ts +233 -0
- package/src/client/usage/observationTypes.ts +101 -0
- package/src/client/usage/providerObservation.test.ts +207 -0
- package/src/client/usage/providerObservation.ts +124 -0
- package/src/client/usage/reconciliation.test.ts +117 -0
- package/src/client/usage/reconciliation.ts +86 -0
- package/src/client/usage/subscription.fixtures.ts +84 -0
- package/src/client/usage/subscriptionAbandonment.test.ts +124 -0
- package/src/client/usage/subscriptionAbandonment.ts +116 -0
- package/src/client/usage/subscriptionCancellation.ts +90 -0
- package/src/client/usage/subscriptionCheckout.test.ts +31 -0
- package/src/client/usage/subscriptionCheckout.ts +152 -0
- package/src/client/usage/subscriptionClient.test.ts +316 -0
- package/src/client/usage/subscriptionClient.ts +204 -0
- package/src/client/usage/subscriptionErrors.ts +14 -0
- package/src/client/usage/subscriptionInvoiceSchema.ts +116 -0
- package/src/client/usage/subscriptionLifecycle.ts +165 -0
- package/src/client/usage/subscriptionProvider.test.ts +48 -0
- package/src/client/usage/subscriptionProvider.ts +247 -0
- package/src/client/usage/subscriptionTerms.test.ts +158 -0
- package/src/client/usage/subscriptionTerms.ts +294 -0
- package/src/client/usage/subscriptionTransport.fixtures.ts +241 -0
- package/src/client/usage/summary.test.ts +222 -0
- package/src/client/usage/summary.ts +188 -0
- package/src/client/webhooks/processors.ts +2 -0
- package/src/client/webhooks/usageSubscriptions.test.ts +162 -0
- package/src/client/webhooks/usageSubscriptions.ts +81 -0
- package/src/component/_generated/api.ts +22 -0
- package/src/component/_generated/component.ts +335 -0
- package/src/component/accountClosure/mutations.ts +12 -0
- package/src/component/schema.ts +16 -0
- package/src/component/usage/mutations.ts +5 -0
- package/src/component/usage/schema.ts +5 -1
- package/src/component/usageDelivery/fields.ts +3 -0
- package/src/component/usageDelivery/mutations.ts +26 -1
- package/src/component/usageDelivery/queries.ts +30 -3
- package/src/component/usageDelivery/steps.ts +61 -2
- package/src/component/usageObservations/helpers.ts +95 -0
- package/src/component/usageObservations/history.test.ts +87 -0
- package/src/component/usageObservations/history.ts +39 -0
- package/src/component/usageObservations/mutations.ts +39 -0
- package/src/component/usageObservations/queries.test.ts +162 -0
- package/src/component/usageObservations/queries.ts +145 -0
- package/src/component/usageObservations/schema.ts +40 -0
- package/src/component/usageSubscriptions/abandonment.ts +80 -0
- package/src/component/usageSubscriptions/acceptance.test.ts +122 -0
- package/src/component/usageSubscriptions/acceptance.ts +66 -0
- package/src/component/usageSubscriptions/helpers.ts +33 -0
- package/src/component/usageSubscriptions/history.test.ts +69 -0
- package/src/component/usageSubscriptions/history.ts +68 -0
- package/src/component/usageSubscriptions/mutations.test.ts +205 -0
- package/src/component/usageSubscriptions/mutations.ts +275 -0
- package/src/component/usageSubscriptions/queries.ts +78 -0
- package/src/component/usageSubscriptions/retirement.ts +105 -0
- package/src/component/usageSubscriptions/schema.ts +73 -0
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
{
|
|
2
|
+
"apiVersion": "2026-09-30.endive",
|
|
3
|
+
"observedAt": "2026-10-18T03:29:41.330Z",
|
|
4
|
+
"models": [
|
|
5
|
+
{
|
|
6
|
+
"model": "pay_as_you_go",
|
|
7
|
+
"catalogCreated": true,
|
|
8
|
+
"eventAccepted": true,
|
|
9
|
+
"aggregatedQuantity": 15,
|
|
10
|
+
"aggregationVerified": true,
|
|
11
|
+
"duplicateRetryVerified": true,
|
|
12
|
+
"invoiceIdentityVerified": true,
|
|
13
|
+
"previewTotal": 30,
|
|
14
|
+
"currency": "usd",
|
|
15
|
+
"paymentVerified": false,
|
|
16
|
+
"creditPurchaseVerified": false,
|
|
17
|
+
"invoiceFinalizationVerified": false
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"model": "included_overage",
|
|
21
|
+
"catalogCreated": true,
|
|
22
|
+
"eventAccepted": true,
|
|
23
|
+
"aggregatedQuantity": 0,
|
|
24
|
+
"aggregationVerified": false,
|
|
25
|
+
"duplicateRetryVerified": false,
|
|
26
|
+
"invoiceIdentityVerified": true,
|
|
27
|
+
"previewTotal": 0,
|
|
28
|
+
"currency": "usd",
|
|
29
|
+
"paymentVerified": false,
|
|
30
|
+
"creditPurchaseVerified": false,
|
|
31
|
+
"invoiceFinalizationVerified": false
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"model": "prepaid",
|
|
35
|
+
"catalogCreated": true,
|
|
36
|
+
"eventAccepted": true,
|
|
37
|
+
"aggregatedQuantity": 15,
|
|
38
|
+
"aggregationVerified": true,
|
|
39
|
+
"duplicateRetryVerified": true,
|
|
40
|
+
"invoiceIdentityVerified": true,
|
|
41
|
+
"previewTotal": 0,
|
|
42
|
+
"currency": "usd",
|
|
43
|
+
"paymentVerified": true,
|
|
44
|
+
"creditPurchaseVerified": true,
|
|
45
|
+
"invoiceFinalizationVerified": false
|
|
46
|
+
}
|
|
47
|
+
],
|
|
48
|
+
"cleanup": [
|
|
49
|
+
{
|
|
50
|
+
"kind": "credit",
|
|
51
|
+
"success": true
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"kind": "test-payment-refund",
|
|
55
|
+
"success": true
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"kind": "subscription",
|
|
59
|
+
"success": true
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"kind": "price",
|
|
63
|
+
"success": true
|
|
64
|
+
},
|
|
65
|
+
{
|
|
66
|
+
"kind": "product",
|
|
67
|
+
"success": true
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"kind": "meter",
|
|
71
|
+
"success": true
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
"kind": "subscription",
|
|
75
|
+
"success": true
|
|
76
|
+
},
|
|
77
|
+
{
|
|
78
|
+
"kind": "price",
|
|
79
|
+
"success": true
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
"kind": "product",
|
|
83
|
+
"success": true
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
"kind": "meter",
|
|
87
|
+
"success": true
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
"kind": "subscription",
|
|
91
|
+
"success": true
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
"kind": "price",
|
|
95
|
+
"success": true
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"kind": "product",
|
|
99
|
+
"success": true
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
"kind": "meter",
|
|
103
|
+
"success": true
|
|
104
|
+
}
|
|
105
|
+
],
|
|
106
|
+
"payerMappingVerified": true
|
|
107
|
+
}
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
{
|
|
2
|
+
"apiVersion": "2026-09-30.endive",
|
|
3
|
+
"observedAt": "2026-10-18T03:20:46.727Z",
|
|
4
|
+
"models": [
|
|
5
|
+
{
|
|
6
|
+
"model": "pay_as_you_go",
|
|
7
|
+
"catalogCreated": true,
|
|
8
|
+
"eventAccepted": true,
|
|
9
|
+
"aggregatedQuantity": 15,
|
|
10
|
+
"aggregationVerified": true,
|
|
11
|
+
"duplicateRetryVerified": true,
|
|
12
|
+
"invoiceIdentityVerified": true,
|
|
13
|
+
"previewTotal": 30,
|
|
14
|
+
"currency": "usd",
|
|
15
|
+
"paymentVerified": false,
|
|
16
|
+
"creditPurchaseVerified": false,
|
|
17
|
+
"invoiceFinalizationVerified": false
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"model": "included_overage",
|
|
21
|
+
"catalogCreated": true,
|
|
22
|
+
"eventAccepted": true,
|
|
23
|
+
"aggregatedQuantity": 15,
|
|
24
|
+
"aggregationVerified": true,
|
|
25
|
+
"duplicateRetryVerified": true,
|
|
26
|
+
"invoiceIdentityVerified": true,
|
|
27
|
+
"previewTotal": 10,
|
|
28
|
+
"currency": "usd",
|
|
29
|
+
"paymentVerified": false,
|
|
30
|
+
"creditPurchaseVerified": false,
|
|
31
|
+
"invoiceFinalizationVerified": false
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"model": "prepaid",
|
|
35
|
+
"catalogCreated": true,
|
|
36
|
+
"eventAccepted": true,
|
|
37
|
+
"aggregatedQuantity": 15,
|
|
38
|
+
"aggregationVerified": true,
|
|
39
|
+
"duplicateRetryVerified": true,
|
|
40
|
+
"invoiceIdentityVerified": true,
|
|
41
|
+
"previewTotal": 0,
|
|
42
|
+
"currency": "usd",
|
|
43
|
+
"paymentVerified": false,
|
|
44
|
+
"creditPurchaseVerified": false,
|
|
45
|
+
"invoiceFinalizationVerified": false
|
|
46
|
+
}
|
|
47
|
+
],
|
|
48
|
+
"cleanup": [
|
|
49
|
+
{
|
|
50
|
+
"kind": "credit",
|
|
51
|
+
"success": true
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"kind": "subscription",
|
|
55
|
+
"success": true
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"kind": "price",
|
|
59
|
+
"success": true
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"kind": "product",
|
|
63
|
+
"success": true
|
|
64
|
+
},
|
|
65
|
+
{
|
|
66
|
+
"kind": "meter",
|
|
67
|
+
"success": true
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"kind": "subscription",
|
|
71
|
+
"success": true
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
"kind": "price",
|
|
75
|
+
"success": true
|
|
76
|
+
},
|
|
77
|
+
{
|
|
78
|
+
"kind": "product",
|
|
79
|
+
"success": true
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
"kind": "meter",
|
|
83
|
+
"success": true
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
"kind": "subscription",
|
|
87
|
+
"success": true
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
"kind": "price",
|
|
91
|
+
"success": true
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
"kind": "product",
|
|
95
|
+
"success": true
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"kind": "meter",
|
|
99
|
+
"success": true
|
|
100
|
+
}
|
|
101
|
+
],
|
|
102
|
+
"payerMappingVerified": true
|
|
103
|
+
}
|
package/docs/metered-usage.md
CHANGED
|
@@ -373,3 +373,17 @@ than overwriting its original delivery or invoice receipt. A requested or
|
|
|
373
373
|
provider-accepted correction must not release spendable credits until confirmed.
|
|
374
374
|
|
|
375
375
|
The [packed consumer fixture](https://github.com/FantasticDevHQ/better-stripe/blob/main/scripts/fixtures/usage-consumer.ts) compiles concrete authorization and activity callbacks plus record/read/reconcile adapters for all three models against the actual package tarball. It returns alternative model paths and never submits one activity to multiple models.
|
|
376
|
+
|
|
377
|
+
## Native lifecycle verification, 2026-10-18
|
|
378
|
+
|
|
379
|
+
The [managed subscription guide](usage-subscriptions.md) now covers native
|
|
380
|
+
metered/mixed subscriptions, Checkout, closeout and retained lifecycle history.
|
|
381
|
+
The [test-clock run](evidence/native-metering/clock-finalization-run.json) verified
|
|
382
|
+
Accounts v2 payer mapping, all three 15-unit aggregates and finalized invoice
|
|
383
|
+
totals of 30/10/0 USD cents for pay-as-you-go/included-overage/prepaid. The prepaid
|
|
384
|
+
purchase was a separate verified 100-cent test payment. All 15 cleanup requests
|
|
385
|
+
succeeded, including grant expiry, the test refund request and clock deletion.
|
|
386
|
+
The [prior lag run](evidence/native-metering/clock-lag-run.json) remains visible;
|
|
387
|
+
it stopped before advancement while prepaid aggregation was pending. These
|
|
388
|
+
results supplement the earlier investigation table. They do not prove production
|
|
389
|
+
billing, non-Connect modes, strict credit accounting or seller settlement.
|
package/docs/metering-setup.md
CHANGED
|
@@ -7,7 +7,9 @@ native Stripe integration into the existing BetterStripe Convex component.
|
|
|
7
7
|
|
|
8
8
|
Current status: shared configuration/quantity helpers and repository sandbox probes
|
|
9
9
|
are implemented. Atomic recording and bounded local history are available through the
|
|
10
|
-
[usage ledger](usage-ledger.md). [Durable provider delivery](usage-delivery.md)
|
|
10
|
+
[usage ledger](usage-ledger.md). [Durable provider delivery](usage-delivery.md),
|
|
11
|
+
[scoped observations](usage-observations.md) and [managed metered subscriptions](usage-subscriptions.md)
|
|
12
|
+
are available. Allowance/credit
|
|
11
13
|
accounting and the three example UI flows are still under development. The probes
|
|
12
14
|
below verify provider behavior directly; they are not public BetterStripe billing
|
|
13
15
|
workflows. See [metered usage contracts and evidence](metered-usage.md).
|
|
@@ -184,3 +186,7 @@ Primary references:
|
|
|
184
186
|
- [Metronome quickstart](https://docs.metronome.com/guides/get-started/api-quickstart)
|
|
185
187
|
|
|
186
188
|
Use the [native catalog guide](usage-catalog.md) to provision versioned meters and prices through BetterStripe.
|
|
189
|
+
|
|
190
|
+
Use the [usage observation guide](usage-observations.md) for bounded local reads, native aggregate refreshes and honest invoice/credit availability.
|
|
191
|
+
|
|
192
|
+
For managed package enrollment, mixed fixed/metered items, Checkout, period-end cancellation and test-clock invoice verification, follow [usage subscriptions](usage-subscriptions.md).
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# Read and reconcile usage
|
|
2
|
+
|
|
3
|
+
BetterStripe keeps local acceptance, transport acceptance, native aggregates,
|
|
4
|
+
estimates and invoices separate. Start with [setup](metering-setup.md), the
|
|
5
|
+
[catalog](usage-catalog.md), [ledger](usage-ledger.md) and
|
|
6
|
+
[delivery](usage-delivery.md). Authenticate and authorize the exact Stripe realm,
|
|
7
|
+
payer and meter before every read, page or reconciliation call. Resolve the
|
|
8
|
+
original binding and subscription snapshot on the server.
|
|
9
|
+
|
|
10
|
+
## Local summaries and history
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
const local = await stripe.usage.getSummary(ctx, {
|
|
14
|
+
scope: verifiedScope,
|
|
15
|
+
period: { start, end }, // Unix seconds, half-open.
|
|
16
|
+
maxRecords: 100,
|
|
17
|
+
});
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The indexed summary reads at most `maxRecords + 1` immutable records, with a
|
|
21
|
+
budget of 1–500 and a default of 100. `complete: false` means the result is only a
|
|
22
|
+
bounded prefix. It never presents that prefix as a complete bill or silently
|
|
23
|
+
assumes missing history is zero. Use the ledger's paginated `read` to export a
|
|
24
|
+
larger period. An empty complete local result means no local events were found;
|
|
25
|
+
it says nothing about native Stripe usage.
|
|
26
|
+
|
|
27
|
+
Groups retain the original plan, version, unit, currency, customer, price and
|
|
28
|
+
subscription item/period. Quantities and decimal minor currency amounts are
|
|
29
|
+
strings. There is no combined money total across currencies or plan versions.
|
|
30
|
+
Each group distinguishes locally accepted quantities, transport-accepted
|
|
31
|
+
quantities and quantities by current delivery state. Validation-error counts
|
|
32
|
+
count events with observed errors, not a complete inventory of provider errors.
|
|
33
|
+
|
|
34
|
+
Pay-as-you-go estimates apply the original exact rate. Included-unit projections
|
|
35
|
+
require a complete original billing period and apply that period's allowance
|
|
36
|
+
before the overage rate. Partial periods, overlapping native subscription
|
|
37
|
+
items and multiple original bindings within an overlapping period return
|
|
38
|
+
unavailable estimates. A plan or price change on the same item does not reset
|
|
39
|
+
the local allowance. Estimates exclude taxes, discounts, fixed
|
|
40
|
+
fees, rounding and other invoice lines. They are not finalized amounts or limits
|
|
41
|
+
that authorize work. Strict allowance reservations are implemented separately.
|
|
42
|
+
Prepaid balance/estimate fields remain explicitly unavailable until the prepaid
|
|
43
|
+
accounting APIs are configured. They never infer available credits from usage.
|
|
44
|
+
|
|
45
|
+
`read(ctx, {scope, page: {period, limit, cursor}})` returns immutable event history
|
|
46
|
+
with current delivery state. For an event's delivery audit:
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
const attempts = await stripe.usage.readDeliveryHistory(ctx, {
|
|
50
|
+
scope: verifiedScope,
|
|
51
|
+
eventId,
|
|
52
|
+
limit: 20,
|
|
53
|
+
cursor: null,
|
|
54
|
+
});
|
|
55
|
+
const errors = await stripe.usage.readValidationHistory(ctx, {
|
|
56
|
+
scope: verifiedScope,
|
|
57
|
+
eventId,
|
|
58
|
+
limit: 20,
|
|
59
|
+
cursor: null,
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Both return `records`, `cursor` and `isDone`. Page sizes are 1–100; continue until
|
|
64
|
+
`isDone`, including an empty final page when required. Delivery history appends
|
|
65
|
+
started attempts, outcomes and operational holds/resumes independently of the
|
|
66
|
+
Workflow journal. Idempotent receipt projection does not duplicate audit entries.
|
|
67
|
+
`legacyHistoryMissing` identifies events whose earlier attempts predate this
|
|
68
|
+
history implementation. History is not reconstructed from guesses. Validation
|
|
69
|
+
history contains only provider samples that were actually observed. Correction
|
|
70
|
+
history is a typed unsupported state until the correction workflow is installed.
|
|
71
|
+
|
|
72
|
+
## Native aggregates and cached freshness
|
|
73
|
+
|
|
74
|
+
Construct one server-owned observation request using the original binding and
|
|
75
|
+
subscription snapshot:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
const request = {
|
|
79
|
+
scope: verifiedScope,
|
|
80
|
+
binding: originalBinding,
|
|
81
|
+
subscription: originalSubscription,
|
|
82
|
+
period: { start, end },
|
|
83
|
+
limit: 100,
|
|
84
|
+
cursor: null,
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
// In an authorized action, with the secret resolved at execution time.
|
|
88
|
+
const result = await stripe.usage.reconcile(ctx, request, {
|
|
89
|
+
stripeSecretKey: process.env.STRIPE_SECRET_KEY,
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
// In an authorized reactive query, without a Stripe key or network call.
|
|
93
|
+
const cached = await stripe.usage.getReconciliation(ctx, {
|
|
94
|
+
...request,
|
|
95
|
+
maxAgeSeconds: 60,
|
|
96
|
+
maxRecords: 100,
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`observeProviderUsage` refreshes only the native observation.
|
|
101
|
+
`getProviderUsage` reads only its scoped cache. One refresh makes a bounded native
|
|
102
|
+
page request, with a maximum page size of 100 and zero SDK retries. There is no
|
|
103
|
+
automatic polling loop. Use explicit, bounded refreshes, normally at least a
|
|
104
|
+
minute apart, and keep transient failures visible. Cache identity includes the
|
|
105
|
+
original scope, binding, subscription, exact period and page request. Older
|
|
106
|
+
in-flight refreshes cannot replace a newer projection.
|
|
107
|
+
|
|
108
|
+
Stripe requires minute-aligned aggregate start/end times. The adapter returns
|
|
109
|
+
`unsupported` for unaligned periods and never rounds a billing period to hide
|
|
110
|
+
that difference. An empty native response is `aggregation_pending`, not zero.
|
|
111
|
+
An explicit native zero remains a zero observation with aggregation lag possible.
|
|
112
|
+
Missing pages, overlapping buckets or incomplete period coverage cannot establish
|
|
113
|
+
a complete total. Unsafe integer or fractional provider values are reported as
|
|
114
|
+
unsupported precision because this adapter submits scaled integer units. It never
|
|
115
|
+
rounds a provider number to fit the local quantity contract.
|
|
116
|
+
|
|
117
|
+
Cached available data carries `observedAt` and `stale`. The default freshness
|
|
118
|
+
limit is 60 seconds; hosts may choose 1–86,400 seconds. Fresh transport responses
|
|
119
|
+
can still contain lagging Stripe aggregates. `aggregationLagPossible` stays true.
|
|
120
|
+
Native customer/meter reads require the key's own verified account and mode and
|
|
121
|
+
the original Accounts v2 payer/subscription mapping. Foreign key/context modes
|
|
122
|
+
return typed unsupported or unavailable results.
|
|
123
|
+
|
|
124
|
+
Reconciliation returns independent `local`, `aggregate`, `comparison` and invoice/
|
|
125
|
+
correction availability. `observed_match` means only that complete, fresh observed
|
|
126
|
+
transport quantities equal the observed aggregate for that exact period. It does
|
|
127
|
+
not prove invoice inclusion or payment. Incomplete local history, stale/incomplete
|
|
128
|
+
provider data, unresolved sends and ambiguous terms prevent comparison. A
|
|
129
|
+
mismatch can reflect aggregation lag, external usage or validation errors.
|
|
130
|
+
Reconciliation never resends, cancels, reroutes or reprices billable usage.
|
|
131
|
+
|
|
132
|
+
## Invoice observations
|
|
133
|
+
|
|
134
|
+
From an authorized action, use `readInvoiceUsage(ctx, request, providerOptions)`
|
|
135
|
+
for a native preview. Add `invoiceId` to request a specific existing invoice.
|
|
136
|
+
This verifies its realm/mode, Accounts v2 payer, native customer and subscription.
|
|
137
|
+
The result distinguishes whole-invoice amounts from matching metered lines,
|
|
138
|
+
preserves full decimal quantities and nullable tiered unit amounts, and reports
|
|
139
|
+
whether the native line page is complete. Missing or ambiguous lines do not become
|
|
140
|
+
a zero meter amount. Native line periods are preserved with Stripe's semantics.
|
|
141
|
+
|
|
142
|
+
Previews remain previews. Only an existing invoice with native finalization
|
|
143
|
+
evidence is marked finalized. `paymentEvidence: "not_resolved"` applies even to a
|
|
144
|
+
paid invoice: credits or out-of-band marking can pay an invoice without new cash.
|
|
145
|
+
Use the separate payment-provenance and settlement APIs before distributing money.
|
|
146
|
+
These readers never finalize, charge, refund or settle an invoice. The generic
|
|
147
|
+
reconciliation result leaves invoices unavailable until explicitly observed.
|
|
148
|
+
|
|
149
|
+
Authoritative references: [native aggregate period and pagination rules](https://docs.stripe.com/api/billing/meter-event-summary/list),
|
|
150
|
+
[asynchronous aggregation and invoice cutoffs](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api),
|
|
151
|
+
[invoice previews](https://docs.stripe.com/api/invoices/create_preview), and
|
|
152
|
+
[full-precision invoice line quantities](https://docs.stripe.com/api/invoice-line-item/object).
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
# Metered subscriptions and invoice lifecycle
|
|
2
|
+
|
|
3
|
+
Use [native setup](metering-setup.md) and the [catalog APIs](usage-catalog.md)
|
|
4
|
+
first. `stripe.usage` provides managed subscriptions for pay-as-you-go, monthly
|
|
5
|
+
included usage with overages, and prepaid usage. Each uses the original native
|
|
6
|
+
meter/price binding. Purchased prepaid grants and strict allowance reservations
|
|
7
|
+
are separate accounting APIs. Creating a subscription does not fund credits or
|
|
8
|
+
authorize consumption.
|
|
9
|
+
|
|
10
|
+
## Create a metered or mixed subscription
|
|
11
|
+
|
|
12
|
+
Authenticate the caller and authorize the entire realm, Accounts v2 payer and
|
|
13
|
+
every meter on the server. Resolve `meters` from server-owned catalog bindings.
|
|
14
|
+
Do not accept a browser-supplied payer, price, plan, quantity or arbitrary JSON
|
|
15
|
+
for a component mutation. The native key must own the requested realm and mode.
|
|
16
|
+
The component verifies the Accounts v2 payer's native customer mapping.
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
const signup = {
|
|
20
|
+
requestId: activity.subscriptionSignupId, // Stable across retries.
|
|
21
|
+
meters: [{ scope: verifiedScope, binding: originalBinding }],
|
|
22
|
+
fixedPriceIds: [], // Optional monthly licensed prices, e.g. a base fee.
|
|
23
|
+
collection: { method: "send_invoice" as const, daysUntilDue: 30 },
|
|
24
|
+
};
|
|
25
|
+
const current = await stripe.usage.ensureSubscription(ctx, signup, {
|
|
26
|
+
stripeSecretKey: process.env.STRIPE_SECRET_KEY,
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
For automatic collection, use
|
|
31
|
+
`{method: "charge_automatically", defaultPaymentMethod: attachedPaymentMethodId}`.
|
|
32
|
+
The payment method must belong to the authorized payer. Initial payment can be
|
|
33
|
+
incomplete; an incomplete subscription is not permission to deliver work.
|
|
34
|
+
|
|
35
|
+
A request supports 1–10 unique meters and up to 10 fixed prices, in one currency,
|
|
36
|
+
realm, mode and payer mapping. All items use monthly prices. Managed creation
|
|
37
|
+
uses native flexible billing. Metered items omit `quantity`; fixed items use one.
|
|
38
|
+
Tiered rates remain nullable in native item observations. Display the original
|
|
39
|
+
plan's exact rate and unit rather than treating a nullable native rate as zero.
|
|
40
|
+
Fixed fees, taxes and other invoice lines are separate from metered line amounts.
|
|
41
|
+
|
|
42
|
+
The component persists immutable signup terms and atomically locks each native
|
|
43
|
+
customer/meter before creation. Changed terms under the same request ID conflict.
|
|
44
|
+
Concurrent payer aliases cannot reserve that native customer/meter twice. Native
|
|
45
|
+
subscription discovery is bounded to ten pages of 100. Active overlapping meter
|
|
46
|
+
subscriptions, incomplete item pages and ambiguous identities block creation.
|
|
47
|
+
Use managed enrollment for every writer in that realm. Component locks cannot
|
|
48
|
+
serialize independent Dashboard/API writers or unrelated external Checkout
|
|
49
|
+
sessions; preflight checks detect existing native overlaps, and hosts must
|
|
50
|
+
prevent concurrent external enrollment.
|
|
51
|
+
|
|
52
|
+
A stable Stripe idempotency key and retained native ID survive component write
|
|
53
|
+
failures. An absent pinned object never triggers recreation. Recovery can discover
|
|
54
|
+
a matching original subscription; an unresolved create is held after 23 hours
|
|
55
|
+
instead of sending a new billable request after Stripe's idempotency window.
|
|
56
|
+
Keep the original request ID and resolve that outcome before starting another.
|
|
57
|
+
Provider errors contain fixed messages and typed `UsageSubscriptionError.code`
|
|
58
|
+
values, without raw Stripe response bodies or credentials.
|
|
59
|
+
|
|
60
|
+
## Checkout
|
|
61
|
+
|
|
62
|
+
Use the same original bindings with a Checkout collection policy:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
const session = await stripe.usage.ensureCheckout(
|
|
66
|
+
ctx,
|
|
67
|
+
{
|
|
68
|
+
...signup,
|
|
69
|
+
collection: {
|
|
70
|
+
method: "checkout",
|
|
71
|
+
successUrl: "https://your-app.example/billing/success",
|
|
72
|
+
cancelUrl: "https://your-app.example/billing",
|
|
73
|
+
},
|
|
74
|
+
},
|
|
75
|
+
{ stripeSecretKey: process.env.STRIPE_SECRET_KEY },
|
|
76
|
+
);
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Redirect to the returned `url` only while its status is `open`. Open, completed
|
|
80
|
+
and expired sessions retain their original identity. An expired signup is not
|
|
81
|
+
silently replaced. A completed session exposes its verified subscription after
|
|
82
|
+
native retrieval. The redirect is not payment or enrollment evidence; use the
|
|
83
|
+
subscription and invoice observations. Pending signup locks stay held until the native outcome is reconciled,
|
|
84
|
+
preventing another concurrent signup. For a verified expired session with no
|
|
85
|
+
subscription, PaymentIntent or SetupIntent and no payment received, call
|
|
86
|
+
`abandonSignup(ctx, ref, providerOptions)`. The same API supports a verified
|
|
87
|
+
`incomplete_expired` subscription only when its original initial invoice is void
|
|
88
|
+
and unpaid, with no recorded usage or pending reservations. It retains the
|
|
89
|
+
original terms and closure evidence, then permits a new request ID. Unknown
|
|
90
|
+
creates, incomplete payments and unresolved financial references stay held.
|
|
91
|
+
|
|
92
|
+
## Read current terms and retained history
|
|
93
|
+
|
|
94
|
+
The subscription reference has no single meter because a subscription can contain
|
|
95
|
+
several:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
const ref = {
|
|
99
|
+
scope: {
|
|
100
|
+
stripeAccountId: verifiedScope.stripeAccountId,
|
|
101
|
+
customerAccount: verifiedScope.customerAccount,
|
|
102
|
+
livemode: verifiedScope.livemode,
|
|
103
|
+
},
|
|
104
|
+
requestId: signup.requestId,
|
|
105
|
+
};
|
|
106
|
+
const cached = await stripe.usage.getSubscription(ctx, ref); // Reactive query.
|
|
107
|
+
const refreshed = await stripe.usage.observeSubscription(ctx, ref, {
|
|
108
|
+
stripeSecretKey: process.env.STRIPE_SECRET_KEY,
|
|
109
|
+
});
|
|
110
|
+
const history = await stripe.usage.readSubscriptionHistory(ctx, {
|
|
111
|
+
...ref,
|
|
112
|
+
kind: "subscription",
|
|
113
|
+
limit: 20,
|
|
114
|
+
cursor: null,
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The managed mirror includes every item, original source binding and actual
|
|
119
|
+
collection policy. Native collection method, invoice due days and configured
|
|
120
|
+
automatic payment method must match the original agreement. Delivery verifies
|
|
121
|
+
that policy again immediately before sending. Each metered binding contains its own native subscription/item/price
|
|
122
|
+
and half-open Unix-second period. Renewals produce a new snapshot; prior periods
|
|
123
|
+
remain immutable. Refresh before authorizing current work. Cached observation
|
|
124
|
+
times are not a guarantee of current native state. Historical prices are never
|
|
125
|
+
replaced by current prices. Changed or incomplete native items return an error
|
|
126
|
+
until their provenance is resolved.
|
|
127
|
+
|
|
128
|
+
History supports `subscription`, `invoice` and `retirement`, bounded pages of
|
|
129
|
+
1–100 and `isDone`/`cursor`. Continue until done, including an empty final page
|
|
130
|
+
when necessary. Duplicate snapshots deduplicate; older in-flight observations
|
|
131
|
+
cannot replace a newer current projection. Each enrollment retains at most
|
|
132
|
+
100,000 immutable history observations. Exhaustion blocks new writes and requires
|
|
133
|
+
an explicit archival/migration plan; financial evidence is never automatically
|
|
134
|
+
deleted. Existing fixed-price APIs remain compatible and retain their existing
|
|
135
|
+
read contracts. Use these managed readers for the full metered item list.
|
|
136
|
+
|
|
137
|
+
Managed subscription and invoice webhooks re-read native state before projection.
|
|
138
|
+
They retain the `bsUsageIntent` marker created by the package. Preserve that
|
|
139
|
+
metadata and the configured webhook routes. Older signed payloads cannot directly
|
|
140
|
+
rewind managed state. Native lookup failures leave the webhook retryable with a
|
|
141
|
+
fixed redacted error. Hosts may also refresh explicitly after downtime.
|
|
142
|
+
|
|
143
|
+
## Closeout, cancellation and model changes
|
|
144
|
+
|
|
145
|
+
Managed v1 closes new acceptance and new delivery attempts 60 seconds before the
|
|
146
|
+
original period ends. This is an operational buffer, not proof of invoice
|
|
147
|
+
inclusion. New acceptance requires the original active managed binding; receipt
|
|
148
|
+
replays still return the original record after closeout. New usage is rejected
|
|
149
|
+
when the native period/binding is closed or has changed. Queue work for the next
|
|
150
|
+
verified service period before it runs; do not move completed activity's original
|
|
151
|
+
timestamp, source ID or pricing to make it billable again.
|
|
152
|
+
|
|
153
|
+
Delivery rechecks the cutoff after preflight and reserves transport time before
|
|
154
|
+
sending. Queued usage that reaches closeout becomes held with
|
|
155
|
+
`billing_period_closed`. In-flight responses remain recorded, including unknown
|
|
156
|
+
outcomes. Inspect [delivery history](usage-delivery.md), native aggregates and
|
|
157
|
+
invoices; resolve held/unknown/rejected usage through the correction workflow.
|
|
158
|
+
Neither a clock advance nor an API receipt proves ingestion or invoicing.
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
await stripe.usage.setCancelAtPeriodEnd(
|
|
162
|
+
ctx,
|
|
163
|
+
{
|
|
164
|
+
...ref,
|
|
165
|
+
operationId: cancellationCommandId,
|
|
166
|
+
cancelAtPeriodEnd: true,
|
|
167
|
+
},
|
|
168
|
+
providerOptions,
|
|
169
|
+
);
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Use a new command ID with `cancelAtPeriodEnd: false` to undo scheduled cancellation
|
|
173
|
+
before Stripe cancels the subscription. Commands serialize per enrollment, reject
|
|
174
|
+
changed retries, retain unknown outcomes, and stop blind writes after 23 hours.
|
|
175
|
+
A replay returns the original command result; refresh separately for current
|
|
176
|
+
state. A canceled native subscription cannot be reactivated.
|
|
177
|
+
|
|
178
|
+
There is no managed immediate-delete, mid-cycle price swap, automatic proration,
|
|
179
|
+
credit conversion or account-closure shortcut. Native mid-cycle changes can omit
|
|
180
|
+
old or late usage, including in flexible billing. Use period-end cancellation,
|
|
181
|
+
drain delivery and resolve reservations, then observe the final period invoice.
|
|
182
|
+
Account closure preparation checks indexed enrollment locks for both the payer
|
|
183
|
+
and the billing realm, including retries. Signup checks pending and completed
|
|
184
|
+
closures before reserving enrollment. Both checks run in their respective
|
|
185
|
+
transactions, so concurrent closure and signup cannot both proceed. Retirement
|
|
186
|
+
or verified abandonment releases the locks.
|
|
187
|
+
|
|
188
|
+
An account closure must follow the same closeout process before deactivating its
|
|
189
|
+
customer configuration or credentials. External changes are detected on refresh;
|
|
190
|
+
they never rewrite retained events. Generic subscription APIs still require host
|
|
191
|
+
policy for lifecycle operations. Account closure uses the enrollment guard above.
|
|
192
|
+
|
|
193
|
+
After native cancellation, a finalized cycle invoice covering the closed period,
|
|
194
|
+
and no pending local sends, validation errors, reservations or cancellation
|
|
195
|
+
commands, retire the enrollment:
|
|
196
|
+
|
|
197
|
+
```ts
|
|
198
|
+
await stripe.usage.retireSubscription(
|
|
199
|
+
ctx,
|
|
200
|
+
{ ...ref, invoiceId: finalInvoiceId },
|
|
201
|
+
providerOptions,
|
|
202
|
+
);
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
This releases its enrollment locks so a new request ID can configure a new model
|
|
206
|
+
or price. Original events, invoices, purchases and credits remain associated with
|
|
207
|
+
their original terms. Retirement does not establish payment or exact invoice
|
|
208
|
+
reconciliation; its result explicitly retains `billingReconciliation: "required"`.
|
|
209
|
+
No historical activity is copied or rebilled. Unused credits do not become credit
|
|
210
|
+
on a new price or currency. Resolve their original expiry/refund policy separately.
|
|
211
|
+
|
|
212
|
+
## Invoice evidence and late usage
|
|
213
|
+
|
|
214
|
+
`observeSubscriptionInvoice(ctx, {...ref, invoiceId}, providerOptions)` verifies
|
|
215
|
+
native realm/mode, payer, subscription and original metered item references,
|
|
216
|
+
then retains a bounded observation for each configured meter. Historical line
|
|
217
|
+
periods and prices remain native evidence. Missing/incomplete lines stay
|
|
218
|
+
unavailable, never an inferred zero. Whole-invoice totals include fixed lines;
|
|
219
|
+
matching meter amounts remain separate. Use `readInvoiceUsage` for previews as
|
|
220
|
+
described in [usage observations](usage-observations.md). Managed history retains
|
|
221
|
+
existing invoice observations, including finalized and paid status.
|
|
222
|
+
|
|
223
|
+
A paid invoice can be covered by credits or marked paid out of band. Its
|
|
224
|
+
`paymentEvidence` stays `not_resolved`. Prepaid application must not create a new
|
|
225
|
+
usage payment or seller settlement. Verify actual payment provenance separately
|
|
226
|
+
before distributing money. These managed readers do not finalize, charge, refund
|
|
227
|
+
or settle invoices.
|
|
228
|
+
|
|
229
|
+
Stripe accepts eligible meter events within its ingestion window, but late
|
|
230
|
+
acceptance does not guarantee invoice inclusion. Configure and verify the native
|
|
231
|
+
invoice finalization grace period for your delivery latency. Only applicable
|
|
232
|
+
cycle/phase-transition invoices collect grace-period usage. Threshold and initial
|
|
233
|
+
invoices have earlier cutoffs, and mid-cycle price changes have additional late
|
|
234
|
+
usage limitations. Do not resend accepted usage under a new ID to fix an invoice.
|
|
235
|
+
|
|
236
|
+
## Verify native test-clock behavior
|
|
237
|
+
|
|
238
|
+
From the repository root, using the test-only secret reference configured in
|
|
239
|
+
[setup](metering-setup.md):
|
|
240
|
+
|
|
241
|
+
```sh
|
|
242
|
+
op run --env-file=.env.metering -- node scripts/metering-sandbox.mjs \
|
|
243
|
+
--verify-test-payment --finalize-test-invoices
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
This test-only probe attaches a test clock when first configuring the Accounts v2
|
|
247
|
+
customer, creates all three metered subscriptions, and confirms the 15-unit native
|
|
248
|
+
aggregates before advancing a billing period. It waits for clock readiness,
|
|
249
|
+
retrieves period-end invoices and explicitly finalizes a matching draft when
|
|
250
|
+
needed. It reports native totals and identity/finalization checks separately from
|
|
251
|
+
payment evidence. Expected totals are 30 USD cents for pay-as-you-go, 10 cents for
|
|
252
|
+
included overages and zero for credit-covered prepaid consumption. The prepaid
|
|
253
|
+
purchase is a separate 100-cent test payment. Synthetic usage uses the clock's
|
|
254
|
+
frozen timestamp. A bounded final re-read handles delayed aggregates before any
|
|
255
|
+
billing-clock advancement. Cleanup expires the grant, requests
|
|
256
|
+
its test refund, cancels subscriptions, archives catalog resources and deletes the
|
|
257
|
+
clock. Inspect every cleanup result.
|
|
258
|
+
|
|
259
|
+
This probe does not prove production clock behavior, application settlement or
|
|
260
|
+
strict credit reservation accounting. It creates synthetic sandbox resources and
|
|
261
|
+
rejects live keys before requests. Clock advancement is not evidence that meter
|
|
262
|
+
ingestion has completed. Keep the sanitized output as reviewer evidence and
|
|
263
|
+
report lag or unsupported account modes explicitly.
|
|
264
|
+
|
|
265
|
+
The [successful sandbox run](evidence/native-metering/clock-finalization-run.json)
|
|
266
|
+
confirmed all three 15-unit aggregates, final totals of 30/10/0 USD cents, the
|
|
267
|
+
separate paid prepaid purchase and all 15 cleanup requests. The
|
|
268
|
+
[earlier bounded lag run](evidence/native-metering/clock-lag-run.json) confirmed
|
|
269
|
+
only the first two aggregates and stopped before clock advancement. Both are
|
|
270
|
+
retained so missing data cannot be mistaken for a zero charge or successful
|
|
271
|
+
finalization.
|
|
272
|
+
|
|
273
|
+
Primary references: [native usage cutoff rules](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api),
|
|
274
|
+
[finalization grace periods](https://docs.stripe.com/billing/subscriptions/usage-based/configure-grace-period),
|
|
275
|
+
[flexible/classic changes and cancellation](https://docs.stripe.com/billing/subscriptions/usage-based/manage-billing-setup),
|
|
276
|
+
and [Accounts v2 test clocks](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage),
|
|
277
|
+
[expired Checkout sessions](https://docs.stripe.com/api/checkout/sessions/expire),
|
|
278
|
+
and [initial payment expiry](https://docs.stripe.com/billing/subscriptions/overview).
|