fluentcart-developer 3.0.0 → 3.0.1

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 (609) hide show
  1. package/LICENSE.md +26 -26
  2. package/README.md +59 -59
  3. package/dist/cards/fluentcart/templates-native.js +1087 -1087
  4. package/dist/cards/fluentcart/tools.js +2309 -2309
  5. package/dist/skills/fluentcart-developer/SKILL.md +108 -108
  6. package/dist/skills/fluentcart-developer/examples/README.md +30 -30
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +113 -113
  10. package/dist/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +148 -148
  11. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  12. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/README.md +22 -22
  13. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/sample-plugin-with-licensing-sdk.php +79 -79
  14. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/FluentLicensing.php +303 -303
  15. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/LicenseSettings.php +566 -566
  16. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/PluginUpdater.php +304 -304
  17. package/dist/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +61 -61
  18. package/dist/skills/fluentcart-developer/references/api/authentication.md +452 -452
  19. package/dist/skills/fluentcart-developer/references/api/coupons.md +786 -786
  20. package/dist/skills/fluentcart-developer/references/api/customers.md +889 -889
  21. package/dist/skills/fluentcart-developer/references/api/files.md +609 -609
  22. package/dist/skills/fluentcart-developer/references/api/index.md +432 -432
  23. package/dist/skills/fluentcart-developer/references/api/licensing.md +633 -633
  24. package/dist/skills/fluentcart-developer/references/api/order-bump.md +384 -384
  25. package/dist/skills/fluentcart-developer/references/api/orders.md +814 -814
  26. package/dist/skills/fluentcart-developer/references/api/products.md +866 -866
  27. package/dist/skills/fluentcart-developer/references/api/roles-permissions.md +536 -536
  28. package/dist/skills/fluentcart-developer/references/api/subscriptions.md +827 -827
  29. package/dist/skills/fluentcart-developer/references/database/index.md +44 -44
  30. package/dist/skills/fluentcart-developer/references/database/models/activity.md +178 -178
  31. package/dist/skills/fluentcart-developer/references/database/models/applied-coupon.md +291 -291
  32. package/dist/skills/fluentcart-developer/references/database/models/attribute-group.md +239 -239
  33. package/dist/skills/fluentcart-developer/references/database/models/attribute-relation.md +181 -181
  34. package/dist/skills/fluentcart-developer/references/database/models/attribute-term.md +219 -219
  35. package/dist/skills/fluentcart-developer/references/database/models/cart.md +645 -645
  36. package/dist/skills/fluentcart-developer/references/database/models/coupon.md +427 -427
  37. package/dist/skills/fluentcart-developer/references/database/models/customer-addresses.md +348 -348
  38. package/dist/skills/fluentcart-developer/references/database/models/customer-meta.md +156 -156
  39. package/dist/skills/fluentcart-developer/references/database/models/customer.md +584 -584
  40. package/dist/skills/fluentcart-developer/references/database/models/dynamic-model.md +163 -163
  41. package/dist/skills/fluentcart-developer/references/database/models/label-relationship.md +155 -155
  42. package/dist/skills/fluentcart-developer/references/database/models/label.md +153 -153
  43. package/dist/skills/fluentcart-developer/references/database/models/license-activation.md +182 -182
  44. package/dist/skills/fluentcart-developer/references/database/models/license-meta.md +163 -163
  45. package/dist/skills/fluentcart-developer/references/database/models/license-site.md +208 -208
  46. package/dist/skills/fluentcart-developer/references/database/models/license.md +640 -640
  47. package/dist/skills/fluentcart-developer/references/database/models/meta.md +233 -233
  48. package/dist/skills/fluentcart-developer/references/database/models/order-address.md +391 -391
  49. package/dist/skills/fluentcart-developer/references/database/models/order-download-permission.md +144 -144
  50. package/dist/skills/fluentcart-developer/references/database/models/order-item.md +383 -383
  51. package/dist/skills/fluentcart-developer/references/database/models/order-meta.md +303 -303
  52. package/dist/skills/fluentcart-developer/references/database/models/order-operation.md +158 -158
  53. package/dist/skills/fluentcart-developer/references/database/models/order-promotion-stat.md +175 -175
  54. package/dist/skills/fluentcart-developer/references/database/models/order-promotion.md +250 -250
  55. package/dist/skills/fluentcart-developer/references/database/models/order-tax-rate.md +172 -172
  56. package/dist/skills/fluentcart-developer/references/database/models/order-transaction.md +440 -440
  57. package/dist/skills/fluentcart-developer/references/database/models/order.md +727 -727
  58. package/dist/skills/fluentcart-developer/references/database/models/product-detail.md +397 -397
  59. package/dist/skills/fluentcart-developer/references/database/models/product-download.md +258 -258
  60. package/dist/skills/fluentcart-developer/references/database/models/product-meta.md +153 -153
  61. package/dist/skills/fluentcart-developer/references/database/models/product-variation.md +556 -556
  62. package/dist/skills/fluentcart-developer/references/database/models/product.md +580 -580
  63. package/dist/skills/fluentcart-developer/references/database/models/relationships.md +427 -427
  64. package/dist/skills/fluentcart-developer/references/database/models/scheduled-action.md +175 -175
  65. package/dist/skills/fluentcart-developer/references/database/models/shipping-class.md +148 -148
  66. package/dist/skills/fluentcart-developer/references/database/models/shipping-method.md +280 -280
  67. package/dist/skills/fluentcart-developer/references/database/models/shipping-zone.md +205 -205
  68. package/dist/skills/fluentcart-developer/references/database/models/subscription-meta.md +173 -173
  69. package/dist/skills/fluentcart-developer/references/database/models/subscription.md +528 -528
  70. package/dist/skills/fluentcart-developer/references/database/models/tax-class.md +195 -195
  71. package/dist/skills/fluentcart-developer/references/database/models/tax-rate.md +225 -225
  72. package/dist/skills/fluentcart-developer/references/database/models/user-meta.md +166 -166
  73. package/dist/skills/fluentcart-developer/references/database/models/user.md +220 -220
  74. package/dist/skills/fluentcart-developer/references/database/models.md +404 -404
  75. package/dist/skills/fluentcart-developer/references/database/query-builder.md +860 -860
  76. package/dist/skills/fluentcart-developer/references/database/readme.md +276 -276
  77. package/dist/skills/fluentcart-developer/references/database/schema.md +1002 -1002
  78. package/dist/skills/fluentcart-developer/references/engineering/adding-custom-pages-to-the-customer-dashboard.md +395 -395
  79. package/dist/skills/fluentcart-developer/references/engineering/index.md +4 -4
  80. package/dist/skills/fluentcart-developer/references/engineering.md +4 -4
  81. package/dist/skills/fluentcart-developer/references/getting-started.md +249 -249
  82. package/dist/skills/fluentcart-developer/references/guides/frontend.md +519 -519
  83. package/dist/skills/fluentcart-developer/references/guides/index.md +107 -107
  84. package/dist/skills/fluentcart-developer/references/guides/integrations.md +600 -600
  85. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/index.md +237 -237
  86. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/labels-and-tracking.md +481 -481
  87. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/live-rates.md +269 -269
  88. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/reference.md +223 -223
  89. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/settings.md +370 -370
  90. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier.md +237 -237
  91. package/dist/skills/fluentcart-developer/references/guides/subscriptions.md +217 -217
  92. package/dist/skills/fluentcart-developer/references/hooks/actions/admin-and-templates.md +1079 -1079
  93. package/dist/skills/fluentcart-developer/references/hooks/actions/cart-and-checkout.md +1795 -1795
  94. package/dist/skills/fluentcart-developer/references/hooks/actions/customers-and-users.md +327 -327
  95. package/dist/skills/fluentcart-developer/references/hooks/actions/licenses.md +829 -829
  96. package/dist/skills/fluentcart-developer/references/hooks/actions/modules.md +81 -81
  97. package/dist/skills/fluentcart-developer/references/hooks/actions/orders.md +757 -757
  98. package/dist/skills/fluentcart-developer/references/hooks/actions/payments-and-integrations.md +1163 -1163
  99. package/dist/skills/fluentcart-developer/references/hooks/actions/pro-modules.md +219 -219
  100. package/dist/skills/fluentcart-developer/references/hooks/actions/products-and-coupons.md +1019 -1019
  101. package/dist/skills/fluentcart-developer/references/hooks/actions/subscriptions.md +1290 -1290
  102. package/dist/skills/fluentcart-developer/references/hooks/actions.md +16 -16
  103. package/dist/skills/fluentcart-developer/references/hooks/deprecated.md +60 -60
  104. package/dist/skills/fluentcart-developer/references/hooks/filters/cart-and-checkout.md +2032 -2032
  105. package/dist/skills/fluentcart-developer/references/hooks/filters/customers-and-subscriptions.md +1746 -1746
  106. package/dist/skills/fluentcart-developer/references/hooks/filters/integrations-and-advanced.md +2439 -2439
  107. package/dist/skills/fluentcart-developer/references/hooks/filters/modules.md +464 -464
  108. package/dist/skills/fluentcart-developer/references/hooks/filters/orders-and-payments.md +2658 -2658
  109. package/dist/skills/fluentcart-developer/references/hooks/filters/pro-modules.md +502 -502
  110. package/dist/skills/fluentcart-developer/references/hooks/filters/products-and-pricing.md +1785 -1785
  111. package/dist/skills/fluentcart-developer/references/hooks/filters/settings-and-configuration.md +2966 -2966
  112. package/dist/skills/fluentcart-developer/references/hooks/filters.md +14 -14
  113. package/dist/skills/fluentcart-developer/references/hooks/index.md +35 -35
  114. package/dist/skills/fluentcart-developer/references/index.md +625 -625
  115. package/dist/skills/fluentcart-developer/references/modules/fee-system.md +427 -427
  116. package/dist/skills/fluentcart-developer/references/modules/ghost-product-selling.md +440 -440
  117. package/dist/skills/fluentcart-developer/references/modules/index.md +484 -484
  118. package/dist/skills/fluentcart-developer/references/modules/licensing.md +342 -342
  119. package/dist/skills/fluentcart-developer/references/modules/order-bump.md +433 -433
  120. package/dist/skills/fluentcart-developer/references/modules/payment-methods.md +129 -129
  121. package/dist/skills/fluentcart-developer/references/modules/refunds.md +170 -170
  122. package/dist/skills/fluentcart-developer/references/modules/shipping.md +846 -846
  123. package/dist/skills/fluentcart-developer/references/modules/storage.md +986 -986
  124. package/dist/skills/fluentcart-developer/references/modules/subscription-vendor-ids.md +186 -186
  125. package/dist/skills/fluentcart-developer/references/modules/subscriptions.md +678 -678
  126. package/dist/skills/fluentcart-developer/references/payment-methods-integration/index.md +164 -164
  127. package/dist/skills/fluentcart-developer/references/payment-methods-integration/paddle-example.md +1648 -1648
  128. package/dist/skills/fluentcart-developer/references/payment-methods-integration/payment/setting/fields.md +353 -353
  129. package/dist/skills/fluentcart-developer/references/payment-methods-integration/quick-implementation.md +1079 -1079
  130. package/dist/skills/fluentcart-developer/references/payment-methods-integration.md +164 -164
  131. package/dist/skills/fluentcart-developer/references/restapi/checkout.md +573 -573
  132. package/dist/skills/fluentcart-developer/references/restapi/coupons.md +958 -958
  133. package/dist/skills/fluentcart-developer/references/restapi/customer-profile.md +1423 -1423
  134. package/dist/skills/fluentcart-developer/references/restapi/customers.md +1103 -1103
  135. package/dist/skills/fluentcart-developer/references/restapi/dashboard.md +1083 -1083
  136. package/dist/skills/fluentcart-developer/references/restapi/data-export.md +132 -132
  137. package/dist/skills/fluentcart-developer/references/restapi/email-notifications.md +846 -846
  138. package/dist/skills/fluentcart-developer/references/restapi/files.md +313 -313
  139. package/dist/skills/fluentcart-developer/references/restapi/index.md +127 -127
  140. package/dist/skills/fluentcart-developer/references/restapi/integrations.md +1000 -1000
  141. package/dist/skills/fluentcart-developer/references/restapi/inventory.md +192 -192
  142. package/dist/skills/fluentcart-developer/references/restapi/labels-and-attributes.md +797 -797
  143. package/dist/skills/fluentcart-developer/references/restapi/licensing.md +1733 -1733
  144. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-available-shipping-methods.md +30 -30
  145. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-checkout-summary.md +28 -28
  146. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-country-info.md +29 -29
  147. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-order-info.md +28 -28
  148. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-shipping-methods-list-view.md +30 -30
  149. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/login.md +66 -66
  150. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/place-order.md +179 -179
  151. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/apply-coupon.md +83 -83
  152. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/cancel-coupon.md +87 -87
  153. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/check-product-eligibility.md +59 -59
  154. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/create-coupon.md +230 -230
  155. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/delete-coupon.md +29 -29
  156. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon-settings.md +20 -20
  157. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon.md +27 -27
  158. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupon-codes.md +20 -20
  159. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupons.md +37 -37
  160. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/re-apply-coupons.md +75 -75
  161. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/store-coupon-settings.md +40 -40
  162. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/update-coupon.md +133 -133
  163. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-address-checkout.md +138 -138
  164. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-profile-address.md +119 -119
  165. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/dashboard-overview.md +22 -22
  166. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/delete-profile-address.md +46 -46
  167. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-order-details.md +30 -30
  168. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-portal-sections.md +29 -29
  169. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-profile-details.md +22 -22
  170. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-transaction-billing-address.md +30 -30
  171. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-upgrade-paths.md +31 -31
  172. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-downloads.md +29 -29
  173. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-orders.md +28 -28
  174. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/make-profile-address-primary.md +55 -55
  175. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/pause-subscription.md +29 -29
  176. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/resume-subscription.md +29 -29
  177. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/save-transaction-billing-address.md +92 -92
  178. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/select-address-for-checkout.md +32 -32
  179. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-address.md +115 -115
  180. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-details.md +69 -69
  181. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/attach-user.md +50 -50
  182. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/bulk-actions.md +65 -65
  183. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-address.md +135 -135
  184. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-customer.md +108 -108
  185. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/delete-address.md +62 -62
  186. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/detach-user.md +28 -28
  187. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/find-customer-order.md +27 -27
  188. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-attachable-users.md +20 -20
  189. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-addresses.md +28 -28
  190. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-orders.md +37 -37
  191. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-stats.md +27 -27
  192. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer.md +32 -32
  193. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/list-customers.md +37 -37
  194. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/recalculate-ltv.md +28 -28
  195. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/set-primary-address.md +72 -72
  196. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-additional-info.md +55 -55
  197. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-address.md +144 -144
  198. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-customer.md +123 -123
  199. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/attach-note-to-order.md +49 -49
  200. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-all-pages.md +21 -21
  201. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-single-page.md +55 -55
  202. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/delete-activity.md +28 -28
  203. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-country-info.md +29 -29
  204. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-dashboard-stats.md +22 -22
  205. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-filter-options.md +31 -31
  206. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-data.md +20 -20
  207. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-settings.md +20 -20
  208. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-print-templates.md +20 -20
  209. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-search-options.md +27 -27
  210. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-widgets.md +28 -28
  211. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/initialize-app.md +20 -20
  212. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-activities.md +33 -33
  213. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-attachments.md +21 -21
  214. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-countries.md +20 -20
  215. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/mark-activity-read.md +53 -53
  216. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/run-data-backfills.md +21 -21
  217. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-settings.md +54 -54
  218. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-tax-settings.md +73 -73
  219. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-print-templates.md +64 -64
  220. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/upload-attachment.md +42 -42
  221. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-customers-batch.md +129 -129
  222. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-licenses-batch.md +133 -133
  223. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-orders-batch.md +129 -129
  224. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-subscriptions-batch.md +129 -129
  225. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-customers-export-schema.md +21 -21
  226. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-licenses-export-schema.md +26 -26
  227. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-orders-export-schema.md +21 -21
  228. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-subscriptions-export-schema.md +21 -21
  229. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/enable-notification.md +57 -57
  230. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-digest-settings.md +22 -22
  231. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-notification.md +30 -30
  232. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-reminders.md +22 -22
  233. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-settings.md +22 -22
  234. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-shortcodes.md +22 -22
  235. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/list-notifications.md +20 -20
  236. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-default-template.md +66 -66
  237. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-notification.md +50 -50
  238. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-digest-settings.md +101 -101
  239. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-reminders.md +162 -162
  240. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-settings.md +99 -99
  241. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-digest-test.md +47 -47
  242. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-manual-reminder.md +51 -51
  243. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/update-notification.md +93 -93
  244. package/dist/skills/fluentcart-developer/references/restapi/operations/files/delete-file.md +31 -31
  245. package/dist/skills/fluentcart-developer/references/restapi/operations/files/get-bucket-list.md +28 -28
  246. package/dist/skills/fluentcart-developer/references/restapi/operations/files/list-files.md +30 -30
  247. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-editor-file.md +32 -32
  248. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-file.md +34 -34
  249. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/chained-data-request.md +46 -46
  250. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/change-feed-status.md +51 -51
  251. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/delete-feed.md +27 -27
  252. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-dynamic-options.md +29 -29
  253. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-lists.md +27 -27
  254. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-settings.md +27 -27
  255. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-feeds.md +20 -20
  256. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-settings.md +26 -26
  257. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/install-addon-plugin.md +49 -49
  258. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/list-addons.md +20 -20
  259. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/save-feed-settings.md +52 -52
  260. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/set-global-settings.md +50 -50
  261. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/bulk-update-stock.md +94 -94
  262. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/export-inventory.md +81 -81
  263. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-adjustment-history.md +26 -26
  264. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-inventory-stats.md +21 -21
  265. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/list-inventory.md +33 -33
  266. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/update-stock.md +75 -75
  267. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-attribute-group.md +31 -31
  268. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-label.md +31 -31
  269. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-terms.md +90 -90
  270. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-group.md +28 -28
  271. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-term.md +29 -29
  272. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-group.md +28 -28
  273. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-library.md +20 -20
  274. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-groups.md +32 -32
  275. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-terms.md +33 -33
  276. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-labels.md +20 -20
  277. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-groups.md +51 -51
  278. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-terms.md +56 -56
  279. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-group.md +37 -37
  280. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-term.md +39 -39
  281. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-label-selections.md +32 -32
  282. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-plugin-license.md +41 -41
  283. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-site-admin.md +60 -60
  284. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-plugin-license.md +18 -18
  285. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-admin.md +67 -67
  286. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-customer.md +47 -47
  287. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/delete-license.md +24 -24
  288. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/extend-license-validity.md +47 -47
  289. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-license-details.md +25 -25
  290. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-licenses-admin.md +26 -26
  291. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-activations.md +25 -25
  292. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-details.md +25 -25
  293. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-site.md +30 -30
  294. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-plugin-license-status.md +18 -18
  295. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-product-license-settings.md +24 -24
  296. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-customer-licenses.md +25 -25
  297. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-license-sites.md +33 -33
  298. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-licenses.md +38 -38
  299. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-activate-license.md +54 -54
  300. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-check-license.md +26 -26
  301. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-deactivate-license.md +46 -46
  302. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-download-license-package.md +23 -23
  303. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-get-license-version.md +26 -26
  304. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/regenerate-license-key.md +24 -24
  305. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/save-product-license-settings.md +193 -193
  306. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-activation-limit.md +53 -53
  307. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-status.md +52 -52
  308. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/create-order-bump.md +47 -47
  309. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/delete-order-bump.md +25 -25
  310. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/get-order-bump.md +25 -25
  311. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/list-order-bumps.md +29 -29
  312. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/update-order-bump.md +141 -141
  313. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/accept-dispute.md +47 -47
  314. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/bulk-actions.md +72 -72
  315. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-shipping.md +67 -67
  316. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-tax.md +98 -98
  317. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/change-customer.md +50 -50
  318. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/charge-now.md +29 -29
  319. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-and-change-customer.md +92 -92
  320. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-custom-order-item.md +68 -68
  321. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-order.md +351 -351
  322. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-renewal-now.md +29 -29
  323. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/delete-order.md +28 -28
  324. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/generate-missing-licenses.md +29 -29
  325. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order-transactions.md +27 -27
  326. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order.md +27 -27
  327. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-renewal.md +28 -28
  328. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-shipping-methods.md +28 -28
  329. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-single-transaction.md +28 -28
  330. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-order-currencies.md +22 -22
  331. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-orders.md +42 -42
  332. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-renewals.md +28 -28
  333. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/mark-as-paid.md +61 -61
  334. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/price-order.md +135 -135
  335. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/refund-order.md +72 -72
  336. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/resend-renewal-invoice.md +29 -29
  337. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/skip-renewal.md +48 -48
  338. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-order-statuses.md +28 -28
  339. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-pending-transaction.md +29 -29
  340. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address-id.md +60 -60
  341. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address.md +98 -98
  342. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order.md +172 -172
  343. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-statuses.md +77 -77
  344. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-subscription-details.md +84 -84
  345. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-transaction-status.md +51 -51
  346. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/void-renewal.md +30 -30
  347. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/create-pdf-template.md +42 -42
  348. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/delete-pdf-template.md +26 -26
  349. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/download-pdf-preview.md +44 -44
  350. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-factory-default-templates.md +19 -19
  351. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-status.md +21 -21
  352. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-template.md +26 -26
  353. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-saved-templates.md +21 -21
  354. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-seller-details.md +19 -19
  355. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/list-pdf-templates.md +19 -19
  356. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-pdf-template.md +53 -53
  357. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-seller-details.md +97 -97
  358. package/dist/skills/fluentcart-developer/references/restapi/operations/products/add-product-terms.md +64 -64
  359. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-edit-fetch.md +30 -30
  360. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-insert-products.md +62 -62
  361. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-products.md +59 -59
  362. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-variants.md +83 -83
  363. package/dist/skills/fluentcart-developer/references/restapi/operations/products/change-integration-status.md +64 -64
  364. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-dummy-products.md +45 -45
  365. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-product.md +81 -81
  366. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-variation.md +181 -181
  367. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-downloadable-file.md +27 -27
  368. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product-integration.md +30 -30
  369. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product.md +27 -27
  370. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-taxonomy-term.md +55 -55
  371. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-upgrade-path.md +27 -27
  372. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-variation.md +27 -27
  373. package/dist/skills/fluentcart-developer/references/restapi/operations/products/do-bulk-action.md +56 -56
  374. package/dist/skills/fluentcart-developer/references/restapi/operations/products/duplicate-product.md +56 -56
  375. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-products-by-ids.md +26 -26
  376. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-taxonomy-terms.md +20 -20
  377. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-terms-by-parent.md +60 -60
  378. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-variations-by-ids.md +26 -26
  379. package/dist/skills/fluentcart-developer/references/restapi/operations/products/find-subscription-variants.md +26 -26
  380. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-bundle-info.md +27 -27
  381. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-downloadable-url.md +27 -27
  382. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-max-excerpt-word-count.md +20 -20
  383. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-pricing-widgets.md +27 -27
  384. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-feeds.md +29 -29
  385. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-settings.md +31 -31
  386. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-pricing.md +28 -28
  387. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product.md +28 -28
  388. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-related-products.md +31 -31
  389. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-upgrade-settings.md +27 -27
  390. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-variation-upgrade-paths.md +28 -28
  391. package/dist/skills/fluentcart-developer/references/restapi/operations/products/group-bulk-update-variants.md +103 -103
  392. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-all-variants.md +26 -26
  393. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-product-variations.md +26 -26
  394. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-products.md +34 -34
  395. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-shipping-class.md +27 -27
  396. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-tax-class.md +27 -27
  397. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-bundle-info.md +56 -56
  398. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-product-integration.md +62 -62
  399. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-upgrade-path.md +78 -78
  400. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-product-variant-options.md +29 -29
  401. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-products-by-name.md +28 -28
  402. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-variants-by-name.md +28 -28
  403. package/dist/skills/fluentcart-developer/references/restapi/operations/products/set-variation-media.md +74 -74
  404. package/dist/skills/fluentcart-developer/references/restapi/operations/products/suggest-sku.md +28 -28
  405. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-downloadable-files.md +134 -134
  406. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-taxonomy-terms.md +61 -61
  407. package/dist/skills/fluentcart-developer/references/restapi/operations/products/toggle-product-tax-exemption.md +56 -56
  408. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-downloadable-file.md +98 -98
  409. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-inventory.md +56 -56
  410. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-long-desc-editor-mode.md +49 -49
  411. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-manage-stock.md +53 -53
  412. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-detail.md +58 -58
  413. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-pricing.md +225 -225
  414. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-shipping-class.md +49 -49
  415. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-tax-class.md +49 -49
  416. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-upgrade-path.md +78 -78
  417. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-option.md +79 -79
  418. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-tax-exemption.md +56 -56
  419. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation-pricing-table.md +49 -49
  420. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation.md +105 -105
  421. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/get-product-views.md +34 -34
  422. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/list-products.md +42 -42
  423. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/search-products.md +30 -30
  424. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/channel-rules.md +24 -24
  425. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/country-heat-map.md +22 -22
  426. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupon-overview.md +37 -37
  427. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupons.md +36 -36
  428. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-insights.md +31 -31
  429. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-overview.md +36 -36
  430. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-repeat.md +35 -35
  431. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segment-customers.md +36 -36
  432. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segments.md +30 -30
  433. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-value.md +34 -34
  434. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/dashboard-stats.md +30 -30
  435. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/failed-orders.md +34 -34
  436. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-new-vs-returning-customer.md +34 -34
  437. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-by-day-and-hour.md +34 -34
  438. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-meta.md +29 -29
  439. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-top-sold-products.md +34 -34
  440. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/future-renewals.md +31 -31
  441. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/generate-retention-snapshots.md +24 -24
  442. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-overview.md +30 -30
  443. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-activities.md +26 -26
  444. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-orders.md +20 -20
  445. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-revenue.md +37 -37
  446. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-at-risk.md +35 -35
  447. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-variations.md +33 -33
  448. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments.md +33 -33
  449. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/item-count-distribution.md +34 -34
  450. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-chart.md +30 -30
  451. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-pie-chart.md +22 -22
  452. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-summary.md +22 -22
  453. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/locations.md +43 -43
  454. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-chart.md +37 -37
  455. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-completion-time.md +34 -34
  456. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-mix.md +34 -34
  457. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-value-distribution.md +34 -34
  458. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-disputes.md +38 -38
  459. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-methods.md +36 -36
  460. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods.md +37 -37
  461. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison-launch.md +33 -33
  462. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison.md +40 -40
  463. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-detail.md +37 -37
  464. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-sales.md +37 -37
  465. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/refunds-overview.md +37 -37
  466. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/retention-snapshots-step.md +45 -45
  467. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sales-growth-chart.md +35 -35
  468. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/save-channel-rules.md +73 -73
  469. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/source-channels.md +37 -37
  470. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sources.md +49 -49
  471. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-cohorts.md +33 -33
  472. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-health.md +30 -30
  473. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-rebuys.md +37 -37
  474. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-retention.md +34 -34
  475. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-variations.md +22 -22
  476. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscriptions-overview.md +37 -37
  477. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/weeks-between-refund.md +34 -34
  478. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/assign-role.md +48 -48
  479. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/delete-role-assignment.md +47 -47
  480. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/get-role.md +25 -25
  481. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-managers.md +18 -18
  482. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-roles.md +18 -18
  483. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/search-users.md +25 -25
  484. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/update-role.md +43 -43
  485. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/create-saved-view.md +106 -106
  486. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/delete-saved-view.md +26 -26
  487. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/list-saved-views.md +25 -25
  488. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/update-saved-view.md +83 -83
  489. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-payment-addon.md +44 -44
  490. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-plugin-addon.md +44 -44
  491. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/change-storage-driver-status.md +56 -56
  492. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/check-paypal-webhook.md +26 -26
  493. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/create-storage-bucket.md +63 -63
  494. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/disconnect-payment-method.md +55 -55
  495. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/exchange-paypal-seller-auth-token.md +62 -62
  496. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-active-storage-drivers.md +20 -20
  497. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-checkout-fields.md +22 -22
  498. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-email-shortcodes.md +20 -20
  499. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-config-snippets.md +26 -26
  500. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-status.md +20 -20
  501. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-module-settings.md +20 -20
  502. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-connection-info.md +26 -26
  503. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-settings.md +26 -26
  504. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-permissions.md +22 -22
  505. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-plugin-addons.md +20 -20
  506. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-storage-driver-settings.md +27 -27
  507. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-store-settings.md +26 -26
  508. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-mcp-adapter.md +21 -21
  509. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-payment-addon.md +60 -60
  510. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-plugin-addon.md +64 -64
  511. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-payment-methods.md +20 -20
  512. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-storage-drivers.md +20 -20
  513. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-storage-buckets.md +67 -67
  514. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reorder-payment-methods.md +55 -55
  515. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reset-storage-driver-settings.md +45 -45
  516. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-checkout-fields.md +133 -133
  517. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-confirmation-settings.md +68 -68
  518. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-module-settings.md +68 -68
  519. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-design.md +67 -67
  520. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-settings.md +58 -58
  521. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-permissions.md +68 -68
  522. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-storage-driver-settings.md +62 -62
  523. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-store-settings.md +239 -239
  524. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/setup-paypal-webhook.md +48 -48
  525. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/toggle-mcp.md +40 -40
  526. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-storage-driver-connection.md +62 -62
  527. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-turnstile-keys.md +55 -55
  528. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-class.md +73 -73
  529. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-method.md +110 -110
  530. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-zone.md +56 -56
  531. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-class.md +29 -29
  532. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-method.md +29 -29
  533. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-zone.md +29 -29
  534. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class-profile.md +30 -30
  535. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class.md +29 -29
  536. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-packages.md +22 -22
  537. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-zone.md +27 -27
  538. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-countries.md +22 -22
  539. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-states.md +28 -28
  540. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-classes.md +31 -31
  541. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-zones.md +31 -31
  542. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/save-shipping-packages.md +112 -112
  543. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-class.md +79 -79
  544. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-method.md +113 -113
  545. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-zone.md +62 -62
  546. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-zone-order.md +52 -52
  547. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-auto-renew.md +30 -30
  548. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-subscription.md +52 -52
  549. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/confirm-subscription-switch.md +70 -70
  550. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/fetch-subscription-remote.md +28 -28
  551. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/generate-early-payment-link.md +29 -29
  552. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-customer-subscription.md +27 -27
  553. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-or-create-plan.md +69 -69
  554. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-setup-intent-attempts.md +30 -30
  555. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-subscription.md +28 -28
  556. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/initiate-early-payment.md +31 -31
  557. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-customer-subscriptions.md +27 -27
  558. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-subscriptions.md +39 -39
  559. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/pause-subscription.md +28 -28
  560. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/reactivate-subscription.md +28 -28
  561. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/resume-subscription.md +28 -28
  562. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/switch-payment-method.md +70 -70
  563. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-payment-method.md +69 -69
  564. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-vendor-ids.md +56 -56
  565. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/verify-vendor-ids.md +56 -56
  566. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-class.md +51 -51
  567. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-rate.md +117 -117
  568. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-product-override.md +27 -27
  569. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-shipping-tax-override.md +27 -27
  570. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-class.md +28 -28
  571. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-rate.md +27 -27
  572. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-id.md +27 -27
  573. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-rates.md +28 -28
  574. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-eu-vat-product-overrides.md +20 -20
  575. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-oss-country-rates.md +20 -20
  576. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-preconfigured-tax-rates.md +20 -20
  577. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-product-overrides.md +27 -27
  578. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-tax-settings.md +20 -20
  579. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-all-tax-rates.md +20 -20
  580. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-classes.md +20 -20
  581. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-records.md +37 -37
  582. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/mark-taxes-as-filed.md +58 -58
  583. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/reset-eu-vat-rates.md +21 -21
  584. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-configured-countries.md +57 -57
  585. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-country-tax-id.md +50 -50
  586. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-eu-vat-cross-border-settings.md +127 -127
  587. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-oss-country-rates.md +100 -100
  588. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-product-override.md +110 -110
  589. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-shipping-tax-override.md +52 -52
  590. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-tax-settings.md +166 -166
  591. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-country-status.md +54 -54
  592. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-tax-rate.md +116 -116
  593. package/dist/skills/fluentcart-developer/references/restapi/order-bumps.md +433 -433
  594. package/dist/skills/fluentcart-developer/references/restapi/orders.md +1212 -1212
  595. package/dist/skills/fluentcart-developer/references/restapi/pdf-templates.md +212 -212
  596. package/dist/skills/fluentcart-developer/references/restapi/products.md +2485 -2485
  597. package/dist/skills/fluentcart-developer/references/restapi/public-shop.md +191 -191
  598. package/dist/skills/fluentcart-developer/references/restapi/reports.md +3773 -3773
  599. package/dist/skills/fluentcart-developer/references/restapi/roles.md +403 -403
  600. package/dist/skills/fluentcart-developer/references/restapi/saved-views.md +136 -136
  601. package/dist/skills/fluentcart-developer/references/restapi/settings.md +1423 -1423
  602. package/dist/skills/fluentcart-developer/references/restapi/shipping.md +905 -905
  603. package/dist/skills/fluentcart-developer/references/restapi/subscriptions.md +1169 -1169
  604. package/dist/skills/fluentcart-developer/references/restapi/tax.md +1551 -1551
  605. package/dist/skills/fluentcart-developer/references/restapi.md +127 -127
  606. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  607. package/dist/version.d.ts +1 -1
  608. package/dist/version.js +1 -1
  609. package/package.json +66 -65
@@ -1,678 +1,678 @@
1
- # Subscriptions Module
2
-
3
- FluentCart's subscription engine bills recurring products through **two competing models** — one where the payment gateway owns the schedule, and one where FluentCart owns it — unified behind a single database column and a single shared write-spine. This document is the architectural map: how the model is chosen, what machinery each one uses, and where they converge.
4
-
5
- Where subscriptions live
6
-
7
- | Concern | Location |
8
- | --- | --- |
9
- | Model + attributes | [`Subscription` model](/database/models/subscription.md) · [`SubscriptionMeta`](/database/models/subscription-meta.md) |
10
- | Lifecycle hooks | [Action hooks](/hooks/actions/subscriptions.md) · [Filter hooks](/hooks/filters/customers-and-subscriptions.md) |
11
- | REST endpoints | [Subscriptions API](/api/subscriptions.md) · [REST operations](/restapi/subscriptions.md) |
12
- | Core code | `app/Modules/Subscriptions/` · `app/Modules/StoreManagedRenewal/` |
13
-
14
- ## The one idea
15
-
16
- Every subscription answers a single question: **who owns the billing schedule — the payment gateway, or FluentCart?**
17
-
18
- That answer is the `fct_subscriptions.collection_method` column, and it decides everything downstream: whether a renewal is a webhook you receive or a renewal you generate, whether dunning is Stripe's retry ladder or FluentCart's grace period, whether an admin can edit the recurring amount.
19
-
20
- | `collection_method` | Who bills | Renewal arrives as | Dunning owned by |
21
- | --- | --- | --- | --- |
22
- | `automatic` | The **gateway**, via a vendor subscription object (Stripe `sub_…`, PayPal `I-…`) | An inbound **webhook** | The gateway |
23
- | `manual` | **FluentCart**, via the renewal engine; the customer pays each renewal by hand | A **renewal** you generate on a cron | FluentCart (reminders → past_due → expired) |
24
- | `system` | **FluentCart**, via the renewal engine; a saved token is charged automatically | A **renewal** you generate, then charge off-session | FluentCart (retries → past_due → expired) |
25
-
26
- `manual` and `system` are the **same engine**. `system` just adds a saved payment method and an automatic charge attempt per renewal. The predicate that groups them is `Subscription::usesRenewalEngine()` — **that method, not `collection_method` itself, is the real store-managed test**, and it appears as a guard throughout the codebase.
27
-
28
- **Reading by type:** `automatic` → [Gateway-managed](#gateway-managed-automatic). `manual` → [the renewal engine](#store-managed-the-renewal-engine-manual-system) (it is the base — there is no separate "manual" section). `system` → the renewal engine **plus** [the auto-charge delta](#store-managed-auto-charge-system). [The capability matrix](#what-each-model-allows) compares all three side by side.
29
-
30
- ## How the method is decided
31
-
32
- Exactly one place, exactly once — at checkout. `CheckoutProcessor::determineCollectionMethod()`:
33
-
34
- Two inputs: a **store setting** and a **gateway capability**.
35
-
36
- ### The setting
37
-
38
- `SubscriptionManagementMode` (`app/Modules/Subscriptions/Services/SubscriptionManagementMode.php`) reads from the `fluent_cart_store_settings` option blob, rendered on the Subscriptions settings tab and sanitized by whitelist in the meta request.
39
-
40
- | Key | Values | Default |
41
- | --- | --- | --- |
42
- | `subscription_management_mode` | `gateway_managed` \| `store_managed` | `gateway_managed` |
43
- | `subscription_system_charge` | `yes` \| `no` | `no` |
44
- | `subscription_manual_fallback` | `yes` \| `no` | `no` |
45
-
46
- `subscription_system_charge` is inert under `gateway_managed` — `isSystemChargeEnabled()` returns `false` outright unless the mode is store-managed.
47
-
48
- `subscription_manual_fallback` is inert under `store_managed` — `isManualFallbackEnabled()` returns `false` outright unless the mode is gateway-managed. When on, gateways without `subscriptions` support are offered on a gateway-managed subscription cart instead of being hidden, and the resulting subscription is created with `collection_method = manual` — invoiced by FluentCart, paid by hand each cycle.
49
-
50
- ### The full decision matrix
51
-
52
- | Mode | System charge | Gateway | Result |
53
- | --- | --- | --- | --- |
54
- | gateway_managed | (ignored) | has `subscriptions` | `automatic` |
55
- | gateway_managed, manual fallback **on** | (ignored) | no `subscriptions` (COD, bank transfer) | `manual` |
56
- | store_managed | off | any | `manual` |
57
- | store_managed | on | has `system_subscription` (Stripe, PayPal) | `system` |
58
- | store_managed | on | no `system_subscription` (COD, bank transfer…) | `manual` |
59
-
60
- A per-gateway filter gets the last word: `fluent_cart/subscription_collection_method_{gateway}`.
61
-
62
- Both Stripe and PayPal do `system`
63
-
64
- Off-session auto-charge is the `system_subscription` capability, and **both Stripe and PayPal declare it** (each overrides `chargeRenewal()` / `reconcileRenewalCharge()`). The Stripe-only axis is a *narrower* one — `zero_recurring` / `supportsSetupWithoutCharge()`, the ability to vault a card at **$0 on a free-trial cart**. PayPal must take a payable-now charge to vault its token, so it can run `system` on a paid-now cart but **cannot start a `system` sub from a $0 trial**.
65
-
66
- ### The durable stamp — why flipping the setting is safe
67
-
68
- A store-managed subscription also gets `config['management_mode'] = 'store_managed'` written onto its row.
69
-
70
- This exists because **payment paths must consult the stamp, not the live setting**. Gateways contain legacy logic that converts a `manual` subscription to `automatic` when it is paid through a subscription-capable gateway. Without the stamp, a merchant who flipped back to `gateway_managed` would silently convert every store-managed subscription into a vendor subscription the next time a customer paid a renewal.
71
-
72
- An unstamped `manual` subscription — one born on a gateway-managed store — can still convert, and that is intentional. When it may is covered under [which gateways appear on a renewal](#which-gateways-appear-on-a-renewal-or-reactivation).
73
-
74
- `AbstractPaymentGateway::shouldChargeSubscriptionAsOneTime()` is the enforcement point:
75
-
76
- - `automatic` subscription → `false` (keeps billing at the vendor, untouched by a flip to store-managed)
77
- - **stamped** store-managed subscription → `true` **regardless of the current setting** — it can never be converted
78
- - unstamped `manual` (pre-feature legacy) → follows the live setting
79
-
80
- The single most important invariant
81
-
82
- **Flipping the mode affects new checkouts only.** No existing subscription ever changes its billing model.
83
-
84
- ### Gateway capability flags
85
-
86
- Declared as `$supportedFeatures` on each gateway; tested with `AbstractPaymentGateway::has()`.
87
-
88
- | Gateway | `subscriptions` | `manual_subscription` | `system_subscription` | `zero_recurring` | `switch_payment_method` | `card_update` |
89
- | --- | --- | --- | --- | --- | --- | --- |
90
- | **Stripe** | ✅ | ✅ | ✅ | ✅ **(only one)** | ✅ | ✅ |
91
- | **PayPal** | ✅ | ✅ | ✅ | — | ✅ | ✅ |
92
- | COD / offline | — | — | — | — | — | — |
93
- | Authorize.net, Mollie, Paddle (pro) | ✅ | ✅ | — | — | — | Paddle only |
94
- | Square, Paystack, Flutterwave, Razorpay (addons) | ✅ | — | — | — | — | — |
95
- | MercadoPago, SSLCommerz (addons) | — | ✅ | — | — | — | — |
96
-
97
- `zero_recurring` (backed by `supportsSetupWithoutCharge()`) is what lets a gateway vault a card at **$0** — the free-trial `system` case. Only Stripe has it; PayPal does `system` but only when the cart charges something now.
98
-
99
- `manual_subscription` is independent of `system_subscription` — it only claims a gateway routes a store-managed subscription's first payment through its existing one-time-charge path instead of creating a vendor subscription (`shouldChargeSubscriptionAsOneTime()`, below). COD/offline don't need it: `storeBilledOnly()` already admits them via `has('offline')` / `!has('subscriptions')`. MercadoPago and SSLCommerz declare it anyway even though the same `!has('subscriptions')` short-circuit already admits them — it's redundant, not load-bearing.
100
-
101
- A seventh flag, `verify_vendor_ids`, is unrelated to billing: it claims the gateway can look a subscription id up read-only, which the [vendor-id repair tool](/modules/subscription-vendor-ids.md) uses to preview a correction before it is saved. Only Stripe and PayPal declare it; every other gateway inherits `AbstractSubscriptionModule::verifyVendorSubscription()`, which returns `not_implemented`.
102
-
103
- The actual admit/hide decision for store-managed checkout lives in `SubscriptionGatewayGate::storeBilledOnly()` (`app/Modules/Subscriptions/Services/SubscriptionGatewayGate.php`):
104
-
105
- ```
106
- return $gateway->has('offline')
107
- || !$gateway->has('subscriptions')
108
- || $gateway->has('manual_subscription');
109
- ```
110
-
111
- A gateway is eligible if it's offline, or doesn't declare `subscriptions` at all, or declares `subscriptions` **and** `manual_subscription`. That third branch is the only case where `manual_subscription` changes anything — it's what lets Stripe/PayPal/Authorize.net/Mollie/Paddle (subscription-capable gateways) also be offered on a store-managed cart instead of being excluded.
112
-
113
- Two traps worth knowing:
114
-
115
- 1. **`has('subscriptions')` is auto-appended** by the constructor whenever a subscription module is injected — so the literal `$supportedFeatures` array under-reports it.
116
- 2. **`has('switch_payment_method')` always returns `false`.** It is an *associative* entry, and `has()` does `in_array` over values. Every call site reads it with `Arr::get($gateway->supportedFeatures, 'switch_payment_method')` instead.
117
-
118
- ### `manual_subscription` — wiring a third-party gateway for store-managed billing
119
-
120
- A gateway earns `manual_subscription` by proving it can take a subscription's first payment as a plain one-time charge, with no vendor subscription object created. Two changes, both in the gateway class:
121
-
122
- 1. Add `'manual_subscription'` to `$supportedFeatures`.
123
- 2. In `makePaymentFromPaymentInstance()`, consult `shouldChargeSubscriptionAsOneTime()` **before** any vendor-subscription/conversion logic, routing to the gateway's existing single-payment path when it returns `true`:
124
-
125
- ```
126
- // AuthorizeDotNet.php — makePaymentFromPaymentInstance()
127
- if ($this->shouldChargeSubscriptionAsOneTime($paymentInstance)) {
128
- return (new AuthorizeDotNetProcessor($this->authorizeSettings))->handleSinglePayment($paymentInstance);
129
- }
130
- ```
131
-
132
- That's the whole pattern — Mollie and Paddle (fluent-cart-pro) mirror it, each calling their own existing `handleSinglePayment()`. Don't add `system_subscription` alongside it unless the gateway also overrides `chargeRenewal()` / `reconcileRenewalCharge()` — `manual_subscription` alone only unlocks the non-zero-payable case; a gateway with no auto-charge implementation correctly stays hidden on $0-due carts.
133
-
134
- ### Which gateways appear on a new subscription cart
135
-
136
- `SubscriptionGatewayGate` capability-gates the payment methods on every subscription cart, on `fluent_cart/checkout_active_payment_methods`. It is the only filter on that list. **Both modes gate, in opposite directions** — store-managed keeps schedule-owning gateways out, gateway-managed keeps them in.
137
-
138
- | Mode | Amount due today | Gateways offered |
139
- | --- | --- | --- |
140
- | `gateway_managed` | any | Gateways **with** `subscriptions` only — a gateway-managed store has no renewal engine, so a subscription needs a gateway that can run its own schedule. Turn on the `subscription_manual_fallback` setting (default `no`) and gateways without it are offered again, billing `manual` |
141
- | `store_managed` | > 0 | Gateways **without** `subscriptions` (COD, bank transfer, MercadoPago, SSLCommerz) — they can't auto-bill anyway — **plus** `manual_subscription` gateways (Stripe, PayPal, Authorize.net, Mollie, Paddle), which take a single charge here because `shouldChargeSubscriptionAsOneTime()` forces it. Vendor-billing-only gateways hidden |
142
- | `store_managed`, auto-charge **on** | 0 (free trial) | Offline methods, plus a `system_subscription` gateway that can vault without charging (`supportsSetupWithoutCharge()`) — Stripe in `onsite` mode, PayPal in `paypal_pro` mode. Either gateway in another checkout mode drops off |
143
- | `store_managed`, auto-charge **off** | 0 (free trial) | Offline methods only — nothing would ever charge a saved token |
144
-
145
- Admission under `store_managed` is deliberately **opt-in**: a gateway is shown only when it is known not to run its own schedule. An unrecognised third-party gateway is hidden rather than trusted, because a gateway that creates a vendor subscription inside its own payment flow would bill in parallel with the renewals the engine generates.
146
-
147
- Renewal and reactivation carts follow the *subscription*, not the store setting — see [which gateways appear on a renewal](#which-gateways-appear-on-a-renewal-or-reactivation).
148
-
149
- **None of this is a security boundary.** The same filter re-runs server-side against the single posted gateway at order placement and returns `423` on a mismatch, so hiding a method in the UI is not what enforces it.
150
-
151
- ## Gateway-managed (`automatic`)
152
-
153
- FluentCart hands the schedule to the gateway and becomes a mirror.
154
-
155
- ### Creation
156
-
157
- The three subscription-capable gateways behave differently at creation — a critical detail, because two of them produce the `vendor_subscription_id` asynchronously:
158
-
159
- WARNING
160
-
161
- Any code that assumes `vendor_subscription_id` exists right after checkout is wrong for **two of the three** gateways.
162
-
163
- ### Renewal — the gateway tells you
164
-
165
- All webhooks enter at `?fluent-cart=fct_payment_listener_ipn&method={slug}` → `GlobalPaymentHandler` → `$gateway->handleIPN()`.
166
-
167
- | Gateway | Renewal event | Handler |
168
- | --- | --- | --- |
169
- | Stripe | `invoice.paid` with `billing_reason = subscription_cycle` | `Webhook::processSubscriptionRenewal()` |
170
- | PayPal | `PAYMENT.SALE.COMPLETED` **with** `billing_agreement_id` | `IPN::processRecurringPaymentReceived()` |
171
- | Paddle | `subscription.payment_received` | Re-syncs from remote, which then records the payment |
172
-
173
- All three converge on **`SubscriptionService::recordRenewalPayment()`**:
174
-
175
- 1. Takes a MySQL lock on `fc_webhook_{vendor_charge_id}` and checks for an existing transaction — **idempotency**, because gateways retry webhooks.
176
- 2. **If a pending renewal already exists for the parent order, it settles that renewal** instead of creating a new order. This is the seam where a converted subscription's renewal gets closed out by a gateway webhook.
177
- 3. Otherwise creates a child renewal `Order` (`type = renewal`, `parent_id` = the parent order) + `OrderItem` + a succeeded `OrderTransaction`.
178
- 4. Calls `syncSubscriptionStates()` with the gateway's own data.
179
- 5. Dispatches `SubscriptionRenewed`.
180
-
181
- **`next_billing_date` is copied from the gateway** (`current_period_end`, `billing_info.next_billing_time`, `next_billed_at`) — never computed locally. `guessNextBillingDate()` is only a fallback for when the gateway supplies nothing.
182
-
183
- ### Status sync
184
-
185
- Gateway-side changes (canceled, past_due, paused) reach the local row two ways:
186
-
187
- - **Webhooks:** `customer.subscription.updated` / `.deleted` (Stripe), `BILLING.SUBSCRIPTION.*` (PayPal), `subscription.updated|past_due|paused|resumed` (Paddle).
188
- - **`Subscription::reSyncFromRemote()`** — pull, not push. Called by the webhook handlers, and by the admin **Fetch** button (`SubscriptionController::fetchSubscription()`), gated on `canFetch` = not renewal-engine + has a vendor id.
189
-
190
- Status mapping is per-gateway and **not** one-to-one. Stripe's (`StripeHelper::transformSubscriptionStatus()`):
191
-
192
- | Stripe | FluentCart | Note |
193
- | --- | --- | --- |
194
- | `active` | `active` | |
195
- | `trialing` | `trialing` | |
196
- | `incomplete`, `incomplete_expired` | `intended` | |
197
- | **`past_due`** | **`expiring`** | not `past_due`! That local status is store-managed-only |
198
- | `unpaid` | `expired` | |
199
- | `canceled` | `canceled` | → `expired` if `cancellation_details.reason = payment_failed` |
200
- | `paused` | `paused` | |
201
-
202
- ### What gateway-managed does **not** do locally
203
-
204
- This is the cleanest way to understand the split:
205
-
206
- 1. **The renewal cron never touches it.** Every query in `RenewalService` is `whereIn('collection_method', ['manual','system'])`. No renewal order is pre-created; it appears reactively when the webhook lands.
207
- 2. **No local dunning or retries.** Retry ladders are the gateway's. FluentCart mirrors the resulting status.
208
- 3. **The recurring amount is not editable** — `canUpdateDetails()` is renewal-engine-only, and `recurring_total` is overwritten from the gateway's plan amount on every sync.
209
- 4. **The one local cron that does touch it** is a safety net: `Subscription::checkAndExpireSubscriptions()` (queried `whereNotIn('collection_method', ['manual','system'])`) expires a subscription whose `next_billing_date` is past the grace period — i.e. the webhook never arrived or the gateway silently stopped billing. It charges nothing; it only marks the row expired.
210
-
211
- ## First payments and simulated trials
212
-
213
- A subscription's first payment is often not the same as its renewals. A signup fee makes it bigger. A free trial makes it zero. A first-payment coupon or an upgrade credit makes it smaller. FluentCart supports all of these on every gateway that runs subscriptions, including gateways that have no signup fee, cannot charge a different first amount, or have no trial at all.
214
-
215
- The way FluentCart fills that gap can make a subscription look like it is on a trial, in the FluentCart admin and in the gateway's dashboard. **That "Trialing" status is expected. It is not a bug.**
216
-
217
- At a glance
218
-
219
- | Question | Short answer |
220
- | --- | --- |
221
- | Why does admin show "Trialing" when I never offered a trial? | The first payment was lower than the renewal price. FluentCart charged that amount at checkout and told the gateway to wait one billing period before its first renewal. Most gateways call that wait a trial. |
222
- | What does the customer see? | "Active". The customer portal hides a trial that FluentCart created this way. |
223
- | Is the customer charged twice? | No. The first period is paid once, at checkout. The gateway's first charge is for the second period. |
224
- | When does it go away? | On the next billing date, when the gateway starts billing. |
225
-
226
- ### The two numbers
227
-
228
- Every subscription checkout ends with two numbers: **what the customer pays now**, and **what the customer pays on each renewal**. FluentCart works both out first, then compares the cost of the first period with the renewal price:
229
-
230
- | First period costs… | Example | What FluentCart sets up |
231
- | --- | --- | --- |
232
- | The same as a renewal | Plain $20/month | Nothing special. |
233
- | More than a renewal | $20/month + $15 signup fee | A $35 first payment, then $20 renewals. |
234
- | Less than a renewal | $20/month with a 50% first-month coupon | A $10 first payment. The first renewal waits one full billing period. FluentCart marks this wait as a **simulated trial**. |
235
- | Nothing | Free trial, 100% coupon, full upgrade credit | No charge (or a card check). The first renewal waits for the trial, or for one billing period. |
236
-
237
- A simulated trial is the wait after a first payment that was lower than the renewal price. Nobody offered it as a trial. FluentCart uses it because "charge something now, start billing later" is the one tool almost every gateway has.
238
-
239
- These lower the first payment and can create one:
240
-
241
- - A coupon that applies to the first payment only.
242
- - A plan upgrade's prorated credit, or an upgrade discount.
243
- - A shipping discount on the first order only, when renewals bill full shipping.
244
- - A 100% discount.
245
-
246
- A coupon that applies to every renewal lowers the renewal price instead, so it creates no simulated trial.
247
-
248
- **Length:** one billing period in days. Monthly uses the number of days in the month of checkout, yearly 365, quarterly 90, weekly 7. A real free trial on the same plan is added on top. The total is capped at 365 days by default (filter `fluent_cart/max_trial_days_allowed`).
249
-
250
- ### Example: a first-month coupon
251
-
252
- A customer buys a $20/month plan on 10 March with a coupon for 50% off the first month.
253
-
254
- 1. FluentCart charges **$10** at checkout.
255
- 2. The first period costs less than a renewal, so it adds a simulated trial of **31 days** (March has 31).
256
- 3. The gateway is told to start billing on **10 April**, at $20.
257
- 4. Until 10 April, the admin and the gateway dashboard may show **Trialing**. The customer portal shows **Active**.
258
- 5. On 10 April the gateway charges $20, and the status becomes Active everywhere.
259
-
260
- ### Example: a plan upgrade
261
-
262
- A customer on a $10/month plan upgrades to a $30/month plan. The unused part of their current month is worth $5, so FluentCart gives a $5 upgrade credit.
263
-
264
- 1. FluentCart charges **$25** at checkout.
265
- 2. $25 is less than the $30 renewal, so the new subscription gets a simulated trial of one billing period.
266
- 3. The gateway first bills $30 one month later.
267
- 4. Until then the new subscription may show **Trialing** in the admin, even though the customer has paid and never saw a trial.
268
-
269
- ### How gateways carry it out
270
-
271
- FluentCart sends the gateway the same plan whatever the gateway can do. Each gateway uses the closest tool it has:
272
-
273
- | Gateway can… | What FluentCart does |
274
- | --- | --- |
275
- | Run a trial and add a one-off first charge | Uses both. The wait is the gateway's own trial, and the first payment is an extra charge on the first invoice. |
276
- | Run a trial, but has no signup fee | Uses a trial period priced at the first payment. |
277
- | Neither | Charges the first payment itself as a one-time payment, then creates the gateway subscription with a later start date. |
278
- | Not delay the start at all | Can still take a lower or higher first payment, but cannot run a real free trial. FluentCart refuses that checkout. |
279
-
280
- Whatever the tool, the gateway reports its own status, and FluentCart shows that status in the admin. Gateways that model the wait as a trial report **Trialing**. Gateways that model it as a later start date may report either **Trialing** or **Active** until billing starts.
281
-
282
- ### Why the admin and the portal differ
283
-
284
- The admin shows the status the gateway reports. The customer portal reads a corrected status (`overridden_status`):
285
-
286
- | Subscription | Admin shows | Customer portal shows |
287
- | --- | --- | --- |
288
- | Simulated trial, gateway reports trialing | Trialing | **Active** |
289
- | Real free trial, gateway reports active, still inside the trial | Active | **Trialing** |
290
- | Everything else | The stored status | The same |
291
-
292
- So the admin always shows what the gateway reports, and the customer sees what they bought.
293
-
294
- Other places that tell the two kinds of trial apart:
295
-
296
- - **Product and checkout labels.** "Free Trial: N days" is never shown for a simulated trial.
297
- - **Reminders.** A simulated trial gets renewal reminders, like any paid subscription. Only a real trial gets trial-ending reminders.
298
- - **Subscription reports.** A trialing subscription with a simulated trial is counted as "discounted", not as a trial.
299
- - **Plan upgrades.** A subscription on a real trial gets no prorated credit when it upgrades. One on a simulated trial does, because the customer paid for that period.
300
-
301
- ### Installments
302
-
303
- On a plan with a fixed number of payments, the first payment at checkout already covers the first period. So the gateway must bill one fewer time (`getInitialRemoteBillTimes()`). Gateways that take a payment count get the reduced count. Gateways that do not are ended by FluentCart: when the last payment is recorded, the subscription completes and `SubscriptionEOT` cancels it at the gateway (see [Events](#events)).
304
-
305
- ### Reactivation
306
-
307
- A canceled or expired subscription that is reactivated usually gets a **new** gateway subscription. If the customer still has paid days left, the new one waits until they run out (`getReactivationTrialDays()`). That wait is a simulated trial too, so it can show "Trialing" in the admin.
308
-
309
- If the reactivation payment is the last installment, most gateways create no new gateway subscription, and FluentCart completes the subscription locally.
310
-
311
- ### Store-managed subscriptions
312
-
313
- A [store-managed](#store-managed-the-renewal-engine-manual-system) subscription has no gateway subscription. FluentCart runs the schedule itself, so it needs no trial trick. On first activation:
314
-
315
- - A real free trial starts as **Trialing**.
316
- - A simulated trial starts as **Active**.
317
-
318
- ### For support
319
-
320
- When a merchant reports "Trialing" on a subscription with no trial:
321
-
322
- 1. Open the order. If the first payment was lower than the renewal price (coupon, upgrade, discount), this is a simulated trial.
323
- 2. Check the next billing date. It should be one billing period after the first payment.
324
- 3. Check that the customer portal shows "Active".
325
- 4. Nothing to fix. The status follows the gateway and becomes "Active" when the gateway starts billing.
326
-
327
- ### Code reference
328
-
329
- Paths are relative to `fluent-cart/`. Each gateway's own handling lives in its `Processor` / `Confirmations` classes.
330
-
331
- | What | Where |
332
- | --- | --- |
333
- | First payment vs renewal, simulated trial decision | `app/Helpers/CheckoutProcessor.php` · `convertToSubscriptionFormat()` (config flag `is_trial_days_simulated`) |
334
- | Discounts that lower the first payment (coupon, `prorate_credit`, `upgrade_discount`) | `app/Helpers/CheckoutProcessor.php` discount total |
335
- | First-order-only shipping discount | `app/Helpers/CheckoutProcessor.php` (`billRenewalsFullShipping`) |
336
- | Simulated trial length, 365-day cap | `app/Helpers/Helper.php` · `calculateAdjustedTrialDaysForInterval()` |
337
- | Interval days | `app/Services/Payments/PaymentHelper.php` · `getIntervalDays()` |
338
- | Customer-facing status | `app/Models/Subscription.php` · `getOverriddenStatusAttribute()` |
339
- | Payment count sent to the gateway | `app/Models/Subscription.php` · `getInitialRemoteBillTimes()` |
340
- | Paid days left on reactivation | `app/Models/Subscription.php` · `getReactivationTrialDays()` |
341
- | $0 first period counting | `app/Helpers/CheckoutProcessor.php` · `syncInitialCycleCounting()` (`billed_cycles_offset`) |
342
- | Store-managed first status | `app/Helpers/StatusHelper.php` |
343
- | "Free Trial" label | `app/Helpers/Helper.php` · `generateTrialInfo()` |
344
- | Reminders | `app/Services/Reminders/ReminderService.php` |
345
- | Reports ("discounted") | `app/Services/Report/SubscriptionReportService.php` |
346
- | Upgrade credit and real trials | `app/Services/PlanUpgradeService.php` |
347
- | Admin list status | `resources/admin/Modules/Subscriptions/Components/SubscriptionsTable.vue` (raw `status`) |
348
- | Portal status | `resources/public/customer-profile/Vue/parts/SubscriptionTable.vue` (`overridden_status`) |
349
-
350
- ## Store-managed: the renewal engine (`manual` + `system`)
351
-
352
- FluentCart owns the schedule. One hourly cron drives everything.
353
-
354
- ### The cron
355
-
356
- `fluent_cart/scheduler/hourly_tasks` (Action Scheduler, 3600s) → `RenewalScheduler::handle()`, which does exactly two things — generate renewals coming due, and escalate renewals that were not paid. Batch size **20 each, per hour**.
357
-
358
- ### Generating the renewal
359
-
360
- `RenewalService::processDueSubscriptions()` selects renewal-engine subscriptions whose `next_billing_date` falls inside an **advance window** — the renewal is created *before* it is due:
361
-
362
- | Interval | Advance days | Grace days |
363
- | --- | --- | --- |
364
- | daily | 0 | 1 |
365
- | weekly | 3 | 3 |
366
- | monthly | 7 | 7 |
367
- | quarterly / half-yearly / yearly | 15 | 15 |
368
-
369
- (Advance: `getAdvanceCreationDaysMap()`. Grace: `SubscriptionHelper::getSubscriptionsGracePeriodDays()`. Both filterable — see [Hook inventory](#hook-inventory).)
370
-
371
- `createRenewalOrders()` takes a MySQL advisory lock (`GET_LOCK('fc_renewal_{sub_id}')`), re-checks that no open renewal exists, and creates a child `Order` inside a transaction:
372
-
373
- - `type = renewal`, `parent_id` = parent order, `status = pending`
374
- - **`payment_status` = `payment_scheduled` if the subscription `isSystem()`, else `pending`** — this single line is the fork between the two store-managed modes
375
- - order meta **`due_date` = the subscription's `next_billing_date`** — the anchor for every downstream dunning calculation
376
- - a pending `OrderTransaction`
377
-
378
- Then:
379
-
380
- - **`manual`** → fires `fluent_cart/renewal_created` → the customer gets a renewal email with a Pay Now link.
381
- - **`system`** → fires `fluent_cart/subscriptions/system_renewal_scheduled` and calls `SystemChargeService::scheduleCharge()`. **No email.** The customer is not asked to pay something that is about to be charged.
382
-
383
- ### Reminders
384
-
385
- A separate subsystem (`RenewalReminderService`), **off by default** (`reminders_enabled` / `renewal_reminders_enabled` both default `no`).
386
-
387
- Anchored on `due_date`: one reminder at the due date, then overdue reminders at **1, 3, 7 days** past it (filterable). It deliberately skips system renewals that are still waiting on their scheduled charge.
388
-
389
- ### Dunning — past_due, then expired
390
-
391
- `processOverdueRenewals()` walks unpaid renewals (`pending` or `payment_scheduled`) and computes `renewalAge = now - due_date` in days:
392
-
393
- ```
394
- renewalAge >= 0 and status ∈ [active, trialing] → past_due
395
- renewalAge >= graceDays and status == past_due → expired
396
- ```
397
-
398
- **It takes two cron passes to expire** — active → past_due, then (grace elapsed) past_due → expired. Expiry calls `syncSubscriptionStates(['status' => expired, 'next_billing_date' => null])`.
399
-
400
- The scanner stands down for a system subscription whose charge engine still owns the renewal — either an async charge is settling, or an attempt is still queued (`hasQueuedCharge()`). **A queued retry suppresses expiry**, so a subscription can never die out from under an armed charge.
401
-
402
- ### Paying — the Pay Now path
403
-
404
- `StatusHelper::syncOrderStatuses()` is the order-side chokepoint. It derives payment status from transaction rows, and **atomically claims** the `→ paid` transition with a conditional UPDATE. If another process (webhook vs. browser confirmation) already claimed it, this one returns early. That claim is what makes the renewal-paid hook fire exactly once:
405
-
406
- ```
407
- // StatusHelper — the ONLY fire site for fluent_cart/renewal_paid
408
- if ($this->order->type === Status::ORDER_TYPE_RENEWAL
409
- && $oldPaymentStatus !== $this->order->payment_status
410
- && $this->order->payment_status === Status::PAYMENT_PAID) {
411
- do_action('fluent_cart/renewal_paid', ['order' => $this->order]);
412
- }
413
- ```
414
-
415
- Edge-triggered: `renewal && (pending|payment_scheduled|failed) → paid`. Two listeners: `RenewalService::handleRenewalPaid()` (priority 10) and `SystemChargeService::cancelPendingCharge()` (priority 20 — paying early cancels the queued charge).
416
-
417
- **`handleRenewalPaid()`** is where a store-managed renewal completes:
418
-
419
- - Idempotent via a `renewal_processed` order meta flag.
420
- - **Cadence-preserving `next_billing_date`:** paid on or before the due date → `due_date + interval` (the schedule does not drift). Paid late → `now + interval`.
421
- - Accepts an **`expired`** subscription and brings it back — a late payment revives.
422
- - Calls `syncSubscriptionStates()`, then dispatches `SubscriptionRenewed` — unless the sync just completed the subscription (EOT), in which case it returns first.
423
-
424
- ### Which gateways appear on a renewal or reactivation
425
-
426
- The same `SubscriptionGatewayGate` handles these, but the decision comes from the *subscription* — its `collection_method` and how it was **born** (the `management_mode` stamp) — never from the store's current setting for an already-stamped subscription. Nothing in the renewal engine gates the list separately.
427
-
428
- | Subscription | Gateways offered |
429
- | --- | --- |
430
- | `automatic` | Gateways with `subscriptions` only — it owns a vendor schedule, and a one-time gateway would strand it. Ignores the `subscription_manual_fallback` setting |
431
- | `manual`, unstamped, store `gateway_managed`, invoice **not yet due** | One-time gateways only — see below |
432
- | `manual`, unstamped, store `gateway_managed`, invoice **due or overdue** | The conversion window: capable gateways offered, and paying through one converts the subscription to `automatic` |
433
- | `manual` stamped `store_managed`, or unstamped while the store is store-managed today | One-time only: `manual_subscription` gateways plus gateways with no `subscriptions` support. Never converts |
434
- | `system` | Same one-time-only list; no conversion path exists for `system` at all |
435
-
436
- Whatever survives is reordered so the subscription's `current_payment_method` renders first. A cart naming a subscription that cannot be resolved is left **ungated** — there is nothing to reason about, and the charge itself fails safely with `no_subscription` before any gateway API call.
437
-
438
- #### Why an early renewal payment is restricted
439
-
440
- Renewal invoices are generated days *ahead* of their due date so the customer has time to pay, and `handleRenewalPaid()` anchors the next date to `due_date` when they pay on or before it — the cadence is preserved and the advance days are honoured.
441
-
442
- The legacy manual→automatic conversion cannot honour them. It creates a vendor subscription anchored to **now** (no trial anchor is set unless the plan itself carries trial days), so an early payer is charged immediately and their `next_billing_date` is reset to `today + interval`, forfeiting every day between now and the original due date. So the gate closes that window until the due date arrives, when there is nothing left to lose.
443
-
444
- Two consequences worth knowing:
445
-
446
- - The restriction uses a strict "no `subscriptions` support" test, not the store-billed list above. Stripe and PayPal declare `manual_subscription`, but the one-time routing that flag implies does not apply to an unstamped `manual` subscription on a gateway-managed store — `shouldChargeSubscriptionAsOneTime()` returns `false` there, so they would still take the subscription route and convert.
447
- - If such a store has no one-time gateway active, that one checkout renders **no** payment methods. Deliberate: the customer pays from the due date onward instead of silently losing days.
448
-
449
- A reactivation rarely hits this rule — a reactivation cart only reaches checkout when payment is already due, so its invoice is not in advance.
450
-
451
- ## Store-managed + auto-charge (`system`)
452
-
453
- Everything above still applies. `system` adds a saved token and an automatic charge per renewal. Same renewal engine, same dunning, same admin actions — it just tries to pay the renewal for the customer first.
454
-
455
- ### Token storage — no new table
456
-
457
- ```
458
- customer id (cus_…) → fct_subscriptions.vendor_customer_id (existing column)
459
- token (pm_…) → active_payment_method SubscriptionMeta (existing key)
460
- ```
461
-
462
- **Two shapes in the wild.** `active_payment_method` is written top-level (`vendor_method_id`) by the checkout/confirmation paths, but nested (`details.payment_method_id`) by the card-update/switch-payment-method flow. **Every reader must check both** — e.g. `Arr::get($meta, 'vendor_method_id') ?: Arr::get($meta, 'details.payment_method_id')`. A single-shape read risks re-persisting a stale token or wrongly demoting a subscription whose current token came from a card update.
463
-
464
- At checkout the first payment is a **one-time charge that also vaults the method** — not a vendor subscription. On **Stripe** that is a PaymentIntent with `setup_future_usage = off_session`; on **PayPal** the initial capture is taken vault-enabled and the resulting token is stored the same way (later charged via `Processor::chargeVaultedRenewal()`). The card is saved with explicit consent copy. **The token is read at charge time, never snapshotted** into the scheduled action, so a card updated mid-dunning is picked up by the next retry automatically.
465
-
466
- **Webhook fallback for vaulting.** The zero-payable trial SetupIntent confirm normally completes via AJAX. If that call is lost (network drop, closed tab), the `setup_intent.succeeded` webhook recovers it — same write path, same demote-to-manual fallback if the gateway returns no token. Self-idempotent: a duplicate/late webhook after the AJAX call already succeeded fails its `vendor_charge_id` lookup and no-ops.
467
-
468
- ### The charge lifecycle
469
-
470
- The gateway contract is two methods on `AbstractPaymentGateway`, both defaulting to `WP_Error('not_supported')` so a capability/implementation mismatch degrades instead of fataling:
471
-
472
- | Method | Returns |
473
- | --- | --- |
474
- | `chargeRenewal(PaymentInstance, $args)` | `true` \| `'processing'` \| `WP_Error` |
475
- | `reconcileRenewalCharge(PaymentInstance)` | same three |
476
-
477
- Stripe's implementation is a PaymentIntent with `customer` + `payment_method` + `off_session: true, confirm: true`, keyed `Idempotency-Key: fct_system_charge_{order_id}_{attempt}`.
478
-
479
- ### Retries are anchored to the grace period, not to fixed days
480
-
481
- ```
482
- offsets = [0.25, 0.6, 0.9] × graceDays → 3 retries + the due-date attempt = 4 total
483
- ```
484
-
485
- | Interval | Grace | Attempt 1 | Retries |
486
- | --- | --- | --- | --- |
487
- | daily | 1 day | due date | +6h, +14.4h, +21.6h |
488
- | weekly | 3 days | due date | +0.75d, +1.8d, +2.7d |
489
- | monthly | 7 days | due date | +1.75d, +4.2d, +6.3d |
490
- | quarterly / yearly | 15 days | due date | +3.75d, +9d, +13.5d |
491
-
492
- The first attempt always fires **on the due date itself** — no grace maths touches it. Only the retries scale.
493
-
494
- Why not fixed days? Because the grace period is per-interval, so a fixed schedule delivers a *different number of retries per interval*. Anchoring to grace guarantees all intervals land their retries inside the dunning window.
495
-
496
- Two invariants hold the schedule and the scanner together:
497
-
498
- - The overdue scanner **will not expire a subscription while an attempt is queued**, so even a filter that pushes an offset past the grace period cannot kill a subscription mid-retry.
499
- - Offsets are sorted, and **truncated to `MAX_ATTEMPT_SLOTS - 1`**. Attempt numbers key both the scheduler lookups and the gateway idempotency key, so an attempt scheduled outside the swept slot range would be invisible to `hasQueuedCharge()` and `unscheduleCharges()` — left armed to charge a renewal that had already been paid or voided.
500
-
501
- The retry offsets are filterable (`fluent_cart/subscriptions/system_charge_retry_offsets`), and the charge-failed email defaults to **first failure only** so retries don't spam the customer.
502
-
503
- ### Admin-triggered charges — off the scheduler
504
-
505
- Two admin actions charge on demand, both through `SystemChargeService::chargeNow()` — one immediate off-session attempt that first **unschedules the queued due-date attempt**, so the manual and automatic charge can never both run:
506
-
507
- - **Charge Now** charges an *existing* open renewal. Gated `canChargeNow`: `system`, open renewal exists, chargeable status, not currently settling (`processing`). After exhaustion the click clears `exhausted`, runs one attempt, and re-records exhaustion on a fresh failure — no ladder restart, nothing re-queued.
508
- - **Charge Next Renewal Now** is the create-renewal action (`SubscriptionController::createRenewalNow()`) on a `system` sub: `createRenewalOrders()` **then** `chargeNow()` on the fresh renewal, in one call. Manual subs take the create-only branch (pay-now email, no charge). Gated `canCreateRenewal` (`usesRenewalEngine()` + active/trialing + `next_billing_date` + **no** open renewal), so it and Charge Now are mutually exclusive by open-renewal state.
509
-
510
- A decline returns `status = 'failed'` (HTTP 200) and drops the renewal onto the normal retry/dunning ladder; a state violation returns `WP_Error`.
511
-
512
- ### Losing the capability — demotion to `manual`
513
-
514
- `collection_method` is resolved once, at checkout. But `current_payment_method` can move afterwards — most commonly when a customer pays a **failed** renewal with a **different gateway** via Pay Now. That is a one-off renewal payment; no vendor subscription is created. The subscription is now `system` on a gateway that cannot token-charge.
515
-
516
- `SystemChargeService::reconcileGatewayCapability()` runs from `syncSubscriptionStates()` whenever `current_payment_method` comes back dirty. If the new gateway lacks `system_subscription`, `demoteToManual()` hands the subscription back to plain manual invoicing: flip `collection_method`, drop `system_charge_state`, unschedule queued attempts, release any waiting renewal to `pending` **with the pay-now email that was previously withheld**, log it, and fire `system_charge_disabled`.
517
-
518
- A second trigger fires **at initial checkout**: if the first capture returns no vaultable token at all (Stripe: no `payment_method` on the response; PayPal: capture isn't vault-enabled), the confirmation path demotes immediately rather than leaving a `system` subscription with nothing to charge.
519
-
520
- Manual is the floor
521
-
522
- In store-managed mode, `resolveCollectionMethodFor()` has no `automatic` branch. A store-managed subscription that loses auto-charge falls back to **manual invoicing** — it never falls back to gateway billing.
523
-
524
- ## The shared spine
525
-
526
- Both models write through the same two functions. This is why the lifecycle events fire consistently no matter how a subscription is billed.
527
-
528
- ### `syncSubscriptionStates()` — the subscription-side chokepoint
529
-
530
- `app/Modules/Subscriptions/Services/SubscriptionService.php`. Every meaningful subscription write funnels through it.
531
-
532
- 1. **Recomputes `bill_count` from the database** — counts succeeded charge transactions with `total > 0`, plus `early_payment_history`, plus a `billed_cycles_offset` meta, minus `billed_cycles_deduction`. **A caller-supplied `bill_count` is always overwritten.** The column is derived, never incremented.
533
- 2. **Owns the EOT rule:** `isEot = bill_times > 0 && bill_count >= bill_times` → forces `status = completed`, `next_billing_date = NULL`. (`bill_times = 0` means unlimited and never completes.)
534
- 3. Normalizes companion fields (`canceled_at`, `validity_expired_at`).
535
- 4. Captures the **dirty diff** before saving — that diff is what the update hook publishes, and what triggers `reconcileGatewayCapability()` when `current_payment_method` changes.
536
- 5. Compares old status to new and dispatches lifecycle events **exactly once**.
537
-
538
- Two paths deliberately bypass it — admin **edit** and admin **reactivate** — precisely because step 1 would override an explicit admin choice. Both re-implement the event fan-out by hand.
539
-
540
- ### Events
541
-
542
- | Event | Fires when | Gateway-managed | Store-managed |
543
- | --- | --- | --- | --- |
544
- | `SubscriptionActivated` | First payment lands | ✅ | ✅ |
545
- | `SubscriptionRenewed` | A renewal is paid | ✅ via `recordRenewalPayment()` | ✅ via `handleRenewalPaid()` |
546
- | `SubscriptionCanceled` | Cancel | ✅ | ✅ |
547
- | `SubscriptionEOT` | `bill_count >= bill_times` | ✅ | ✅ |
548
- | `SubscriptionValidityExpired` | → expired | ✅ (+ expiry cron) | ✅ (via the overdue scanner) |
549
- | `SubscriptionReactivated` | canceled/expired → active | ✅ | ✅ |
550
- | `SubscriptionPaused` / `Resumed` | pause/resume | ✅ (gateway must support it) | ✅ (local, immediate) |
551
- | `SubscriptionUpdated` | Admin edits the terms | ❌ **never** | ✅ only |
552
- | `SubscriptionPeriodSkipped` | Admin skips a period | ❌ **never** | ✅ only |
553
- | `fluent_cart/subscription_past_due` | Renewal overdue | ❌ **never** | ✅ only |
554
- | `system_charge_failed` | Auto-charge declined | ❌ | ✅ `system` only |
555
-
556
- `SubscriptionEOT` has a `beforeDispatch()` that cancels the vendor subscription with `fire_hooks => false` — so ending a term tears down the gateway side **without** also emitting `SubscriptionCanceled`.
557
-
558
- See [Subscription action hooks](/hooks/actions/subscriptions.md) for payloads and priorities.
559
-
560
- ## What each model allows
561
-
562
- | Action | `automatic` | `manual` | `system` | Guard |
563
- | --- | --- | --- | --- | --- |
564
- | Cancel | ✅ (calls gateway) | ✅ (local) | ✅ (local) | — |
565
- | Fetch / resync from gateway | ✅ | ❌ | ❌ | `canFetch` |
566
- | Pause / Resume | ⚠️ gateway must support it | ✅ | ✅ | `canPause` / `canResume` |
567
- | **Edit terms** (amount, interval, bill_times, next date) | ❌ | ✅ | ✅ | `canUpdateDetails()` = `usesRenewalEngine()` |
568
- | **Reactivate** | ❌ | ✅ | ✅ | `usesRenewalEngine()` + `canReactivate()` |
569
- | **Create renewal now** | ❌ | ✅ (create + email) | ✅ **create + charge** | `canCreateRenewal` |
570
- | **Skip next period** | ❌ | ✅ | ✅ | `usesRenewalEngine()` |
571
- | **Charge an open renewal now** | ❌ | ❌ | ✅ (one off-session attempt) | `canChargeNow` |
572
- | Update card on file | ✅ | ✅ | ✅ | `canUpdatePaymentMethod()` |
573
- | **Switch gateway** | ✅ | ❌ | ❌ | `canSwitchPaymentMethod()` |
574
- | **[Edit vendor IDs](/modules/subscription-vendor-ids.md)** | ✅ opt-in | ❌ | ❌ | `canEditVendorIds()` — off unless `fluent_cart/subscription/vendor_id_editing_enabled` returns `true` |
575
- | Pay Now on an open renewal | n/a | ✅ | ✅ (cancels the queued charge) | — |
576
-
577
- Two asymmetries deserve explanation.
578
-
579
- **Pause on `automatic` is effectively dead.** The code requires the gateway to declare `pause_subscription` and implement `pause()`. **No shipped gateway does either.** An automatic subscription can only become `paused` by being paused at the gateway and having the status arrive by webhook.
580
-
581
- **Switching gateways is blocked for store-billed subscriptions** — and this is not a limitation, it's a correctness guard. "Switch payment method" does not change a card; both `StripeGateway/SwitchCustomerMethod` and `PayPalGateway/SubscriptionManager` **create a live vendor subscription** at the target gateway. On a subscription owned by the renewal engine, that gateway would start billing on its own schedule while FluentCart kept issuing renewals for the same periods — a **double bill**. Moving a store-billed subscription onto a gateway's billing engine is a *migration*, not a fallback, and is deliberately not implemented. Customers change the **card on file** instead.
582
-
583
- ## Hook inventory
584
-
585
- ### Shared
586
-
587
- | Hook | Fired at |
588
- | --- | --- |
589
- | `fluent_cart/scheduler/hourly_tasks` | Action Scheduler, hourly |
590
- | `fluent_cart/renewal_paid` | `StatusHelper` — **the only fire site** |
591
- | `fluent_cart/payments/subscription_status_changed` | `SubscriptionService` |
592
- | `fluent_cart/payments/subscription_{status}` | `SubscriptionService` (dynamic) |
593
- | `fluent_cart/subscription/data_updated` | `SubscriptionService` (dirty diff, no status change) |
594
- | `fluent_cart/subscription_collection_method_{gateway}` | filter — `CheckoutProcessor` |
595
- | `fluent_cart/subscription/management_mode` | filter — `SubscriptionManagementMode`, store-wide mode override |
596
- | `fluent_cart/checkout_active_payment_methods` | filter — `SubscriptionGatewayGate` gates every subscription cart here |
597
- | `fluent_cart/subscription/vendor_id_editing_enabled` | filter, default `false` — opt in to [editing vendor identifiers](/modules/subscription-vendor-ids.md) on an `automatic` subscription |
598
-
599
- ### Renewal engine
600
-
601
- | Hook | Purpose |
602
- | --- | --- |
603
- | `fluent_cart/renewal_created` | Renewal generated (drives the pay-now email) |
604
- | `fluent_cart/renewal_payment_scheduled` | Gateway deferred a charge → renewal flips to `payment_scheduled` |
605
- | `fluent_cart/subscription_past_due` | Overdue escalation (drives the past-due email) |
606
- | `fluent_cart/renewal_voided` | Admin voided a renewal |
607
- | `fluent_cart/renewal/advance_creation_days` | filter — the advance window map |
608
- | `fluent_cart/subscription/grace_period_days` | filter — the grace map |
609
-
610
- ### System charge
611
-
612
- | Hook | Params | Purpose |
613
- | --- | --- | --- |
614
- | `fluent_cart/subscriptions/system_renewal_scheduled` | `(['subscription','order','parent_order','customer','transaction'])` | System renewal created; charge queued, no pay-now email |
615
- | `fluent_cart/subscriptions/system_charge_due` | `($orderId, $attempt)` | The scheduled charge (Action Scheduler) |
616
- | `fluent_cart/subscriptions/system_charge_reconcile` | `($orderId)` | Daily re-check of an async charge |
617
- | `fluent_cart/subscriptions/system_charge_succeeded` | `(['order','subscription','attempt'])` | |
618
- | `fluent_cart/subscriptions/system_charge_failed` | `(['order','subscription','attempt','error','next_retry_at'])` | |
619
- | `fluent_cart/subscriptions/system_charge_failed_notification` | `([...])` | Drives the charge-failed emails |
620
- | `fluent_cart/subscriptions/system_charge_failure_notify` | filter, default `$attempt === 1` | Whether to email on this failure |
621
- | `fluent_cart/subscriptions/system_charge_disabled` | `(['subscription','reason'])` | Demoted to `manual` |
622
- | `fluent_cart/subscriptions/system_charge_retry_offsets` | filter — `($offsets, ['subscription','grace_days'])` | Retry schedule, in days after the due date |
623
- | `fluent_cart/subscriptions/system_collection_enabled` | filter — `($enabled)` | Store-wide override of the auto-charge setting |
624
- | `fluent_cart/subscriptions/system_billing_enabled` | filter, default `true` | Env kill switch — return `false` (e.g. on a staging clone) to stop all system billing |
625
-
626
- Stripe webhook events are merchant-configured
627
-
628
- `Webhook::getEvents()` is the source of truth for which Stripe dashboard events are consumed (including `setup_intent.succeeded`). Any event added to the accepted-events list must also land in `getEvents()` and the setup instructions, or the merchant never enables it in their dashboard and the handler is unreachable.
629
-
630
- ## Known gaps
631
-
632
- Recorded so nobody rediscovers them the hard way.
633
-
634
- - **An ambiguous transport failure can double-charge a `system` renewal.** The Stripe idempotency key is `fct_system_charge_{order_id}_{attempt}` — it includes the attempt number, so a charge that *succeeded* but whose response was lost gets re-charged under a fresh key on the next retry. A per-renewal key would fix it, at the cost of per-attempt replay protection.
635
- - **Stripe's `invoice.payment_failed` is not handled.** It is advertised in the webhook setup instructions but absent from the accepted-events list, so it returns 200 and does nothing. Payment failure on a gateway-managed subscription is learned indirectly, via `customer.subscription.updated` → `past_due` → local `expiring`.
636
- - **`pause_subscription` is declared by no gateway and implemented by none** — pausing an `automatic` subscription from FluentCart always fails.
637
- - **The final installment of a store-billed subscription emits `SubscriptionEOT` but no `SubscriptionRenewed`** (`handleRenewalPaid` returns early once the sync marks it `completed`).
638
- - **A lost Action Scheduler job** leaves a system renewal sitting in `payment_scheduled` with its reminders suppressed. The overdue scanner still escalates it once the due date passes, so it is not stranded — just quiet until then.
639
- - **`store_managed` does not fully stop a gateway schedule for an `automatic` subscription.** The gate admits Stripe and PayPal on a store-managed cart because they declare `manual_subscription`, on the assumption they will take a single charge — but that one-time routing only applies to `manual` and `system` subscriptions. An `automatic` subscription paid through them still gets a vendor schedule. Closing it means widening the one-time rule itself, not the gate.
640
-
641
- ## Quick reference
642
-
643
- **Am I looking at a store-managed subscription?** `$subscription->usesRenewalEngine()` — not `isManual()`, which means strictly `manual` and excludes `system`.
644
-
645
- **Where does a renewal come from?**
646
-
647
- - `automatic` → a webhook, reactively → `recordRenewalPayment()`
648
- - `manual` / `system` → the hourly cron, proactively → `processDueSubscriptions()`
649
-
650
- **Who advances `next_billing_date`?**
651
-
652
- - `automatic` → the gateway (copied from its payload)
653
- - `manual` / `system` → `handleRenewalPaid()`, cadence-preserving
654
-
655
- **Why isn't my subscription renewing?**
656
-
657
- - `automatic` → check the webhook actually arrived; the expiry safety-net cron is what eventually marks it expired
658
- - `manual` / `system` → check `next_billing_date`, the advance window, and whether an open renewal already exists (the engine will not create a second one)
659
-
660
- **Why is a `system` subscription not auto-charging?** Check `collection_method` — it may have been **demoted to `manual`** because the gateway on file changed (look for a `system_charge_disabled` activity log entry). Also check `system_charge_state` meta for `exhausted`.
661
-
662
- ## Related Documentation
663
-
664
- - [Subscription Model](/database/models/subscription.md) — attributes, scopes, methods
665
- - [Subscription Meta](/database/models/subscription-meta.md) — where tokens and system-charge state are stored
666
- - [Subscription Action Hooks](/hooks/actions/subscriptions.md) — lifecycle event payloads
667
- - [Subscription Filter Hooks](/hooks/filters/customers-and-subscriptions.md) — advance window, grace, retry offsets
668
- - [Subscriptions API](/api/subscriptions.md) — admin and customer REST endpoints
669
- - [Editing Vendor IDs](/modules/subscription-vendor-ids.md) — opt-in repair of `vendor_subscription_id` / `vendor_customer_id`
670
- - [Payment Methods Module](/modules/payment-methods.md) — the gateway architecture subscriptions build on
671
-
672
- ---
673
-
674
- **Next Steps:**
675
-
676
- - [Payment Methods Module](./payment-methods.md) — gateway development and the capability system
677
- - [Custom Payment Gateway](/payment-methods-integration/) — implement `chargeRenewal()` for system charges
678
- - [Modules Overview](./index.md) — back to modules overview
1
+ # Subscriptions Module
2
+
3
+ FluentCart's subscription engine bills recurring products through **two competing models** — one where the payment gateway owns the schedule, and one where FluentCart owns it — unified behind a single database column and a single shared write-spine. This document is the architectural map: how the model is chosen, what machinery each one uses, and where they converge.
4
+
5
+ Where subscriptions live
6
+
7
+ | Concern | Location |
8
+ | --- | --- |
9
+ | Model + attributes | [`Subscription` model](/database/models/subscription.md) · [`SubscriptionMeta`](/database/models/subscription-meta.md) |
10
+ | Lifecycle hooks | [Action hooks](/hooks/actions/subscriptions.md) · [Filter hooks](/hooks/filters/customers-and-subscriptions.md) |
11
+ | REST endpoints | [Subscriptions API](/api/subscriptions.md) · [REST operations](/restapi/subscriptions.md) |
12
+ | Core code | `app/Modules/Subscriptions/` · `app/Modules/StoreManagedRenewal/` |
13
+
14
+ ## The one idea
15
+
16
+ Every subscription answers a single question: **who owns the billing schedule — the payment gateway, or FluentCart?**
17
+
18
+ That answer is the `fct_subscriptions.collection_method` column, and it decides everything downstream: whether a renewal is a webhook you receive or a renewal you generate, whether dunning is Stripe's retry ladder or FluentCart's grace period, whether an admin can edit the recurring amount.
19
+
20
+ | `collection_method` | Who bills | Renewal arrives as | Dunning owned by |
21
+ | --- | --- | --- | --- |
22
+ | `automatic` | The **gateway**, via a vendor subscription object (Stripe `sub_…`, PayPal `I-…`) | An inbound **webhook** | The gateway |
23
+ | `manual` | **FluentCart**, via the renewal engine; the customer pays each renewal by hand | A **renewal** you generate on a cron | FluentCart (reminders → past_due → expired) |
24
+ | `system` | **FluentCart**, via the renewal engine; a saved token is charged automatically | A **renewal** you generate, then charge off-session | FluentCart (retries → past_due → expired) |
25
+
26
+ `manual` and `system` are the **same engine**. `system` just adds a saved payment method and an automatic charge attempt per renewal. The predicate that groups them is `Subscription::usesRenewalEngine()` — **that method, not `collection_method` itself, is the real store-managed test**, and it appears as a guard throughout the codebase.
27
+
28
+ **Reading by type:** `automatic` → [Gateway-managed](#gateway-managed-automatic). `manual` → [the renewal engine](#store-managed-the-renewal-engine-manual-system) (it is the base — there is no separate "manual" section). `system` → the renewal engine **plus** [the auto-charge delta](#store-managed-auto-charge-system). [The capability matrix](#what-each-model-allows) compares all three side by side.
29
+
30
+ ## How the method is decided
31
+
32
+ Exactly one place, exactly once — at checkout. `CheckoutProcessor::determineCollectionMethod()`:
33
+
34
+ Two inputs: a **store setting** and a **gateway capability**.
35
+
36
+ ### The setting
37
+
38
+ `SubscriptionManagementMode` (`app/Modules/Subscriptions/Services/SubscriptionManagementMode.php`) reads from the `fluent_cart_store_settings` option blob, rendered on the Subscriptions settings tab and sanitized by whitelist in the meta request.
39
+
40
+ | Key | Values | Default |
41
+ | --- | --- | --- |
42
+ | `subscription_management_mode` | `gateway_managed` \| `store_managed` | `gateway_managed` |
43
+ | `subscription_system_charge` | `yes` \| `no` | `no` |
44
+ | `subscription_manual_fallback` | `yes` \| `no` | `no` |
45
+
46
+ `subscription_system_charge` is inert under `gateway_managed` — `isSystemChargeEnabled()` returns `false` outright unless the mode is store-managed.
47
+
48
+ `subscription_manual_fallback` is inert under `store_managed` — `isManualFallbackEnabled()` returns `false` outright unless the mode is gateway-managed. When on, gateways without `subscriptions` support are offered on a gateway-managed subscription cart instead of being hidden, and the resulting subscription is created with `collection_method = manual` — invoiced by FluentCart, paid by hand each cycle.
49
+
50
+ ### The full decision matrix
51
+
52
+ | Mode | System charge | Gateway | Result |
53
+ | --- | --- | --- | --- |
54
+ | gateway_managed | (ignored) | has `subscriptions` | `automatic` |
55
+ | gateway_managed, manual fallback **on** | (ignored) | no `subscriptions` (COD, bank transfer) | `manual` |
56
+ | store_managed | off | any | `manual` |
57
+ | store_managed | on | has `system_subscription` (Stripe, PayPal) | `system` |
58
+ | store_managed | on | no `system_subscription` (COD, bank transfer…) | `manual` |
59
+
60
+ A per-gateway filter gets the last word: `fluent_cart/subscription_collection_method_{gateway}`.
61
+
62
+ Both Stripe and PayPal do `system`
63
+
64
+ Off-session auto-charge is the `system_subscription` capability, and **both Stripe and PayPal declare it** (each overrides `chargeRenewal()` / `reconcileRenewalCharge()`). The Stripe-only axis is a *narrower* one — `zero_recurring` / `supportsSetupWithoutCharge()`, the ability to vault a card at **$0 on a free-trial cart**. PayPal must take a payable-now charge to vault its token, so it can run `system` on a paid-now cart but **cannot start a `system` sub from a $0 trial**.
65
+
66
+ ### The durable stamp — why flipping the setting is safe
67
+
68
+ A store-managed subscription also gets `config['management_mode'] = 'store_managed'` written onto its row.
69
+
70
+ This exists because **payment paths must consult the stamp, not the live setting**. Gateways contain legacy logic that converts a `manual` subscription to `automatic` when it is paid through a subscription-capable gateway. Without the stamp, a merchant who flipped back to `gateway_managed` would silently convert every store-managed subscription into a vendor subscription the next time a customer paid a renewal.
71
+
72
+ An unstamped `manual` subscription — one born on a gateway-managed store — can still convert, and that is intentional. When it may is covered under [which gateways appear on a renewal](#which-gateways-appear-on-a-renewal-or-reactivation).
73
+
74
+ `AbstractPaymentGateway::shouldChargeSubscriptionAsOneTime()` is the enforcement point:
75
+
76
+ - `automatic` subscription → `false` (keeps billing at the vendor, untouched by a flip to store-managed)
77
+ - **stamped** store-managed subscription → `true` **regardless of the current setting** — it can never be converted
78
+ - unstamped `manual` (pre-feature legacy) → follows the live setting
79
+
80
+ The single most important invariant
81
+
82
+ **Flipping the mode affects new checkouts only.** No existing subscription ever changes its billing model.
83
+
84
+ ### Gateway capability flags
85
+
86
+ Declared as `$supportedFeatures` on each gateway; tested with `AbstractPaymentGateway::has()`.
87
+
88
+ | Gateway | `subscriptions` | `manual_subscription` | `system_subscription` | `zero_recurring` | `switch_payment_method` | `card_update` |
89
+ | --- | --- | --- | --- | --- | --- | --- |
90
+ | **Stripe** | ✅ | ✅ | ✅ | ✅ **(only one)** | ✅ | ✅ |
91
+ | **PayPal** | ✅ | ✅ | ✅ | — | ✅ | ✅ |
92
+ | COD / offline | — | — | — | — | — | — |
93
+ | Authorize.net, Mollie, Paddle (pro) | ✅ | ✅ | — | — | — | Paddle only |
94
+ | Square, Paystack, Flutterwave, Razorpay (addons) | ✅ | — | — | — | — | — |
95
+ | MercadoPago, SSLCommerz (addons) | — | ✅ | — | — | — | — |
96
+
97
+ `zero_recurring` (backed by `supportsSetupWithoutCharge()`) is what lets a gateway vault a card at **$0** — the free-trial `system` case. Only Stripe has it; PayPal does `system` but only when the cart charges something now.
98
+
99
+ `manual_subscription` is independent of `system_subscription` — it only claims a gateway routes a store-managed subscription's first payment through its existing one-time-charge path instead of creating a vendor subscription (`shouldChargeSubscriptionAsOneTime()`, below). COD/offline don't need it: `storeBilledOnly()` already admits them via `has('offline')` / `!has('subscriptions')`. MercadoPago and SSLCommerz declare it anyway even though the same `!has('subscriptions')` short-circuit already admits them — it's redundant, not load-bearing.
100
+
101
+ A seventh flag, `verify_vendor_ids`, is unrelated to billing: it claims the gateway can look a subscription id up read-only, which the [vendor-id repair tool](/modules/subscription-vendor-ids.md) uses to preview a correction before it is saved. Only Stripe and PayPal declare it; every other gateway inherits `AbstractSubscriptionModule::verifyVendorSubscription()`, which returns `not_implemented`.
102
+
103
+ The actual admit/hide decision for store-managed checkout lives in `SubscriptionGatewayGate::storeBilledOnly()` (`app/Modules/Subscriptions/Services/SubscriptionGatewayGate.php`):
104
+
105
+ ```
106
+ return $gateway->has('offline')
107
+ || !$gateway->has('subscriptions')
108
+ || $gateway->has('manual_subscription');
109
+ ```
110
+
111
+ A gateway is eligible if it's offline, or doesn't declare `subscriptions` at all, or declares `subscriptions` **and** `manual_subscription`. That third branch is the only case where `manual_subscription` changes anything — it's what lets Stripe/PayPal/Authorize.net/Mollie/Paddle (subscription-capable gateways) also be offered on a store-managed cart instead of being excluded.
112
+
113
+ Two traps worth knowing:
114
+
115
+ 1. **`has('subscriptions')` is auto-appended** by the constructor whenever a subscription module is injected — so the literal `$supportedFeatures` array under-reports it.
116
+ 2. **`has('switch_payment_method')` always returns `false`.** It is an *associative* entry, and `has()` does `in_array` over values. Every call site reads it with `Arr::get($gateway->supportedFeatures, 'switch_payment_method')` instead.
117
+
118
+ ### `manual_subscription` — wiring a third-party gateway for store-managed billing
119
+
120
+ A gateway earns `manual_subscription` by proving it can take a subscription's first payment as a plain one-time charge, with no vendor subscription object created. Two changes, both in the gateway class:
121
+
122
+ 1. Add `'manual_subscription'` to `$supportedFeatures`.
123
+ 2. In `makePaymentFromPaymentInstance()`, consult `shouldChargeSubscriptionAsOneTime()` **before** any vendor-subscription/conversion logic, routing to the gateway's existing single-payment path when it returns `true`:
124
+
125
+ ```
126
+ // AuthorizeDotNet.php — makePaymentFromPaymentInstance()
127
+ if ($this->shouldChargeSubscriptionAsOneTime($paymentInstance)) {
128
+ return (new AuthorizeDotNetProcessor($this->authorizeSettings))->handleSinglePayment($paymentInstance);
129
+ }
130
+ ```
131
+
132
+ That's the whole pattern — Mollie and Paddle (fluent-cart-pro) mirror it, each calling their own existing `handleSinglePayment()`. Don't add `system_subscription` alongside it unless the gateway also overrides `chargeRenewal()` / `reconcileRenewalCharge()` — `manual_subscription` alone only unlocks the non-zero-payable case; a gateway with no auto-charge implementation correctly stays hidden on $0-due carts.
133
+
134
+ ### Which gateways appear on a new subscription cart
135
+
136
+ `SubscriptionGatewayGate` capability-gates the payment methods on every subscription cart, on `fluent_cart/checkout_active_payment_methods`. It is the only filter on that list. **Both modes gate, in opposite directions** — store-managed keeps schedule-owning gateways out, gateway-managed keeps them in.
137
+
138
+ | Mode | Amount due today | Gateways offered |
139
+ | --- | --- | --- |
140
+ | `gateway_managed` | any | Gateways **with** `subscriptions` only — a gateway-managed store has no renewal engine, so a subscription needs a gateway that can run its own schedule. Turn on the `subscription_manual_fallback` setting (default `no`) and gateways without it are offered again, billing `manual` |
141
+ | `store_managed` | > 0 | Gateways **without** `subscriptions` (COD, bank transfer, MercadoPago, SSLCommerz) — they can't auto-bill anyway — **plus** `manual_subscription` gateways (Stripe, PayPal, Authorize.net, Mollie, Paddle), which take a single charge here because `shouldChargeSubscriptionAsOneTime()` forces it. Vendor-billing-only gateways hidden |
142
+ | `store_managed`, auto-charge **on** | 0 (free trial) | Offline methods, plus a `system_subscription` gateway that can vault without charging (`supportsSetupWithoutCharge()`) — Stripe in `onsite` mode, PayPal in `paypal_pro` mode. Either gateway in another checkout mode drops off |
143
+ | `store_managed`, auto-charge **off** | 0 (free trial) | Offline methods only — nothing would ever charge a saved token |
144
+
145
+ Admission under `store_managed` is deliberately **opt-in**: a gateway is shown only when it is known not to run its own schedule. An unrecognised third-party gateway is hidden rather than trusted, because a gateway that creates a vendor subscription inside its own payment flow would bill in parallel with the renewals the engine generates.
146
+
147
+ Renewal and reactivation carts follow the *subscription*, not the store setting — see [which gateways appear on a renewal](#which-gateways-appear-on-a-renewal-or-reactivation).
148
+
149
+ **None of this is a security boundary.** The same filter re-runs server-side against the single posted gateway at order placement and returns `423` on a mismatch, so hiding a method in the UI is not what enforces it.
150
+
151
+ ## Gateway-managed (`automatic`)
152
+
153
+ FluentCart hands the schedule to the gateway and becomes a mirror.
154
+
155
+ ### Creation
156
+
157
+ The three subscription-capable gateways behave differently at creation — a critical detail, because two of them produce the `vendor_subscription_id` asynchronously:
158
+
159
+ WARNING
160
+
161
+ Any code that assumes `vendor_subscription_id` exists right after checkout is wrong for **two of the three** gateways.
162
+
163
+ ### Renewal — the gateway tells you
164
+
165
+ All webhooks enter at `?fluent-cart=fct_payment_listener_ipn&method={slug}` → `GlobalPaymentHandler` → `$gateway->handleIPN()`.
166
+
167
+ | Gateway | Renewal event | Handler |
168
+ | --- | --- | --- |
169
+ | Stripe | `invoice.paid` with `billing_reason = subscription_cycle` | `Webhook::processSubscriptionRenewal()` |
170
+ | PayPal | `PAYMENT.SALE.COMPLETED` **with** `billing_agreement_id` | `IPN::processRecurringPaymentReceived()` |
171
+ | Paddle | `subscription.payment_received` | Re-syncs from remote, which then records the payment |
172
+
173
+ All three converge on **`SubscriptionService::recordRenewalPayment()`**:
174
+
175
+ 1. Takes a MySQL lock on `fc_webhook_{vendor_charge_id}` and checks for an existing transaction — **idempotency**, because gateways retry webhooks.
176
+ 2. **If a pending renewal already exists for the parent order, it settles that renewal** instead of creating a new order. This is the seam where a converted subscription's renewal gets closed out by a gateway webhook.
177
+ 3. Otherwise creates a child renewal `Order` (`type = renewal`, `parent_id` = the parent order) + `OrderItem` + a succeeded `OrderTransaction`.
178
+ 4. Calls `syncSubscriptionStates()` with the gateway's own data.
179
+ 5. Dispatches `SubscriptionRenewed`.
180
+
181
+ **`next_billing_date` is copied from the gateway** (`current_period_end`, `billing_info.next_billing_time`, `next_billed_at`) — never computed locally. `guessNextBillingDate()` is only a fallback for when the gateway supplies nothing.
182
+
183
+ ### Status sync
184
+
185
+ Gateway-side changes (canceled, past_due, paused) reach the local row two ways:
186
+
187
+ - **Webhooks:** `customer.subscription.updated` / `.deleted` (Stripe), `BILLING.SUBSCRIPTION.*` (PayPal), `subscription.updated|past_due|paused|resumed` (Paddle).
188
+ - **`Subscription::reSyncFromRemote()`** — pull, not push. Called by the webhook handlers, and by the admin **Fetch** button (`SubscriptionController::fetchSubscription()`), gated on `canFetch` = not renewal-engine + has a vendor id.
189
+
190
+ Status mapping is per-gateway and **not** one-to-one. Stripe's (`StripeHelper::transformSubscriptionStatus()`):
191
+
192
+ | Stripe | FluentCart | Note |
193
+ | --- | --- | --- |
194
+ | `active` | `active` | |
195
+ | `trialing` | `trialing` | |
196
+ | `incomplete`, `incomplete_expired` | `intended` | |
197
+ | **`past_due`** | **`expiring`** | not `past_due`! That local status is store-managed-only |
198
+ | `unpaid` | `expired` | |
199
+ | `canceled` | `canceled` | → `expired` if `cancellation_details.reason = payment_failed` |
200
+ | `paused` | `paused` | |
201
+
202
+ ### What gateway-managed does **not** do locally
203
+
204
+ This is the cleanest way to understand the split:
205
+
206
+ 1. **The renewal cron never touches it.** Every query in `RenewalService` is `whereIn('collection_method', ['manual','system'])`. No renewal order is pre-created; it appears reactively when the webhook lands.
207
+ 2. **No local dunning or retries.** Retry ladders are the gateway's. FluentCart mirrors the resulting status.
208
+ 3. **The recurring amount is not editable** — `canUpdateDetails()` is renewal-engine-only, and `recurring_total` is overwritten from the gateway's plan amount on every sync.
209
+ 4. **The one local cron that does touch it** is a safety net: `Subscription::checkAndExpireSubscriptions()` (queried `whereNotIn('collection_method', ['manual','system'])`) expires a subscription whose `next_billing_date` is past the grace period — i.e. the webhook never arrived or the gateway silently stopped billing. It charges nothing; it only marks the row expired.
210
+
211
+ ## First payments and simulated trials
212
+
213
+ A subscription's first payment is often not the same as its renewals. A signup fee makes it bigger. A free trial makes it zero. A first-payment coupon or an upgrade credit makes it smaller. FluentCart supports all of these on every gateway that runs subscriptions, including gateways that have no signup fee, cannot charge a different first amount, or have no trial at all.
214
+
215
+ The way FluentCart fills that gap can make a subscription look like it is on a trial, in the FluentCart admin and in the gateway's dashboard. **That "Trialing" status is expected. It is not a bug.**
216
+
217
+ At a glance
218
+
219
+ | Question | Short answer |
220
+ | --- | --- |
221
+ | Why does admin show "Trialing" when I never offered a trial? | The first payment was lower than the renewal price. FluentCart charged that amount at checkout and told the gateway to wait one billing period before its first renewal. Most gateways call that wait a trial. |
222
+ | What does the customer see? | "Active". The customer portal hides a trial that FluentCart created this way. |
223
+ | Is the customer charged twice? | No. The first period is paid once, at checkout. The gateway's first charge is for the second period. |
224
+ | When does it go away? | On the next billing date, when the gateway starts billing. |
225
+
226
+ ### The two numbers
227
+
228
+ Every subscription checkout ends with two numbers: **what the customer pays now**, and **what the customer pays on each renewal**. FluentCart works both out first, then compares the cost of the first period with the renewal price:
229
+
230
+ | First period costs… | Example | What FluentCart sets up |
231
+ | --- | --- | --- |
232
+ | The same as a renewal | Plain $20/month | Nothing special. |
233
+ | More than a renewal | $20/month + $15 signup fee | A $35 first payment, then $20 renewals. |
234
+ | Less than a renewal | $20/month with a 50% first-month coupon | A $10 first payment. The first renewal waits one full billing period. FluentCart marks this wait as a **simulated trial**. |
235
+ | Nothing | Free trial, 100% coupon, full upgrade credit | No charge (or a card check). The first renewal waits for the trial, or for one billing period. |
236
+
237
+ A simulated trial is the wait after a first payment that was lower than the renewal price. Nobody offered it as a trial. FluentCart uses it because "charge something now, start billing later" is the one tool almost every gateway has.
238
+
239
+ These lower the first payment and can create one:
240
+
241
+ - A coupon that applies to the first payment only.
242
+ - A plan upgrade's prorated credit, or an upgrade discount.
243
+ - A shipping discount on the first order only, when renewals bill full shipping.
244
+ - A 100% discount.
245
+
246
+ A coupon that applies to every renewal lowers the renewal price instead, so it creates no simulated trial.
247
+
248
+ **Length:** one billing period in days. Monthly uses the number of days in the month of checkout, yearly 365, quarterly 90, weekly 7. A real free trial on the same plan is added on top. The total is capped at 365 days by default (filter `fluent_cart/max_trial_days_allowed`).
249
+
250
+ ### Example: a first-month coupon
251
+
252
+ A customer buys a $20/month plan on 10 March with a coupon for 50% off the first month.
253
+
254
+ 1. FluentCart charges **$10** at checkout.
255
+ 2. The first period costs less than a renewal, so it adds a simulated trial of **31 days** (March has 31).
256
+ 3. The gateway is told to start billing on **10 April**, at $20.
257
+ 4. Until 10 April, the admin and the gateway dashboard may show **Trialing**. The customer portal shows **Active**.
258
+ 5. On 10 April the gateway charges $20, and the status becomes Active everywhere.
259
+
260
+ ### Example: a plan upgrade
261
+
262
+ A customer on a $10/month plan upgrades to a $30/month plan. The unused part of their current month is worth $5, so FluentCart gives a $5 upgrade credit.
263
+
264
+ 1. FluentCart charges **$25** at checkout.
265
+ 2. $25 is less than the $30 renewal, so the new subscription gets a simulated trial of one billing period.
266
+ 3. The gateway first bills $30 one month later.
267
+ 4. Until then the new subscription may show **Trialing** in the admin, even though the customer has paid and never saw a trial.
268
+
269
+ ### How gateways carry it out
270
+
271
+ FluentCart sends the gateway the same plan whatever the gateway can do. Each gateway uses the closest tool it has:
272
+
273
+ | Gateway can… | What FluentCart does |
274
+ | --- | --- |
275
+ | Run a trial and add a one-off first charge | Uses both. The wait is the gateway's own trial, and the first payment is an extra charge on the first invoice. |
276
+ | Run a trial, but has no signup fee | Uses a trial period priced at the first payment. |
277
+ | Neither | Charges the first payment itself as a one-time payment, then creates the gateway subscription with a later start date. |
278
+ | Not delay the start at all | Can still take a lower or higher first payment, but cannot run a real free trial. FluentCart refuses that checkout. |
279
+
280
+ Whatever the tool, the gateway reports its own status, and FluentCart shows that status in the admin. Gateways that model the wait as a trial report **Trialing**. Gateways that model it as a later start date may report either **Trialing** or **Active** until billing starts.
281
+
282
+ ### Why the admin and the portal differ
283
+
284
+ The admin shows the status the gateway reports. The customer portal reads a corrected status (`overridden_status`):
285
+
286
+ | Subscription | Admin shows | Customer portal shows |
287
+ | --- | --- | --- |
288
+ | Simulated trial, gateway reports trialing | Trialing | **Active** |
289
+ | Real free trial, gateway reports active, still inside the trial | Active | **Trialing** |
290
+ | Everything else | The stored status | The same |
291
+
292
+ So the admin always shows what the gateway reports, and the customer sees what they bought.
293
+
294
+ Other places that tell the two kinds of trial apart:
295
+
296
+ - **Product and checkout labels.** "Free Trial: N days" is never shown for a simulated trial.
297
+ - **Reminders.** A simulated trial gets renewal reminders, like any paid subscription. Only a real trial gets trial-ending reminders.
298
+ - **Subscription reports.** A trialing subscription with a simulated trial is counted as "discounted", not as a trial.
299
+ - **Plan upgrades.** A subscription on a real trial gets no prorated credit when it upgrades. One on a simulated trial does, because the customer paid for that period.
300
+
301
+ ### Installments
302
+
303
+ On a plan with a fixed number of payments, the first payment at checkout already covers the first period. So the gateway must bill one fewer time (`getInitialRemoteBillTimes()`). Gateways that take a payment count get the reduced count. Gateways that do not are ended by FluentCart: when the last payment is recorded, the subscription completes and `SubscriptionEOT` cancels it at the gateway (see [Events](#events)).
304
+
305
+ ### Reactivation
306
+
307
+ A canceled or expired subscription that is reactivated usually gets a **new** gateway subscription. If the customer still has paid days left, the new one waits until they run out (`getReactivationTrialDays()`). That wait is a simulated trial too, so it can show "Trialing" in the admin.
308
+
309
+ If the reactivation payment is the last installment, most gateways create no new gateway subscription, and FluentCart completes the subscription locally.
310
+
311
+ ### Store-managed subscriptions
312
+
313
+ A [store-managed](#store-managed-the-renewal-engine-manual-system) subscription has no gateway subscription. FluentCart runs the schedule itself, so it needs no trial trick. On first activation:
314
+
315
+ - A real free trial starts as **Trialing**.
316
+ - A simulated trial starts as **Active**.
317
+
318
+ ### For support
319
+
320
+ When a merchant reports "Trialing" on a subscription with no trial:
321
+
322
+ 1. Open the order. If the first payment was lower than the renewal price (coupon, upgrade, discount), this is a simulated trial.
323
+ 2. Check the next billing date. It should be one billing period after the first payment.
324
+ 3. Check that the customer portal shows "Active".
325
+ 4. Nothing to fix. The status follows the gateway and becomes "Active" when the gateway starts billing.
326
+
327
+ ### Code reference
328
+
329
+ Paths are relative to `fluent-cart/`. Each gateway's own handling lives in its `Processor` / `Confirmations` classes.
330
+
331
+ | What | Where |
332
+ | --- | --- |
333
+ | First payment vs renewal, simulated trial decision | `app/Helpers/CheckoutProcessor.php` · `convertToSubscriptionFormat()` (config flag `is_trial_days_simulated`) |
334
+ | Discounts that lower the first payment (coupon, `prorate_credit`, `upgrade_discount`) | `app/Helpers/CheckoutProcessor.php` discount total |
335
+ | First-order-only shipping discount | `app/Helpers/CheckoutProcessor.php` (`billRenewalsFullShipping`) |
336
+ | Simulated trial length, 365-day cap | `app/Helpers/Helper.php` · `calculateAdjustedTrialDaysForInterval()` |
337
+ | Interval days | `app/Services/Payments/PaymentHelper.php` · `getIntervalDays()` |
338
+ | Customer-facing status | `app/Models/Subscription.php` · `getOverriddenStatusAttribute()` |
339
+ | Payment count sent to the gateway | `app/Models/Subscription.php` · `getInitialRemoteBillTimes()` |
340
+ | Paid days left on reactivation | `app/Models/Subscription.php` · `getReactivationTrialDays()` |
341
+ | $0 first period counting | `app/Helpers/CheckoutProcessor.php` · `syncInitialCycleCounting()` (`billed_cycles_offset`) |
342
+ | Store-managed first status | `app/Helpers/StatusHelper.php` |
343
+ | "Free Trial" label | `app/Helpers/Helper.php` · `generateTrialInfo()` |
344
+ | Reminders | `app/Services/Reminders/ReminderService.php` |
345
+ | Reports ("discounted") | `app/Services/Report/SubscriptionReportService.php` |
346
+ | Upgrade credit and real trials | `app/Services/PlanUpgradeService.php` |
347
+ | Admin list status | `resources/admin/Modules/Subscriptions/Components/SubscriptionsTable.vue` (raw `status`) |
348
+ | Portal status | `resources/public/customer-profile/Vue/parts/SubscriptionTable.vue` (`overridden_status`) |
349
+
350
+ ## Store-managed: the renewal engine (`manual` + `system`)
351
+
352
+ FluentCart owns the schedule. One hourly cron drives everything.
353
+
354
+ ### The cron
355
+
356
+ `fluent_cart/scheduler/hourly_tasks` (Action Scheduler, 3600s) → `RenewalScheduler::handle()`, which does exactly two things — generate renewals coming due, and escalate renewals that were not paid. Batch size **20 each, per hour**.
357
+
358
+ ### Generating the renewal
359
+
360
+ `RenewalService::processDueSubscriptions()` selects renewal-engine subscriptions whose `next_billing_date` falls inside an **advance window** — the renewal is created *before* it is due:
361
+
362
+ | Interval | Advance days | Grace days |
363
+ | --- | --- | --- |
364
+ | daily | 0 | 1 |
365
+ | weekly | 3 | 3 |
366
+ | monthly | 7 | 7 |
367
+ | quarterly / half-yearly / yearly | 15 | 15 |
368
+
369
+ (Advance: `getAdvanceCreationDaysMap()`. Grace: `SubscriptionHelper::getSubscriptionsGracePeriodDays()`. Both filterable — see [Hook inventory](#hook-inventory).)
370
+
371
+ `createRenewalOrders()` takes a MySQL advisory lock (`GET_LOCK('fc_renewal_{sub_id}')`), re-checks that no open renewal exists, and creates a child `Order` inside a transaction:
372
+
373
+ - `type = renewal`, `parent_id` = parent order, `status = pending`
374
+ - **`payment_status` = `payment_scheduled` if the subscription `isSystem()`, else `pending`** — this single line is the fork between the two store-managed modes
375
+ - order meta **`due_date` = the subscription's `next_billing_date`** — the anchor for every downstream dunning calculation
376
+ - a pending `OrderTransaction`
377
+
378
+ Then:
379
+
380
+ - **`manual`** → fires `fluent_cart/renewal_created` → the customer gets a renewal email with a Pay Now link.
381
+ - **`system`** → fires `fluent_cart/subscriptions/system_renewal_scheduled` and calls `SystemChargeService::scheduleCharge()`. **No email.** The customer is not asked to pay something that is about to be charged.
382
+
383
+ ### Reminders
384
+
385
+ A separate subsystem (`RenewalReminderService`), **off by default** (`reminders_enabled` / `renewal_reminders_enabled` both default `no`).
386
+
387
+ Anchored on `due_date`: one reminder at the due date, then overdue reminders at **1, 3, 7 days** past it (filterable). It deliberately skips system renewals that are still waiting on their scheduled charge.
388
+
389
+ ### Dunning — past_due, then expired
390
+
391
+ `processOverdueRenewals()` walks unpaid renewals (`pending` or `payment_scheduled`) and computes `renewalAge = now - due_date` in days:
392
+
393
+ ```
394
+ renewalAge >= 0 and status ∈ [active, trialing] → past_due
395
+ renewalAge >= graceDays and status == past_due → expired
396
+ ```
397
+
398
+ **It takes two cron passes to expire** — active → past_due, then (grace elapsed) past_due → expired. Expiry calls `syncSubscriptionStates(['status' => expired, 'next_billing_date' => null])`.
399
+
400
+ The scanner stands down for a system subscription whose charge engine still owns the renewal — either an async charge is settling, or an attempt is still queued (`hasQueuedCharge()`). **A queued retry suppresses expiry**, so a subscription can never die out from under an armed charge.
401
+
402
+ ### Paying — the Pay Now path
403
+
404
+ `StatusHelper::syncOrderStatuses()` is the order-side chokepoint. It derives payment status from transaction rows, and **atomically claims** the `→ paid` transition with a conditional UPDATE. If another process (webhook vs. browser confirmation) already claimed it, this one returns early. That claim is what makes the renewal-paid hook fire exactly once:
405
+
406
+ ```
407
+ // StatusHelper — the ONLY fire site for fluent_cart/renewal_paid
408
+ if ($this->order->type === Status::ORDER_TYPE_RENEWAL
409
+ && $oldPaymentStatus !== $this->order->payment_status
410
+ && $this->order->payment_status === Status::PAYMENT_PAID) {
411
+ do_action('fluent_cart/renewal_paid', ['order' => $this->order]);
412
+ }
413
+ ```
414
+
415
+ Edge-triggered: `renewal && (pending|payment_scheduled|failed) → paid`. Two listeners: `RenewalService::handleRenewalPaid()` (priority 10) and `SystemChargeService::cancelPendingCharge()` (priority 20 — paying early cancels the queued charge).
416
+
417
+ **`handleRenewalPaid()`** is where a store-managed renewal completes:
418
+
419
+ - Idempotent via a `renewal_processed` order meta flag.
420
+ - **Cadence-preserving `next_billing_date`:** paid on or before the due date → `due_date + interval` (the schedule does not drift). Paid late → `now + interval`.
421
+ - Accepts an **`expired`** subscription and brings it back — a late payment revives.
422
+ - Calls `syncSubscriptionStates()`, then dispatches `SubscriptionRenewed` — unless the sync just completed the subscription (EOT), in which case it returns first.
423
+
424
+ ### Which gateways appear on a renewal or reactivation
425
+
426
+ The same `SubscriptionGatewayGate` handles these, but the decision comes from the *subscription* — its `collection_method` and how it was **born** (the `management_mode` stamp) — never from the store's current setting for an already-stamped subscription. Nothing in the renewal engine gates the list separately.
427
+
428
+ | Subscription | Gateways offered |
429
+ | --- | --- |
430
+ | `automatic` | Gateways with `subscriptions` only — it owns a vendor schedule, and a one-time gateway would strand it. Ignores the `subscription_manual_fallback` setting |
431
+ | `manual`, unstamped, store `gateway_managed`, invoice **not yet due** | One-time gateways only — see below |
432
+ | `manual`, unstamped, store `gateway_managed`, invoice **due or overdue** | The conversion window: capable gateways offered, and paying through one converts the subscription to `automatic` |
433
+ | `manual` stamped `store_managed`, or unstamped while the store is store-managed today | One-time only: `manual_subscription` gateways plus gateways with no `subscriptions` support. Never converts |
434
+ | `system` | Same one-time-only list; no conversion path exists for `system` at all |
435
+
436
+ Whatever survives is reordered so the subscription's `current_payment_method` renders first. A cart naming a subscription that cannot be resolved is left **ungated** — there is nothing to reason about, and the charge itself fails safely with `no_subscription` before any gateway API call.
437
+
438
+ #### Why an early renewal payment is restricted
439
+
440
+ Renewal invoices are generated days *ahead* of their due date so the customer has time to pay, and `handleRenewalPaid()` anchors the next date to `due_date` when they pay on or before it — the cadence is preserved and the advance days are honoured.
441
+
442
+ The legacy manual→automatic conversion cannot honour them. It creates a vendor subscription anchored to **now** (no trial anchor is set unless the plan itself carries trial days), so an early payer is charged immediately and their `next_billing_date` is reset to `today + interval`, forfeiting every day between now and the original due date. So the gate closes that window until the due date arrives, when there is nothing left to lose.
443
+
444
+ Two consequences worth knowing:
445
+
446
+ - The restriction uses a strict "no `subscriptions` support" test, not the store-billed list above. Stripe and PayPal declare `manual_subscription`, but the one-time routing that flag implies does not apply to an unstamped `manual` subscription on a gateway-managed store — `shouldChargeSubscriptionAsOneTime()` returns `false` there, so they would still take the subscription route and convert.
447
+ - If such a store has no one-time gateway active, that one checkout renders **no** payment methods. Deliberate: the customer pays from the due date onward instead of silently losing days.
448
+
449
+ A reactivation rarely hits this rule — a reactivation cart only reaches checkout when payment is already due, so its invoice is not in advance.
450
+
451
+ ## Store-managed + auto-charge (`system`)
452
+
453
+ Everything above still applies. `system` adds a saved token and an automatic charge per renewal. Same renewal engine, same dunning, same admin actions — it just tries to pay the renewal for the customer first.
454
+
455
+ ### Token storage — no new table
456
+
457
+ ```
458
+ customer id (cus_…) → fct_subscriptions.vendor_customer_id (existing column)
459
+ token (pm_…) → active_payment_method SubscriptionMeta (existing key)
460
+ ```
461
+
462
+ **Two shapes in the wild.** `active_payment_method` is written top-level (`vendor_method_id`) by the checkout/confirmation paths, but nested (`details.payment_method_id`) by the card-update/switch-payment-method flow. **Every reader must check both** — e.g. `Arr::get($meta, 'vendor_method_id') ?: Arr::get($meta, 'details.payment_method_id')`. A single-shape read risks re-persisting a stale token or wrongly demoting a subscription whose current token came from a card update.
463
+
464
+ At checkout the first payment is a **one-time charge that also vaults the method** — not a vendor subscription. On **Stripe** that is a PaymentIntent with `setup_future_usage = off_session`; on **PayPal** the initial capture is taken vault-enabled and the resulting token is stored the same way (later charged via `Processor::chargeVaultedRenewal()`). The card is saved with explicit consent copy. **The token is read at charge time, never snapshotted** into the scheduled action, so a card updated mid-dunning is picked up by the next retry automatically.
465
+
466
+ **Webhook fallback for vaulting.** The zero-payable trial SetupIntent confirm normally completes via AJAX. If that call is lost (network drop, closed tab), the `setup_intent.succeeded` webhook recovers it — same write path, same demote-to-manual fallback if the gateway returns no token. Self-idempotent: a duplicate/late webhook after the AJAX call already succeeded fails its `vendor_charge_id` lookup and no-ops.
467
+
468
+ ### The charge lifecycle
469
+
470
+ The gateway contract is two methods on `AbstractPaymentGateway`, both defaulting to `WP_Error('not_supported')` so a capability/implementation mismatch degrades instead of fataling:
471
+
472
+ | Method | Returns |
473
+ | --- | --- |
474
+ | `chargeRenewal(PaymentInstance, $args)` | `true` \| `'processing'` \| `WP_Error` |
475
+ | `reconcileRenewalCharge(PaymentInstance)` | same three |
476
+
477
+ Stripe's implementation is a PaymentIntent with `customer` + `payment_method` + `off_session: true, confirm: true`, keyed `Idempotency-Key: fct_system_charge_{order_id}_{attempt}`.
478
+
479
+ ### Retries are anchored to the grace period, not to fixed days
480
+
481
+ ```
482
+ offsets = [0.25, 0.6, 0.9] × graceDays → 3 retries + the due-date attempt = 4 total
483
+ ```
484
+
485
+ | Interval | Grace | Attempt 1 | Retries |
486
+ | --- | --- | --- | --- |
487
+ | daily | 1 day | due date | +6h, +14.4h, +21.6h |
488
+ | weekly | 3 days | due date | +0.75d, +1.8d, +2.7d |
489
+ | monthly | 7 days | due date | +1.75d, +4.2d, +6.3d |
490
+ | quarterly / yearly | 15 days | due date | +3.75d, +9d, +13.5d |
491
+
492
+ The first attempt always fires **on the due date itself** — no grace maths touches it. Only the retries scale.
493
+
494
+ Why not fixed days? Because the grace period is per-interval, so a fixed schedule delivers a *different number of retries per interval*. Anchoring to grace guarantees all intervals land their retries inside the dunning window.
495
+
496
+ Two invariants hold the schedule and the scanner together:
497
+
498
+ - The overdue scanner **will not expire a subscription while an attempt is queued**, so even a filter that pushes an offset past the grace period cannot kill a subscription mid-retry.
499
+ - Offsets are sorted, and **truncated to `MAX_ATTEMPT_SLOTS - 1`**. Attempt numbers key both the scheduler lookups and the gateway idempotency key, so an attempt scheduled outside the swept slot range would be invisible to `hasQueuedCharge()` and `unscheduleCharges()` — left armed to charge a renewal that had already been paid or voided.
500
+
501
+ The retry offsets are filterable (`fluent_cart/subscriptions/system_charge_retry_offsets`), and the charge-failed email defaults to **first failure only** so retries don't spam the customer.
502
+
503
+ ### Admin-triggered charges — off the scheduler
504
+
505
+ Two admin actions charge on demand, both through `SystemChargeService::chargeNow()` — one immediate off-session attempt that first **unschedules the queued due-date attempt**, so the manual and automatic charge can never both run:
506
+
507
+ - **Charge Now** charges an *existing* open renewal. Gated `canChargeNow`: `system`, open renewal exists, chargeable status, not currently settling (`processing`). After exhaustion the click clears `exhausted`, runs one attempt, and re-records exhaustion on a fresh failure — no ladder restart, nothing re-queued.
508
+ - **Charge Next Renewal Now** is the create-renewal action (`SubscriptionController::createRenewalNow()`) on a `system` sub: `createRenewalOrders()` **then** `chargeNow()` on the fresh renewal, in one call. Manual subs take the create-only branch (pay-now email, no charge). Gated `canCreateRenewal` (`usesRenewalEngine()` + active/trialing + `next_billing_date` + **no** open renewal), so it and Charge Now are mutually exclusive by open-renewal state.
509
+
510
+ A decline returns `status = 'failed'` (HTTP 200) and drops the renewal onto the normal retry/dunning ladder; a state violation returns `WP_Error`.
511
+
512
+ ### Losing the capability — demotion to `manual`
513
+
514
+ `collection_method` is resolved once, at checkout. But `current_payment_method` can move afterwards — most commonly when a customer pays a **failed** renewal with a **different gateway** via Pay Now. That is a one-off renewal payment; no vendor subscription is created. The subscription is now `system` on a gateway that cannot token-charge.
515
+
516
+ `SystemChargeService::reconcileGatewayCapability()` runs from `syncSubscriptionStates()` whenever `current_payment_method` comes back dirty. If the new gateway lacks `system_subscription`, `demoteToManual()` hands the subscription back to plain manual invoicing: flip `collection_method`, drop `system_charge_state`, unschedule queued attempts, release any waiting renewal to `pending` **with the pay-now email that was previously withheld**, log it, and fire `system_charge_disabled`.
517
+
518
+ A second trigger fires **at initial checkout**: if the first capture returns no vaultable token at all (Stripe: no `payment_method` on the response; PayPal: capture isn't vault-enabled), the confirmation path demotes immediately rather than leaving a `system` subscription with nothing to charge.
519
+
520
+ Manual is the floor
521
+
522
+ In store-managed mode, `resolveCollectionMethodFor()` has no `automatic` branch. A store-managed subscription that loses auto-charge falls back to **manual invoicing** — it never falls back to gateway billing.
523
+
524
+ ## The shared spine
525
+
526
+ Both models write through the same two functions. This is why the lifecycle events fire consistently no matter how a subscription is billed.
527
+
528
+ ### `syncSubscriptionStates()` — the subscription-side chokepoint
529
+
530
+ `app/Modules/Subscriptions/Services/SubscriptionService.php`. Every meaningful subscription write funnels through it.
531
+
532
+ 1. **Recomputes `bill_count` from the database** — counts succeeded charge transactions with `total > 0`, plus `early_payment_history`, plus a `billed_cycles_offset` meta, minus `billed_cycles_deduction`. **A caller-supplied `bill_count` is always overwritten.** The column is derived, never incremented.
533
+ 2. **Owns the EOT rule:** `isEot = bill_times > 0 && bill_count >= bill_times` → forces `status = completed`, `next_billing_date = NULL`. (`bill_times = 0` means unlimited and never completes.)
534
+ 3. Normalizes companion fields (`canceled_at`, `validity_expired_at`).
535
+ 4. Captures the **dirty diff** before saving — that diff is what the update hook publishes, and what triggers `reconcileGatewayCapability()` when `current_payment_method` changes.
536
+ 5. Compares old status to new and dispatches lifecycle events **exactly once**.
537
+
538
+ Two paths deliberately bypass it — admin **edit** and admin **reactivate** — precisely because step 1 would override an explicit admin choice. Both re-implement the event fan-out by hand.
539
+
540
+ ### Events
541
+
542
+ | Event | Fires when | Gateway-managed | Store-managed |
543
+ | --- | --- | --- | --- |
544
+ | `SubscriptionActivated` | First payment lands | ✅ | ✅ |
545
+ | `SubscriptionRenewed` | A renewal is paid | ✅ via `recordRenewalPayment()` | ✅ via `handleRenewalPaid()` |
546
+ | `SubscriptionCanceled` | Cancel | ✅ | ✅ |
547
+ | `SubscriptionEOT` | `bill_count >= bill_times` | ✅ | ✅ |
548
+ | `SubscriptionValidityExpired` | → expired | ✅ (+ expiry cron) | ✅ (via the overdue scanner) |
549
+ | `SubscriptionReactivated` | canceled/expired → active | ✅ | ✅ |
550
+ | `SubscriptionPaused` / `Resumed` | pause/resume | ✅ (gateway must support it) | ✅ (local, immediate) |
551
+ | `SubscriptionUpdated` | Admin edits the terms | ❌ **never** | ✅ only |
552
+ | `SubscriptionPeriodSkipped` | Admin skips a period | ❌ **never** | ✅ only |
553
+ | `fluent_cart/subscription_past_due` | Renewal overdue | ❌ **never** | ✅ only |
554
+ | `system_charge_failed` | Auto-charge declined | ❌ | ✅ `system` only |
555
+
556
+ `SubscriptionEOT` has a `beforeDispatch()` that cancels the vendor subscription with `fire_hooks => false` — so ending a term tears down the gateway side **without** also emitting `SubscriptionCanceled`.
557
+
558
+ See [Subscription action hooks](/hooks/actions/subscriptions.md) for payloads and priorities.
559
+
560
+ ## What each model allows
561
+
562
+ | Action | `automatic` | `manual` | `system` | Guard |
563
+ | --- | --- | --- | --- | --- |
564
+ | Cancel | ✅ (calls gateway) | ✅ (local) | ✅ (local) | — |
565
+ | Fetch / resync from gateway | ✅ | ❌ | ❌ | `canFetch` |
566
+ | Pause / Resume | ⚠️ gateway must support it | ✅ | ✅ | `canPause` / `canResume` |
567
+ | **Edit terms** (amount, interval, bill_times, next date) | ❌ | ✅ | ✅ | `canUpdateDetails()` = `usesRenewalEngine()` |
568
+ | **Reactivate** | ❌ | ✅ | ✅ | `usesRenewalEngine()` + `canReactivate()` |
569
+ | **Create renewal now** | ❌ | ✅ (create + email) | ✅ **create + charge** | `canCreateRenewal` |
570
+ | **Skip next period** | ❌ | ✅ | ✅ | `usesRenewalEngine()` |
571
+ | **Charge an open renewal now** | ❌ | ❌ | ✅ (one off-session attempt) | `canChargeNow` |
572
+ | Update card on file | ✅ | ✅ | ✅ | `canUpdatePaymentMethod()` |
573
+ | **Switch gateway** | ✅ | ❌ | ❌ | `canSwitchPaymentMethod()` |
574
+ | **[Edit vendor IDs](/modules/subscription-vendor-ids.md)** | ✅ opt-in | ❌ | ❌ | `canEditVendorIds()` — off unless `fluent_cart/subscription/vendor_id_editing_enabled` returns `true` |
575
+ | Pay Now on an open renewal | n/a | ✅ | ✅ (cancels the queued charge) | — |
576
+
577
+ Two asymmetries deserve explanation.
578
+
579
+ **Pause on `automatic` is effectively dead.** The code requires the gateway to declare `pause_subscription` and implement `pause()`. **No shipped gateway does either.** An automatic subscription can only become `paused` by being paused at the gateway and having the status arrive by webhook.
580
+
581
+ **Switching gateways is blocked for store-billed subscriptions** — and this is not a limitation, it's a correctness guard. "Switch payment method" does not change a card; both `StripeGateway/SwitchCustomerMethod` and `PayPalGateway/SubscriptionManager` **create a live vendor subscription** at the target gateway. On a subscription owned by the renewal engine, that gateway would start billing on its own schedule while FluentCart kept issuing renewals for the same periods — a **double bill**. Moving a store-billed subscription onto a gateway's billing engine is a *migration*, not a fallback, and is deliberately not implemented. Customers change the **card on file** instead.
582
+
583
+ ## Hook inventory
584
+
585
+ ### Shared
586
+
587
+ | Hook | Fired at |
588
+ | --- | --- |
589
+ | `fluent_cart/scheduler/hourly_tasks` | Action Scheduler, hourly |
590
+ | `fluent_cart/renewal_paid` | `StatusHelper` — **the only fire site** |
591
+ | `fluent_cart/payments/subscription_status_changed` | `SubscriptionService` |
592
+ | `fluent_cart/payments/subscription_{status}` | `SubscriptionService` (dynamic) |
593
+ | `fluent_cart/subscription/data_updated` | `SubscriptionService` (dirty diff, no status change) |
594
+ | `fluent_cart/subscription_collection_method_{gateway}` | filter — `CheckoutProcessor` |
595
+ | `fluent_cart/subscription/management_mode` | filter — `SubscriptionManagementMode`, store-wide mode override |
596
+ | `fluent_cart/checkout_active_payment_methods` | filter — `SubscriptionGatewayGate` gates every subscription cart here |
597
+ | `fluent_cart/subscription/vendor_id_editing_enabled` | filter, default `false` — opt in to [editing vendor identifiers](/modules/subscription-vendor-ids.md) on an `automatic` subscription |
598
+
599
+ ### Renewal engine
600
+
601
+ | Hook | Purpose |
602
+ | --- | --- |
603
+ | `fluent_cart/renewal_created` | Renewal generated (drives the pay-now email) |
604
+ | `fluent_cart/renewal_payment_scheduled` | Gateway deferred a charge → renewal flips to `payment_scheduled` |
605
+ | `fluent_cart/subscription_past_due` | Overdue escalation (drives the past-due email) |
606
+ | `fluent_cart/renewal_voided` | Admin voided a renewal |
607
+ | `fluent_cart/renewal/advance_creation_days` | filter — the advance window map |
608
+ | `fluent_cart/subscription/grace_period_days` | filter — the grace map |
609
+
610
+ ### System charge
611
+
612
+ | Hook | Params | Purpose |
613
+ | --- | --- | --- |
614
+ | `fluent_cart/subscriptions/system_renewal_scheduled` | `(['subscription','order','parent_order','customer','transaction'])` | System renewal created; charge queued, no pay-now email |
615
+ | `fluent_cart/subscriptions/system_charge_due` | `($orderId, $attempt)` | The scheduled charge (Action Scheduler) |
616
+ | `fluent_cart/subscriptions/system_charge_reconcile` | `($orderId)` | Daily re-check of an async charge |
617
+ | `fluent_cart/subscriptions/system_charge_succeeded` | `(['order','subscription','attempt'])` | |
618
+ | `fluent_cart/subscriptions/system_charge_failed` | `(['order','subscription','attempt','error','next_retry_at'])` | |
619
+ | `fluent_cart/subscriptions/system_charge_failed_notification` | `([...])` | Drives the charge-failed emails |
620
+ | `fluent_cart/subscriptions/system_charge_failure_notify` | filter, default `$attempt === 1` | Whether to email on this failure |
621
+ | `fluent_cart/subscriptions/system_charge_disabled` | `(['subscription','reason'])` | Demoted to `manual` |
622
+ | `fluent_cart/subscriptions/system_charge_retry_offsets` | filter — `($offsets, ['subscription','grace_days'])` | Retry schedule, in days after the due date |
623
+ | `fluent_cart/subscriptions/system_collection_enabled` | filter — `($enabled)` | Store-wide override of the auto-charge setting |
624
+ | `fluent_cart/subscriptions/system_billing_enabled` | filter, default `true` | Env kill switch — return `false` (e.g. on a staging clone) to stop all system billing |
625
+
626
+ Stripe webhook events are merchant-configured
627
+
628
+ `Webhook::getEvents()` is the source of truth for which Stripe dashboard events are consumed (including `setup_intent.succeeded`). Any event added to the accepted-events list must also land in `getEvents()` and the setup instructions, or the merchant never enables it in their dashboard and the handler is unreachable.
629
+
630
+ ## Known gaps
631
+
632
+ Recorded so nobody rediscovers them the hard way.
633
+
634
+ - **An ambiguous transport failure can double-charge a `system` renewal.** The Stripe idempotency key is `fct_system_charge_{order_id}_{attempt}` — it includes the attempt number, so a charge that *succeeded* but whose response was lost gets re-charged under a fresh key on the next retry. A per-renewal key would fix it, at the cost of per-attempt replay protection.
635
+ - **Stripe's `invoice.payment_failed` is not handled.** It is advertised in the webhook setup instructions but absent from the accepted-events list, so it returns 200 and does nothing. Payment failure on a gateway-managed subscription is learned indirectly, via `customer.subscription.updated` → `past_due` → local `expiring`.
636
+ - **`pause_subscription` is declared by no gateway and implemented by none** — pausing an `automatic` subscription from FluentCart always fails.
637
+ - **The final installment of a store-billed subscription emits `SubscriptionEOT` but no `SubscriptionRenewed`** (`handleRenewalPaid` returns early once the sync marks it `completed`).
638
+ - **A lost Action Scheduler job** leaves a system renewal sitting in `payment_scheduled` with its reminders suppressed. The overdue scanner still escalates it once the due date passes, so it is not stranded — just quiet until then.
639
+ - **`store_managed` does not fully stop a gateway schedule for an `automatic` subscription.** The gate admits Stripe and PayPal on a store-managed cart because they declare `manual_subscription`, on the assumption they will take a single charge — but that one-time routing only applies to `manual` and `system` subscriptions. An `automatic` subscription paid through them still gets a vendor schedule. Closing it means widening the one-time rule itself, not the gate.
640
+
641
+ ## Quick reference
642
+
643
+ **Am I looking at a store-managed subscription?** `$subscription->usesRenewalEngine()` — not `isManual()`, which means strictly `manual` and excludes `system`.
644
+
645
+ **Where does a renewal come from?**
646
+
647
+ - `automatic` → a webhook, reactively → `recordRenewalPayment()`
648
+ - `manual` / `system` → the hourly cron, proactively → `processDueSubscriptions()`
649
+
650
+ **Who advances `next_billing_date`?**
651
+
652
+ - `automatic` → the gateway (copied from its payload)
653
+ - `manual` / `system` → `handleRenewalPaid()`, cadence-preserving
654
+
655
+ **Why isn't my subscription renewing?**
656
+
657
+ - `automatic` → check the webhook actually arrived; the expiry safety-net cron is what eventually marks it expired
658
+ - `manual` / `system` → check `next_billing_date`, the advance window, and whether an open renewal already exists (the engine will not create a second one)
659
+
660
+ **Why is a `system` subscription not auto-charging?** Check `collection_method` — it may have been **demoted to `manual`** because the gateway on file changed (look for a `system_charge_disabled` activity log entry). Also check `system_charge_state` meta for `exhausted`.
661
+
662
+ ## Related Documentation
663
+
664
+ - [Subscription Model](/database/models/subscription.md) — attributes, scopes, methods
665
+ - [Subscription Meta](/database/models/subscription-meta.md) — where tokens and system-charge state are stored
666
+ - [Subscription Action Hooks](/hooks/actions/subscriptions.md) — lifecycle event payloads
667
+ - [Subscription Filter Hooks](/hooks/filters/customers-and-subscriptions.md) — advance window, grace, retry offsets
668
+ - [Subscriptions API](/api/subscriptions.md) — admin and customer REST endpoints
669
+ - [Editing Vendor IDs](/modules/subscription-vendor-ids.md) — opt-in repair of `vendor_subscription_id` / `vendor_customer_id`
670
+ - [Payment Methods Module](/modules/payment-methods.md) — the gateway architecture subscriptions build on
671
+
672
+ ---
673
+
674
+ **Next Steps:**
675
+
676
+ - [Payment Methods Module](./payment-methods.md) — gateway development and the capability system
677
+ - [Custom Payment Gateway](/payment-methods-integration/) — implement `chargeRenewal()` for system charges
678
+ - [Modules Overview](./index.md) — back to modules overview