@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.
Files changed (282) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +3 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +264 -8
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +132 -4
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +264 -8
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +132 -4
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +9 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/index.js +1 -0
  14. package/dist/client/index.js.map +1 -1
  15. package/dist/client/usage/catalogPrices.d.ts +2 -0
  16. package/dist/client/usage/catalogPrices.d.ts.map +1 -1
  17. package/dist/client/usage/catalogPrices.js +15 -0
  18. package/dist/client/usage/catalogPrices.js.map +1 -1
  19. package/dist/client/usage/client.d.ts +2 -2
  20. package/dist/client/usage/client.d.ts.map +1 -1
  21. package/dist/client/usage/client.js +2 -2
  22. package/dist/client/usage/client.js.map +1 -1
  23. package/dist/client/usage/deliveryProvider.d.ts.map +1 -1
  24. package/dist/client/usage/deliveryProvider.js +26 -1
  25. package/dist/client/usage/deliveryProvider.js.map +1 -1
  26. package/dist/client/usage/index.d.ts +9 -0
  27. package/dist/client/usage/index.d.ts.map +1 -1
  28. package/dist/client/usage/index.js +1 -0
  29. package/dist/client/usage/index.js.map +1 -1
  30. package/dist/client/usage/invoiceObservation.d.ts +38 -0
  31. package/dist/client/usage/invoiceObservation.d.ts.map +1 -0
  32. package/dist/client/usage/invoiceObservation.js +157 -0
  33. package/dist/client/usage/invoiceObservation.js.map +1 -0
  34. package/dist/client/usage/observationClient.d.ts +83 -0
  35. package/dist/client/usage/observationClient.d.ts.map +1 -0
  36. package/dist/client/usage/observationClient.js +157 -0
  37. package/dist/client/usage/observationClient.js.map +1 -0
  38. package/dist/client/usage/observationTypes.d.ts +63 -0
  39. package/dist/client/usage/observationTypes.d.ts.map +1 -0
  40. package/dist/client/usage/observationTypes.js +59 -0
  41. package/dist/client/usage/observationTypes.js.map +1 -0
  42. package/dist/client/usage/providerObservation.d.ts +4 -0
  43. package/dist/client/usage/providerObservation.d.ts.map +1 -0
  44. package/dist/client/usage/providerObservation.js +96 -0
  45. package/dist/client/usage/providerObservation.js.map +1 -0
  46. package/dist/client/usage/reconciliation.d.ts +12 -0
  47. package/dist/client/usage/reconciliation.d.ts.map +1 -0
  48. package/dist/client/usage/reconciliation.js +48 -0
  49. package/dist/client/usage/reconciliation.js.map +1 -0
  50. package/dist/client/usage/subscription.fixtures.d.ts +118 -0
  51. package/dist/client/usage/subscription.fixtures.d.ts.map +1 -0
  52. package/dist/client/usage/subscription.fixtures.js +84 -0
  53. package/dist/client/usage/subscription.fixtures.js.map +1 -0
  54. package/dist/client/usage/subscriptionAbandonment.d.ts +8 -0
  55. package/dist/client/usage/subscriptionAbandonment.d.ts.map +1 -0
  56. package/dist/client/usage/subscriptionAbandonment.js +82 -0
  57. package/dist/client/usage/subscriptionAbandonment.js.map +1 -0
  58. package/dist/client/usage/subscriptionCancellation.d.ts +9 -0
  59. package/dist/client/usage/subscriptionCancellation.d.ts.map +1 -0
  60. package/dist/client/usage/subscriptionCancellation.js +39 -0
  61. package/dist/client/usage/subscriptionCancellation.js.map +1 -0
  62. package/dist/client/usage/subscriptionCheckout.d.ts +52 -0
  63. package/dist/client/usage/subscriptionCheckout.d.ts.map +1 -0
  64. package/dist/client/usage/subscriptionCheckout.js +94 -0
  65. package/dist/client/usage/subscriptionCheckout.js.map +1 -0
  66. package/dist/client/usage/subscriptionClient.d.ts +267 -0
  67. package/dist/client/usage/subscriptionClient.d.ts.map +1 -0
  68. package/dist/client/usage/subscriptionClient.js +93 -0
  69. package/dist/client/usage/subscriptionClient.js.map +1 -0
  70. package/dist/client/usage/subscriptionErrors.d.ts +5 -0
  71. package/dist/client/usage/subscriptionErrors.d.ts.map +1 -0
  72. package/dist/client/usage/subscriptionErrors.js +9 -0
  73. package/dist/client/usage/subscriptionErrors.js.map +1 -0
  74. package/dist/client/usage/subscriptionInvoiceSchema.d.ts +203 -0
  75. package/dist/client/usage/subscriptionInvoiceSchema.d.ts.map +1 -0
  76. package/dist/client/usage/subscriptionInvoiceSchema.js +108 -0
  77. package/dist/client/usage/subscriptionInvoiceSchema.js.map +1 -0
  78. package/dist/client/usage/subscriptionLifecycle.d.ts +80 -0
  79. package/dist/client/usage/subscriptionLifecycle.d.ts.map +1 -0
  80. package/dist/client/usage/subscriptionLifecycle.js +87 -0
  81. package/dist/client/usage/subscriptionLifecycle.js.map +1 -0
  82. package/dist/client/usage/subscriptionProvider.d.ts +111 -0
  83. package/dist/client/usage/subscriptionProvider.d.ts.map +1 -0
  84. package/dist/client/usage/subscriptionProvider.js +147 -0
  85. package/dist/client/usage/subscriptionProvider.js.map +1 -0
  86. package/dist/client/usage/subscriptionTerms.d.ts +161 -0
  87. package/dist/client/usage/subscriptionTerms.d.ts.map +1 -0
  88. package/dist/client/usage/subscriptionTerms.js +242 -0
  89. package/dist/client/usage/subscriptionTerms.js.map +1 -0
  90. package/dist/client/usage/subscriptionTransport.fixtures.d.ts +25 -0
  91. package/dist/client/usage/subscriptionTransport.fixtures.d.ts.map +1 -0
  92. package/dist/client/usage/subscriptionTransport.fixtures.js +203 -0
  93. package/dist/client/usage/subscriptionTransport.fixtures.js.map +1 -0
  94. package/dist/client/usage/summary.d.ts +50 -0
  95. package/dist/client/usage/summary.d.ts.map +1 -0
  96. package/dist/client/usage/summary.js +110 -0
  97. package/dist/client/usage/summary.js.map +1 -0
  98. package/dist/client/webhooks/processors.d.ts.map +1 -1
  99. package/dist/client/webhooks/processors.js +2 -0
  100. package/dist/client/webhooks/processors.js.map +1 -1
  101. package/dist/client/webhooks/usageSubscriptions.d.ts +5 -0
  102. package/dist/client/webhooks/usageSubscriptions.d.ts.map +1 -0
  103. package/dist/client/webhooks/usageSubscriptions.js +54 -0
  104. package/dist/client/webhooks/usageSubscriptions.js.map +1 -0
  105. package/dist/component/_generated/api.d.ts +22 -0
  106. package/dist/component/_generated/api.d.ts.map +1 -1
  107. package/dist/component/_generated/api.js.map +1 -1
  108. package/dist/component/_generated/component.d.ts +255 -5
  109. package/dist/component/_generated/component.d.ts.map +1 -1
  110. package/dist/component/accountClosure/mutations.d.ts.map +1 -1
  111. package/dist/component/accountClosure/mutations.js +10 -0
  112. package/dist/component/accountClosure/mutations.js.map +1 -1
  113. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  114. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  115. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  116. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  117. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  118. package/dist/component/earnings/triggers.d.ts +296 -22
  119. package/dist/component/earnings/triggers.d.ts.map +1 -1
  120. package/dist/component/payoutRelease/queries.d.ts +2 -2
  121. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  122. package/dist/component/refundHistory/queries.d.ts +1 -1
  123. package/dist/component/schema.d.ts +132 -4
  124. package/dist/component/schema.js +8 -0
  125. package/dist/component/schema.js.map +1 -1
  126. package/dist/component/usage/mutations.d.ts.map +1 -1
  127. package/dist/component/usage/mutations.js +5 -0
  128. package/dist/component/usage/mutations.js.map +1 -1
  129. package/dist/component/usage/queries.d.ts +2 -0
  130. package/dist/component/usage/queries.d.ts.map +1 -1
  131. package/dist/component/usage/schema.d.ts +21 -9
  132. package/dist/component/usage/schema.d.ts.map +1 -1
  133. package/dist/component/usage/schema.js +5 -1
  134. package/dist/component/usage/schema.js.map +1 -1
  135. package/dist/component/usageDelivery/fields.d.ts +4 -2
  136. package/dist/component/usageDelivery/fields.d.ts.map +1 -1
  137. package/dist/component/usageDelivery/fields.js +3 -1
  138. package/dist/component/usageDelivery/fields.js.map +1 -1
  139. package/dist/component/usageDelivery/helpers.d.ts +5 -3
  140. package/dist/component/usageDelivery/helpers.d.ts.map +1 -1
  141. package/dist/component/usageDelivery/mutations.d.ts +3 -3
  142. package/dist/component/usageDelivery/mutations.d.ts.map +1 -1
  143. package/dist/component/usageDelivery/mutations.js +8 -1
  144. package/dist/component/usageDelivery/mutations.js.map +1 -1
  145. package/dist/component/usageDelivery/queries.d.ts +19 -3
  146. package/dist/component/usageDelivery/queries.d.ts.map +1 -1
  147. package/dist/component/usageDelivery/queries.js +20 -3
  148. package/dist/component/usageDelivery/queries.js.map +1 -1
  149. package/dist/component/usageDelivery/schema.d.ts +2 -2
  150. package/dist/component/usageDelivery/steps.d.ts +1 -1
  151. package/dist/component/usageDelivery/steps.d.ts.map +1 -1
  152. package/dist/component/usageDelivery/steps.js +20 -2
  153. package/dist/component/usageDelivery/steps.js.map +1 -1
  154. package/dist/component/usageObservations/helpers.d.ts +38 -0
  155. package/dist/component/usageObservations/helpers.d.ts.map +1 -0
  156. package/dist/component/usageObservations/helpers.js +80 -0
  157. package/dist/component/usageObservations/helpers.js.map +1 -0
  158. package/dist/component/usageObservations/history.d.ts +6 -0
  159. package/dist/component/usageObservations/history.d.ts.map +1 -0
  160. package/dist/component/usageObservations/history.js +29 -0
  161. package/dist/component/usageObservations/history.js.map +1 -0
  162. package/dist/component/usageObservations/mutations.d.ts +6 -0
  163. package/dist/component/usageObservations/mutations.d.ts.map +1 -0
  164. package/dist/component/usageObservations/mutations.js +39 -0
  165. package/dist/component/usageObservations/mutations.js.map +1 -0
  166. package/dist/component/usageObservations/queries.d.ts +78 -0
  167. package/dist/component/usageObservations/queries.d.ts.map +1 -0
  168. package/dist/component/usageObservations/queries.js +131 -0
  169. package/dist/component/usageObservations/queries.js.map +1 -0
  170. package/dist/component/usageObservations/schema.d.ts +72 -0
  171. package/dist/component/usageObservations/schema.d.ts.map +1 -0
  172. package/dist/component/usageObservations/schema.js +29 -0
  173. package/dist/component/usageObservations/schema.js.map +1 -0
  174. package/dist/component/usageSubscriptions/abandonment.d.ts +4 -0
  175. package/dist/component/usageSubscriptions/abandonment.d.ts.map +1 -0
  176. package/dist/component/usageSubscriptions/abandonment.js +59 -0
  177. package/dist/component/usageSubscriptions/abandonment.js.map +1 -0
  178. package/dist/component/usageSubscriptions/acceptance.d.ts +11 -0
  179. package/dist/component/usageSubscriptions/acceptance.d.ts.map +1 -0
  180. package/dist/component/usageSubscriptions/acceptance.js +38 -0
  181. package/dist/component/usageSubscriptions/acceptance.js.map +1 -0
  182. package/dist/component/usageSubscriptions/helpers.d.ts +39 -0
  183. package/dist/component/usageSubscriptions/helpers.d.ts.map +1 -0
  184. package/dist/component/usageSubscriptions/helpers.js +28 -0
  185. package/dist/component/usageSubscriptions/helpers.js.map +1 -0
  186. package/dist/component/usageSubscriptions/history.d.ts +46 -0
  187. package/dist/component/usageSubscriptions/history.d.ts.map +1 -0
  188. package/dist/component/usageSubscriptions/history.js +46 -0
  189. package/dist/component/usageSubscriptions/history.js.map +1 -0
  190. package/dist/component/usageSubscriptions/mutations.d.ts +64 -0
  191. package/dist/component/usageSubscriptions/mutations.d.ts.map +1 -0
  192. package/dist/component/usageSubscriptions/mutations.js +252 -0
  193. package/dist/component/usageSubscriptions/mutations.js.map +1 -0
  194. package/dist/component/usageSubscriptions/queries.d.ts +81 -0
  195. package/dist/component/usageSubscriptions/queries.d.ts.map +1 -0
  196. package/dist/component/usageSubscriptions/queries.js +70 -0
  197. package/dist/component/usageSubscriptions/queries.js.map +1 -0
  198. package/dist/component/usageSubscriptions/retirement.d.ts +4 -0
  199. package/dist/component/usageSubscriptions/retirement.d.ts.map +1 -0
  200. package/dist/component/usageSubscriptions/retirement.js +80 -0
  201. package/dist/component/usageSubscriptions/retirement.js.map +1 -0
  202. package/dist/component/usageSubscriptions/schema.d.ts +191 -0
  203. package/dist/component/usageSubscriptions/schema.d.ts.map +1 -0
  204. package/dist/component/usageSubscriptions/schema.js +69 -0
  205. package/dist/component/usageSubscriptions/schema.js.map +1 -0
  206. package/dist/test.d.ts +6 -0
  207. package/dist/test.d.ts.map +1 -0
  208. package/dist/test.js +15 -0
  209. package/dist/test.js.map +1 -0
  210. package/docs/README.md +4 -0
  211. package/docs/evidence/native-metering/clock-finalization-run.json +129 -0
  212. package/docs/evidence/native-metering/clock-lag-run.json +111 -0
  213. package/docs/evidence/native-metering/paid-run.json +107 -0
  214. package/docs/evidence/native-metering/promotional-run.json +103 -0
  215. package/docs/metered-usage.md +14 -0
  216. package/docs/metering-setup.md +7 -1
  217. package/docs/usage-observations.md +152 -0
  218. package/docs/usage-subscriptions.md +278 -0
  219. package/package.json +5 -2
  220. package/src/client/index.ts +26 -0
  221. package/src/client/usage/catalogPrices.ts +21 -0
  222. package/src/client/usage/client.ts +2 -2
  223. package/src/client/usage/deliveryProvider.test.ts +70 -1
  224. package/src/client/usage/deliveryProvider.ts +43 -2
  225. package/src/client/usage/index.ts +27 -0
  226. package/src/client/usage/invoiceObservation.test.ts +195 -0
  227. package/src/client/usage/invoiceObservation.ts +203 -0
  228. package/src/client/usage/observationClient.ts +233 -0
  229. package/src/client/usage/observationTypes.ts +101 -0
  230. package/src/client/usage/providerObservation.test.ts +207 -0
  231. package/src/client/usage/providerObservation.ts +124 -0
  232. package/src/client/usage/reconciliation.test.ts +117 -0
  233. package/src/client/usage/reconciliation.ts +86 -0
  234. package/src/client/usage/subscription.fixtures.ts +84 -0
  235. package/src/client/usage/subscriptionAbandonment.test.ts +124 -0
  236. package/src/client/usage/subscriptionAbandonment.ts +116 -0
  237. package/src/client/usage/subscriptionCancellation.ts +90 -0
  238. package/src/client/usage/subscriptionCheckout.test.ts +31 -0
  239. package/src/client/usage/subscriptionCheckout.ts +152 -0
  240. package/src/client/usage/subscriptionClient.test.ts +316 -0
  241. package/src/client/usage/subscriptionClient.ts +204 -0
  242. package/src/client/usage/subscriptionErrors.ts +14 -0
  243. package/src/client/usage/subscriptionInvoiceSchema.ts +116 -0
  244. package/src/client/usage/subscriptionLifecycle.ts +165 -0
  245. package/src/client/usage/subscriptionProvider.test.ts +48 -0
  246. package/src/client/usage/subscriptionProvider.ts +247 -0
  247. package/src/client/usage/subscriptionTerms.test.ts +158 -0
  248. package/src/client/usage/subscriptionTerms.ts +294 -0
  249. package/src/client/usage/subscriptionTransport.fixtures.ts +241 -0
  250. package/src/client/usage/summary.test.ts +222 -0
  251. package/src/client/usage/summary.ts +188 -0
  252. package/src/client/webhooks/processors.ts +2 -0
  253. package/src/client/webhooks/usageSubscriptions.test.ts +162 -0
  254. package/src/client/webhooks/usageSubscriptions.ts +81 -0
  255. package/src/component/_generated/api.ts +22 -0
  256. package/src/component/_generated/component.ts +335 -0
  257. package/src/component/accountClosure/mutations.ts +12 -0
  258. package/src/component/schema.ts +16 -0
  259. package/src/component/usage/mutations.ts +5 -0
  260. package/src/component/usage/schema.ts +5 -1
  261. package/src/component/usageDelivery/fields.ts +3 -0
  262. package/src/component/usageDelivery/mutations.ts +26 -1
  263. package/src/component/usageDelivery/queries.ts +30 -3
  264. package/src/component/usageDelivery/steps.ts +61 -2
  265. package/src/component/usageObservations/helpers.ts +95 -0
  266. package/src/component/usageObservations/history.test.ts +87 -0
  267. package/src/component/usageObservations/history.ts +39 -0
  268. package/src/component/usageObservations/mutations.ts +39 -0
  269. package/src/component/usageObservations/queries.test.ts +162 -0
  270. package/src/component/usageObservations/queries.ts +145 -0
  271. package/src/component/usageObservations/schema.ts +40 -0
  272. package/src/component/usageSubscriptions/abandonment.ts +80 -0
  273. package/src/component/usageSubscriptions/acceptance.test.ts +122 -0
  274. package/src/component/usageSubscriptions/acceptance.ts +66 -0
  275. package/src/component/usageSubscriptions/helpers.ts +33 -0
  276. package/src/component/usageSubscriptions/history.test.ts +69 -0
  277. package/src/component/usageSubscriptions/history.ts +68 -0
  278. package/src/component/usageSubscriptions/mutations.test.ts +205 -0
  279. package/src/component/usageSubscriptions/mutations.ts +275 -0
  280. package/src/component/usageSubscriptions/queries.ts +78 -0
  281. package/src/component/usageSubscriptions/retirement.ts +105 -0
  282. 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
+ }
@@ -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.
@@ -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) is available. Allowance/credit
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).