fluentcart-developer 3.0.0 → 3.0.2

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 (612) 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/server.d.ts.map +1 -1
  6. package/dist/server.js +37 -1
  7. package/dist/server.js.map +1 -1
  8. package/dist/skills/fluentcart-developer/SKILL.md +108 -108
  9. package/dist/skills/fluentcart-developer/examples/README.md +30 -30
  10. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  11. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  12. package/dist/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +113 -113
  13. package/dist/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +148 -148
  14. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  15. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/README.md +22 -22
  16. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/sample-plugin-with-licensing-sdk.php +79 -79
  17. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/FluentLicensing.php +303 -303
  18. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/LicenseSettings.php +566 -566
  19. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/PluginUpdater.php +304 -304
  20. package/dist/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +61 -61
  21. package/dist/skills/fluentcart-developer/references/api/authentication.md +452 -452
  22. package/dist/skills/fluentcart-developer/references/api/coupons.md +786 -786
  23. package/dist/skills/fluentcart-developer/references/api/customers.md +889 -889
  24. package/dist/skills/fluentcart-developer/references/api/files.md +609 -609
  25. package/dist/skills/fluentcart-developer/references/api/index.md +432 -432
  26. package/dist/skills/fluentcart-developer/references/api/licensing.md +633 -633
  27. package/dist/skills/fluentcart-developer/references/api/order-bump.md +384 -384
  28. package/dist/skills/fluentcart-developer/references/api/orders.md +814 -814
  29. package/dist/skills/fluentcart-developer/references/api/products.md +866 -866
  30. package/dist/skills/fluentcart-developer/references/api/roles-permissions.md +536 -536
  31. package/dist/skills/fluentcart-developer/references/api/subscriptions.md +827 -827
  32. package/dist/skills/fluentcart-developer/references/database/index.md +44 -44
  33. package/dist/skills/fluentcart-developer/references/database/models/activity.md +178 -178
  34. package/dist/skills/fluentcart-developer/references/database/models/applied-coupon.md +291 -291
  35. package/dist/skills/fluentcart-developer/references/database/models/attribute-group.md +239 -239
  36. package/dist/skills/fluentcart-developer/references/database/models/attribute-relation.md +181 -181
  37. package/dist/skills/fluentcart-developer/references/database/models/attribute-term.md +219 -219
  38. package/dist/skills/fluentcart-developer/references/database/models/cart.md +645 -645
  39. package/dist/skills/fluentcart-developer/references/database/models/coupon.md +427 -427
  40. package/dist/skills/fluentcart-developer/references/database/models/customer-addresses.md +348 -348
  41. package/dist/skills/fluentcart-developer/references/database/models/customer-meta.md +156 -156
  42. package/dist/skills/fluentcart-developer/references/database/models/customer.md +584 -584
  43. package/dist/skills/fluentcart-developer/references/database/models/dynamic-model.md +163 -163
  44. package/dist/skills/fluentcart-developer/references/database/models/label-relationship.md +155 -155
  45. package/dist/skills/fluentcart-developer/references/database/models/label.md +153 -153
  46. package/dist/skills/fluentcart-developer/references/database/models/license-activation.md +182 -182
  47. package/dist/skills/fluentcart-developer/references/database/models/license-meta.md +163 -163
  48. package/dist/skills/fluentcart-developer/references/database/models/license-site.md +208 -208
  49. package/dist/skills/fluentcart-developer/references/database/models/license.md +640 -640
  50. package/dist/skills/fluentcart-developer/references/database/models/meta.md +233 -233
  51. package/dist/skills/fluentcart-developer/references/database/models/order-address.md +391 -391
  52. package/dist/skills/fluentcart-developer/references/database/models/order-download-permission.md +144 -144
  53. package/dist/skills/fluentcart-developer/references/database/models/order-item.md +383 -383
  54. package/dist/skills/fluentcart-developer/references/database/models/order-meta.md +303 -303
  55. package/dist/skills/fluentcart-developer/references/database/models/order-operation.md +158 -158
  56. package/dist/skills/fluentcart-developer/references/database/models/order-promotion-stat.md +175 -175
  57. package/dist/skills/fluentcart-developer/references/database/models/order-promotion.md +250 -250
  58. package/dist/skills/fluentcart-developer/references/database/models/order-tax-rate.md +172 -172
  59. package/dist/skills/fluentcart-developer/references/database/models/order-transaction.md +440 -440
  60. package/dist/skills/fluentcart-developer/references/database/models/order.md +727 -727
  61. package/dist/skills/fluentcart-developer/references/database/models/product-detail.md +397 -397
  62. package/dist/skills/fluentcart-developer/references/database/models/product-download.md +258 -258
  63. package/dist/skills/fluentcart-developer/references/database/models/product-meta.md +153 -153
  64. package/dist/skills/fluentcart-developer/references/database/models/product-variation.md +556 -556
  65. package/dist/skills/fluentcart-developer/references/database/models/product.md +580 -580
  66. package/dist/skills/fluentcart-developer/references/database/models/relationships.md +427 -427
  67. package/dist/skills/fluentcart-developer/references/database/models/scheduled-action.md +175 -175
  68. package/dist/skills/fluentcart-developer/references/database/models/shipping-class.md +148 -148
  69. package/dist/skills/fluentcart-developer/references/database/models/shipping-method.md +280 -280
  70. package/dist/skills/fluentcart-developer/references/database/models/shipping-zone.md +205 -205
  71. package/dist/skills/fluentcart-developer/references/database/models/subscription-meta.md +173 -173
  72. package/dist/skills/fluentcart-developer/references/database/models/subscription.md +528 -528
  73. package/dist/skills/fluentcart-developer/references/database/models/tax-class.md +195 -195
  74. package/dist/skills/fluentcart-developer/references/database/models/tax-rate.md +225 -225
  75. package/dist/skills/fluentcart-developer/references/database/models/user-meta.md +166 -166
  76. package/dist/skills/fluentcart-developer/references/database/models/user.md +220 -220
  77. package/dist/skills/fluentcart-developer/references/database/models.md +404 -404
  78. package/dist/skills/fluentcart-developer/references/database/query-builder.md +860 -860
  79. package/dist/skills/fluentcart-developer/references/database/readme.md +276 -276
  80. package/dist/skills/fluentcart-developer/references/database/schema.md +1002 -1002
  81. package/dist/skills/fluentcart-developer/references/engineering/adding-custom-pages-to-the-customer-dashboard.md +395 -395
  82. package/dist/skills/fluentcart-developer/references/engineering/index.md +4 -4
  83. package/dist/skills/fluentcart-developer/references/engineering.md +4 -4
  84. package/dist/skills/fluentcart-developer/references/getting-started.md +249 -249
  85. package/dist/skills/fluentcart-developer/references/guides/frontend.md +519 -519
  86. package/dist/skills/fluentcart-developer/references/guides/index.md +107 -107
  87. package/dist/skills/fluentcart-developer/references/guides/integrations.md +600 -600
  88. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/index.md +237 -237
  89. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/labels-and-tracking.md +481 -481
  90. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/live-rates.md +269 -269
  91. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/reference.md +223 -223
  92. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/settings.md +370 -370
  93. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier.md +237 -237
  94. package/dist/skills/fluentcart-developer/references/guides/subscriptions.md +217 -217
  95. package/dist/skills/fluentcart-developer/references/hooks/actions/admin-and-templates.md +1079 -1079
  96. package/dist/skills/fluentcart-developer/references/hooks/actions/cart-and-checkout.md +1795 -1795
  97. package/dist/skills/fluentcart-developer/references/hooks/actions/customers-and-users.md +327 -327
  98. package/dist/skills/fluentcart-developer/references/hooks/actions/licenses.md +829 -829
  99. package/dist/skills/fluentcart-developer/references/hooks/actions/modules.md +81 -81
  100. package/dist/skills/fluentcart-developer/references/hooks/actions/orders.md +757 -757
  101. package/dist/skills/fluentcart-developer/references/hooks/actions/payments-and-integrations.md +1163 -1163
  102. package/dist/skills/fluentcart-developer/references/hooks/actions/pro-modules.md +219 -219
  103. package/dist/skills/fluentcart-developer/references/hooks/actions/products-and-coupons.md +1019 -1019
  104. package/dist/skills/fluentcart-developer/references/hooks/actions/subscriptions.md +1290 -1290
  105. package/dist/skills/fluentcart-developer/references/hooks/actions.md +16 -16
  106. package/dist/skills/fluentcart-developer/references/hooks/deprecated.md +60 -60
  107. package/dist/skills/fluentcart-developer/references/hooks/filters/cart-and-checkout.md +2032 -2032
  108. package/dist/skills/fluentcart-developer/references/hooks/filters/customers-and-subscriptions.md +1746 -1746
  109. package/dist/skills/fluentcart-developer/references/hooks/filters/integrations-and-advanced.md +2439 -2439
  110. package/dist/skills/fluentcart-developer/references/hooks/filters/modules.md +464 -464
  111. package/dist/skills/fluentcart-developer/references/hooks/filters/orders-and-payments.md +2658 -2658
  112. package/dist/skills/fluentcart-developer/references/hooks/filters/pro-modules.md +502 -502
  113. package/dist/skills/fluentcart-developer/references/hooks/filters/products-and-pricing.md +1785 -1785
  114. package/dist/skills/fluentcart-developer/references/hooks/filters/settings-and-configuration.md +2966 -2966
  115. package/dist/skills/fluentcart-developer/references/hooks/filters.md +14 -14
  116. package/dist/skills/fluentcart-developer/references/hooks/index.md +35 -35
  117. package/dist/skills/fluentcart-developer/references/index.md +625 -625
  118. package/dist/skills/fluentcart-developer/references/modules/fee-system.md +427 -427
  119. package/dist/skills/fluentcart-developer/references/modules/ghost-product-selling.md +440 -440
  120. package/dist/skills/fluentcart-developer/references/modules/index.md +484 -484
  121. package/dist/skills/fluentcart-developer/references/modules/licensing.md +342 -342
  122. package/dist/skills/fluentcart-developer/references/modules/order-bump.md +433 -433
  123. package/dist/skills/fluentcart-developer/references/modules/payment-methods.md +129 -129
  124. package/dist/skills/fluentcart-developer/references/modules/refunds.md +170 -170
  125. package/dist/skills/fluentcart-developer/references/modules/shipping.md +846 -846
  126. package/dist/skills/fluentcart-developer/references/modules/storage.md +986 -986
  127. package/dist/skills/fluentcart-developer/references/modules/subscription-vendor-ids.md +186 -186
  128. package/dist/skills/fluentcart-developer/references/modules/subscriptions.md +678 -678
  129. package/dist/skills/fluentcart-developer/references/payment-methods-integration/index.md +164 -164
  130. package/dist/skills/fluentcart-developer/references/payment-methods-integration/paddle-example.md +1648 -1648
  131. package/dist/skills/fluentcart-developer/references/payment-methods-integration/payment/setting/fields.md +353 -353
  132. package/dist/skills/fluentcart-developer/references/payment-methods-integration/quick-implementation.md +1079 -1079
  133. package/dist/skills/fluentcart-developer/references/payment-methods-integration.md +164 -164
  134. package/dist/skills/fluentcart-developer/references/restapi/checkout.md +573 -573
  135. package/dist/skills/fluentcart-developer/references/restapi/coupons.md +958 -958
  136. package/dist/skills/fluentcart-developer/references/restapi/customer-profile.md +1423 -1423
  137. package/dist/skills/fluentcart-developer/references/restapi/customers.md +1103 -1103
  138. package/dist/skills/fluentcart-developer/references/restapi/dashboard.md +1083 -1083
  139. package/dist/skills/fluentcart-developer/references/restapi/data-export.md +132 -132
  140. package/dist/skills/fluentcart-developer/references/restapi/email-notifications.md +846 -846
  141. package/dist/skills/fluentcart-developer/references/restapi/files.md +313 -313
  142. package/dist/skills/fluentcart-developer/references/restapi/index.md +127 -127
  143. package/dist/skills/fluentcart-developer/references/restapi/integrations.md +1000 -1000
  144. package/dist/skills/fluentcart-developer/references/restapi/inventory.md +192 -192
  145. package/dist/skills/fluentcart-developer/references/restapi/labels-and-attributes.md +797 -797
  146. package/dist/skills/fluentcart-developer/references/restapi/licensing.md +1733 -1733
  147. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-available-shipping-methods.md +30 -30
  148. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-checkout-summary.md +28 -28
  149. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-country-info.md +29 -29
  150. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-order-info.md +28 -28
  151. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-shipping-methods-list-view.md +30 -30
  152. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/login.md +66 -66
  153. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/place-order.md +179 -179
  154. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/apply-coupon.md +83 -83
  155. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/cancel-coupon.md +87 -87
  156. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/check-product-eligibility.md +59 -59
  157. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/create-coupon.md +230 -230
  158. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/delete-coupon.md +29 -29
  159. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon-settings.md +20 -20
  160. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon.md +27 -27
  161. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupon-codes.md +20 -20
  162. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupons.md +37 -37
  163. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/re-apply-coupons.md +75 -75
  164. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/store-coupon-settings.md +40 -40
  165. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/update-coupon.md +133 -133
  166. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-address-checkout.md +138 -138
  167. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-profile-address.md +119 -119
  168. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/dashboard-overview.md +22 -22
  169. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/delete-profile-address.md +46 -46
  170. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-order-details.md +30 -30
  171. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-portal-sections.md +29 -29
  172. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-profile-details.md +22 -22
  173. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-transaction-billing-address.md +30 -30
  174. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-upgrade-paths.md +31 -31
  175. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-downloads.md +29 -29
  176. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-orders.md +28 -28
  177. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/make-profile-address-primary.md +55 -55
  178. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/pause-subscription.md +29 -29
  179. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/resume-subscription.md +29 -29
  180. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/save-transaction-billing-address.md +92 -92
  181. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/select-address-for-checkout.md +32 -32
  182. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-address.md +115 -115
  183. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-details.md +69 -69
  184. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/attach-user.md +50 -50
  185. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/bulk-actions.md +65 -65
  186. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-address.md +135 -135
  187. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-customer.md +108 -108
  188. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/delete-address.md +62 -62
  189. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/detach-user.md +28 -28
  190. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/find-customer-order.md +27 -27
  191. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-attachable-users.md +20 -20
  192. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-addresses.md +28 -28
  193. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-orders.md +37 -37
  194. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-stats.md +27 -27
  195. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer.md +32 -32
  196. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/list-customers.md +37 -37
  197. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/recalculate-ltv.md +28 -28
  198. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/set-primary-address.md +72 -72
  199. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-additional-info.md +55 -55
  200. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-address.md +144 -144
  201. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-customer.md +123 -123
  202. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/attach-note-to-order.md +49 -49
  203. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-all-pages.md +21 -21
  204. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-single-page.md +55 -55
  205. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/delete-activity.md +28 -28
  206. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-country-info.md +29 -29
  207. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-dashboard-stats.md +22 -22
  208. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-filter-options.md +31 -31
  209. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-data.md +20 -20
  210. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-settings.md +20 -20
  211. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-print-templates.md +20 -20
  212. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-search-options.md +27 -27
  213. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-widgets.md +28 -28
  214. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/initialize-app.md +20 -20
  215. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-activities.md +33 -33
  216. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-attachments.md +21 -21
  217. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-countries.md +20 -20
  218. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/mark-activity-read.md +53 -53
  219. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/run-data-backfills.md +21 -21
  220. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-settings.md +54 -54
  221. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-tax-settings.md +73 -73
  222. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-print-templates.md +64 -64
  223. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/upload-attachment.md +42 -42
  224. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-customers-batch.md +129 -129
  225. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-licenses-batch.md +133 -133
  226. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-orders-batch.md +129 -129
  227. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-subscriptions-batch.md +129 -129
  228. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-customers-export-schema.md +21 -21
  229. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-licenses-export-schema.md +26 -26
  230. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-orders-export-schema.md +21 -21
  231. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-subscriptions-export-schema.md +21 -21
  232. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/enable-notification.md +57 -57
  233. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-digest-settings.md +22 -22
  234. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-notification.md +30 -30
  235. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-reminders.md +22 -22
  236. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-settings.md +22 -22
  237. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-shortcodes.md +22 -22
  238. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/list-notifications.md +20 -20
  239. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-default-template.md +66 -66
  240. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-notification.md +50 -50
  241. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-digest-settings.md +101 -101
  242. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-reminders.md +162 -162
  243. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-settings.md +99 -99
  244. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-digest-test.md +47 -47
  245. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-manual-reminder.md +51 -51
  246. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/update-notification.md +93 -93
  247. package/dist/skills/fluentcart-developer/references/restapi/operations/files/delete-file.md +31 -31
  248. package/dist/skills/fluentcart-developer/references/restapi/operations/files/get-bucket-list.md +28 -28
  249. package/dist/skills/fluentcart-developer/references/restapi/operations/files/list-files.md +30 -30
  250. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-editor-file.md +32 -32
  251. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-file.md +34 -34
  252. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/chained-data-request.md +46 -46
  253. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/change-feed-status.md +51 -51
  254. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/delete-feed.md +27 -27
  255. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-dynamic-options.md +29 -29
  256. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-lists.md +27 -27
  257. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-settings.md +27 -27
  258. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-feeds.md +20 -20
  259. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-settings.md +26 -26
  260. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/install-addon-plugin.md +49 -49
  261. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/list-addons.md +20 -20
  262. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/save-feed-settings.md +52 -52
  263. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/set-global-settings.md +50 -50
  264. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/bulk-update-stock.md +94 -94
  265. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/export-inventory.md +81 -81
  266. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-adjustment-history.md +26 -26
  267. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-inventory-stats.md +21 -21
  268. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/list-inventory.md +33 -33
  269. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/update-stock.md +75 -75
  270. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-attribute-group.md +31 -31
  271. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-label.md +31 -31
  272. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-terms.md +90 -90
  273. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-group.md +28 -28
  274. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-term.md +29 -29
  275. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-group.md +28 -28
  276. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-library.md +20 -20
  277. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-groups.md +32 -32
  278. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-terms.md +33 -33
  279. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-labels.md +20 -20
  280. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-groups.md +51 -51
  281. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-terms.md +56 -56
  282. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-group.md +37 -37
  283. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-term.md +39 -39
  284. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-label-selections.md +32 -32
  285. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-plugin-license.md +41 -41
  286. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-site-admin.md +60 -60
  287. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-plugin-license.md +18 -18
  288. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-admin.md +67 -67
  289. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-customer.md +47 -47
  290. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/delete-license.md +24 -24
  291. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/extend-license-validity.md +47 -47
  292. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-license-details.md +25 -25
  293. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-licenses-admin.md +26 -26
  294. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-activations.md +25 -25
  295. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-details.md +25 -25
  296. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-site.md +30 -30
  297. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-plugin-license-status.md +18 -18
  298. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-product-license-settings.md +24 -24
  299. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-customer-licenses.md +25 -25
  300. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-license-sites.md +33 -33
  301. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-licenses.md +38 -38
  302. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-activate-license.md +54 -54
  303. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-check-license.md +26 -26
  304. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-deactivate-license.md +46 -46
  305. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-download-license-package.md +23 -23
  306. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-get-license-version.md +26 -26
  307. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/regenerate-license-key.md +24 -24
  308. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/save-product-license-settings.md +193 -193
  309. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-activation-limit.md +53 -53
  310. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-status.md +52 -52
  311. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/create-order-bump.md +47 -47
  312. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/delete-order-bump.md +25 -25
  313. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/get-order-bump.md +25 -25
  314. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/list-order-bumps.md +29 -29
  315. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/update-order-bump.md +141 -141
  316. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/accept-dispute.md +47 -47
  317. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/bulk-actions.md +72 -72
  318. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-shipping.md +67 -67
  319. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-tax.md +98 -98
  320. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/change-customer.md +50 -50
  321. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/charge-now.md +29 -29
  322. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-and-change-customer.md +92 -92
  323. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-custom-order-item.md +68 -68
  324. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-order.md +351 -351
  325. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-renewal-now.md +29 -29
  326. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/delete-order.md +28 -28
  327. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/generate-missing-licenses.md +29 -29
  328. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order-transactions.md +27 -27
  329. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order.md +27 -27
  330. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-renewal.md +28 -28
  331. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-shipping-methods.md +28 -28
  332. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-single-transaction.md +28 -28
  333. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-order-currencies.md +22 -22
  334. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-orders.md +42 -42
  335. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-renewals.md +28 -28
  336. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/mark-as-paid.md +61 -61
  337. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/price-order.md +135 -135
  338. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/refund-order.md +72 -72
  339. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/resend-renewal-invoice.md +29 -29
  340. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/skip-renewal.md +48 -48
  341. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-order-statuses.md +28 -28
  342. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-pending-transaction.md +29 -29
  343. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address-id.md +60 -60
  344. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address.md +98 -98
  345. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order.md +172 -172
  346. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-statuses.md +77 -77
  347. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-subscription-details.md +84 -84
  348. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-transaction-status.md +51 -51
  349. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/void-renewal.md +30 -30
  350. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/create-pdf-template.md +42 -42
  351. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/delete-pdf-template.md +26 -26
  352. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/download-pdf-preview.md +44 -44
  353. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-factory-default-templates.md +19 -19
  354. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-status.md +21 -21
  355. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-template.md +26 -26
  356. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-saved-templates.md +21 -21
  357. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-seller-details.md +19 -19
  358. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/list-pdf-templates.md +19 -19
  359. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-pdf-template.md +53 -53
  360. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-seller-details.md +97 -97
  361. package/dist/skills/fluentcart-developer/references/restapi/operations/products/add-product-terms.md +64 -64
  362. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-edit-fetch.md +30 -30
  363. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-insert-products.md +62 -62
  364. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-products.md +59 -59
  365. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-variants.md +83 -83
  366. package/dist/skills/fluentcart-developer/references/restapi/operations/products/change-integration-status.md +64 -64
  367. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-dummy-products.md +45 -45
  368. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-product.md +81 -81
  369. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-variation.md +181 -181
  370. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-downloadable-file.md +27 -27
  371. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product-integration.md +30 -30
  372. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product.md +27 -27
  373. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-taxonomy-term.md +55 -55
  374. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-upgrade-path.md +27 -27
  375. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-variation.md +27 -27
  376. package/dist/skills/fluentcart-developer/references/restapi/operations/products/do-bulk-action.md +56 -56
  377. package/dist/skills/fluentcart-developer/references/restapi/operations/products/duplicate-product.md +56 -56
  378. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-products-by-ids.md +26 -26
  379. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-taxonomy-terms.md +20 -20
  380. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-terms-by-parent.md +60 -60
  381. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-variations-by-ids.md +26 -26
  382. package/dist/skills/fluentcart-developer/references/restapi/operations/products/find-subscription-variants.md +26 -26
  383. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-bundle-info.md +27 -27
  384. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-downloadable-url.md +27 -27
  385. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-max-excerpt-word-count.md +20 -20
  386. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-pricing-widgets.md +27 -27
  387. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-feeds.md +29 -29
  388. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-settings.md +31 -31
  389. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-pricing.md +28 -28
  390. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product.md +28 -28
  391. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-related-products.md +31 -31
  392. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-upgrade-settings.md +27 -27
  393. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-variation-upgrade-paths.md +28 -28
  394. package/dist/skills/fluentcart-developer/references/restapi/operations/products/group-bulk-update-variants.md +103 -103
  395. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-all-variants.md +26 -26
  396. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-product-variations.md +26 -26
  397. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-products.md +34 -34
  398. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-shipping-class.md +27 -27
  399. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-tax-class.md +27 -27
  400. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-bundle-info.md +56 -56
  401. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-product-integration.md +62 -62
  402. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-upgrade-path.md +78 -78
  403. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-product-variant-options.md +29 -29
  404. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-products-by-name.md +28 -28
  405. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-variants-by-name.md +28 -28
  406. package/dist/skills/fluentcart-developer/references/restapi/operations/products/set-variation-media.md +74 -74
  407. package/dist/skills/fluentcart-developer/references/restapi/operations/products/suggest-sku.md +28 -28
  408. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-downloadable-files.md +134 -134
  409. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-taxonomy-terms.md +61 -61
  410. package/dist/skills/fluentcart-developer/references/restapi/operations/products/toggle-product-tax-exemption.md +56 -56
  411. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-downloadable-file.md +98 -98
  412. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-inventory.md +56 -56
  413. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-long-desc-editor-mode.md +49 -49
  414. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-manage-stock.md +53 -53
  415. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-detail.md +58 -58
  416. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-pricing.md +225 -225
  417. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-shipping-class.md +49 -49
  418. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-tax-class.md +49 -49
  419. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-upgrade-path.md +78 -78
  420. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-option.md +79 -79
  421. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-tax-exemption.md +56 -56
  422. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation-pricing-table.md +49 -49
  423. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation.md +105 -105
  424. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/get-product-views.md +34 -34
  425. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/list-products.md +42 -42
  426. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/search-products.md +30 -30
  427. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/channel-rules.md +24 -24
  428. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/country-heat-map.md +22 -22
  429. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupon-overview.md +37 -37
  430. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupons.md +36 -36
  431. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-insights.md +31 -31
  432. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-overview.md +36 -36
  433. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-repeat.md +35 -35
  434. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segment-customers.md +36 -36
  435. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segments.md +30 -30
  436. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-value.md +34 -34
  437. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/dashboard-stats.md +30 -30
  438. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/failed-orders.md +34 -34
  439. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-new-vs-returning-customer.md +34 -34
  440. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-by-day-and-hour.md +34 -34
  441. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-meta.md +29 -29
  442. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-top-sold-products.md +34 -34
  443. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/future-renewals.md +31 -31
  444. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/generate-retention-snapshots.md +24 -24
  445. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-overview.md +30 -30
  446. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-activities.md +26 -26
  447. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-orders.md +20 -20
  448. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-revenue.md +37 -37
  449. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-at-risk.md +35 -35
  450. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-variations.md +33 -33
  451. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments.md +33 -33
  452. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/item-count-distribution.md +34 -34
  453. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-chart.md +30 -30
  454. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-pie-chart.md +22 -22
  455. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-summary.md +22 -22
  456. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/locations.md +43 -43
  457. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-chart.md +37 -37
  458. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-completion-time.md +34 -34
  459. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-mix.md +34 -34
  460. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-value-distribution.md +34 -34
  461. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-disputes.md +38 -38
  462. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-methods.md +36 -36
  463. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods.md +37 -37
  464. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison-launch.md +33 -33
  465. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison.md +40 -40
  466. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-detail.md +37 -37
  467. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-sales.md +37 -37
  468. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/refunds-overview.md +37 -37
  469. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/retention-snapshots-step.md +45 -45
  470. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sales-growth-chart.md +35 -35
  471. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/save-channel-rules.md +73 -73
  472. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/source-channels.md +37 -37
  473. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sources.md +49 -49
  474. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-cohorts.md +33 -33
  475. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-health.md +30 -30
  476. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-rebuys.md +37 -37
  477. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-retention.md +34 -34
  478. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-variations.md +22 -22
  479. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscriptions-overview.md +37 -37
  480. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/weeks-between-refund.md +34 -34
  481. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/assign-role.md +48 -48
  482. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/delete-role-assignment.md +47 -47
  483. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/get-role.md +25 -25
  484. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-managers.md +18 -18
  485. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-roles.md +18 -18
  486. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/search-users.md +25 -25
  487. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/update-role.md +43 -43
  488. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/create-saved-view.md +106 -106
  489. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/delete-saved-view.md +26 -26
  490. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/list-saved-views.md +25 -25
  491. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/update-saved-view.md +83 -83
  492. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-payment-addon.md +44 -44
  493. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-plugin-addon.md +44 -44
  494. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/change-storage-driver-status.md +56 -56
  495. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/check-paypal-webhook.md +26 -26
  496. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/create-storage-bucket.md +63 -63
  497. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/disconnect-payment-method.md +55 -55
  498. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/exchange-paypal-seller-auth-token.md +62 -62
  499. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-active-storage-drivers.md +20 -20
  500. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-checkout-fields.md +22 -22
  501. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-email-shortcodes.md +20 -20
  502. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-config-snippets.md +26 -26
  503. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-status.md +20 -20
  504. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-module-settings.md +20 -20
  505. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-connection-info.md +26 -26
  506. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-settings.md +26 -26
  507. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-permissions.md +22 -22
  508. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-plugin-addons.md +20 -20
  509. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-storage-driver-settings.md +27 -27
  510. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-store-settings.md +26 -26
  511. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-mcp-adapter.md +21 -21
  512. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-payment-addon.md +60 -60
  513. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-plugin-addon.md +64 -64
  514. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-payment-methods.md +20 -20
  515. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-storage-drivers.md +20 -20
  516. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-storage-buckets.md +67 -67
  517. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reorder-payment-methods.md +55 -55
  518. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reset-storage-driver-settings.md +45 -45
  519. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-checkout-fields.md +133 -133
  520. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-confirmation-settings.md +68 -68
  521. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-module-settings.md +68 -68
  522. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-design.md +67 -67
  523. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-settings.md +58 -58
  524. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-permissions.md +68 -68
  525. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-storage-driver-settings.md +62 -62
  526. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-store-settings.md +239 -239
  527. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/setup-paypal-webhook.md +48 -48
  528. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/toggle-mcp.md +40 -40
  529. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-storage-driver-connection.md +62 -62
  530. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-turnstile-keys.md +55 -55
  531. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-class.md +73 -73
  532. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-method.md +110 -110
  533. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-zone.md +56 -56
  534. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-class.md +29 -29
  535. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-method.md +29 -29
  536. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-zone.md +29 -29
  537. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class-profile.md +30 -30
  538. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class.md +29 -29
  539. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-packages.md +22 -22
  540. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-zone.md +27 -27
  541. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-countries.md +22 -22
  542. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-states.md +28 -28
  543. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-classes.md +31 -31
  544. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-zones.md +31 -31
  545. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/save-shipping-packages.md +112 -112
  546. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-class.md +79 -79
  547. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-method.md +113 -113
  548. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-zone.md +62 -62
  549. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-zone-order.md +52 -52
  550. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-auto-renew.md +30 -30
  551. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-subscription.md +52 -52
  552. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/confirm-subscription-switch.md +70 -70
  553. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/fetch-subscription-remote.md +28 -28
  554. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/generate-early-payment-link.md +29 -29
  555. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-customer-subscription.md +27 -27
  556. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-or-create-plan.md +69 -69
  557. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-setup-intent-attempts.md +30 -30
  558. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-subscription.md +28 -28
  559. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/initiate-early-payment.md +31 -31
  560. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-customer-subscriptions.md +27 -27
  561. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-subscriptions.md +39 -39
  562. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/pause-subscription.md +28 -28
  563. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/reactivate-subscription.md +28 -28
  564. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/resume-subscription.md +28 -28
  565. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/switch-payment-method.md +70 -70
  566. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-payment-method.md +69 -69
  567. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-vendor-ids.md +56 -56
  568. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/verify-vendor-ids.md +56 -56
  569. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-class.md +51 -51
  570. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-rate.md +117 -117
  571. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-product-override.md +27 -27
  572. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-shipping-tax-override.md +27 -27
  573. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-class.md +28 -28
  574. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-rate.md +27 -27
  575. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-id.md +27 -27
  576. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-rates.md +28 -28
  577. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-eu-vat-product-overrides.md +20 -20
  578. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-oss-country-rates.md +20 -20
  579. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-preconfigured-tax-rates.md +20 -20
  580. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-product-overrides.md +27 -27
  581. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-tax-settings.md +20 -20
  582. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-all-tax-rates.md +20 -20
  583. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-classes.md +20 -20
  584. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-records.md +37 -37
  585. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/mark-taxes-as-filed.md +58 -58
  586. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/reset-eu-vat-rates.md +21 -21
  587. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-configured-countries.md +57 -57
  588. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-country-tax-id.md +50 -50
  589. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-eu-vat-cross-border-settings.md +127 -127
  590. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-oss-country-rates.md +100 -100
  591. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-product-override.md +110 -110
  592. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-shipping-tax-override.md +52 -52
  593. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-tax-settings.md +166 -166
  594. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-country-status.md +54 -54
  595. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-tax-rate.md +116 -116
  596. package/dist/skills/fluentcart-developer/references/restapi/order-bumps.md +433 -433
  597. package/dist/skills/fluentcart-developer/references/restapi/orders.md +1212 -1212
  598. package/dist/skills/fluentcart-developer/references/restapi/pdf-templates.md +212 -212
  599. package/dist/skills/fluentcart-developer/references/restapi/products.md +2485 -2485
  600. package/dist/skills/fluentcart-developer/references/restapi/public-shop.md +191 -191
  601. package/dist/skills/fluentcart-developer/references/restapi/reports.md +3773 -3773
  602. package/dist/skills/fluentcart-developer/references/restapi/roles.md +403 -403
  603. package/dist/skills/fluentcart-developer/references/restapi/saved-views.md +136 -136
  604. package/dist/skills/fluentcart-developer/references/restapi/settings.md +1423 -1423
  605. package/dist/skills/fluentcart-developer/references/restapi/shipping.md +905 -905
  606. package/dist/skills/fluentcart-developer/references/restapi/subscriptions.md +1169 -1169
  607. package/dist/skills/fluentcart-developer/references/restapi/tax.md +1551 -1551
  608. package/dist/skills/fluentcart-developer/references/restapi.md +127 -127
  609. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  610. package/dist/version.d.ts +1 -1
  611. package/dist/version.js +1 -1
  612. package/package.json +66 -65
@@ -1,481 +1,481 @@
1
- # Labels and Tracking
2
-
3
- An admin creates a shipment from the order screen by choosing a carrier and the items to send. These methods connect your carrier to that flow. Add `labels` and `tracking` to `meta()['supports']`, and an `enable_labels` toggle to your settings.
4
-
5
- ```
6
- 'supports' => ['rates', 'labels', 'tracking'],
7
- ```
8
-
9
- The form offers your label purchase only when the carrier is enabled, `supports` lists `labels`, and the `enable_labels` setting is `yes`. Your rate picker follows the same rule when you declare both `rates` and `labels`. All registered carriers can be picked to record a shipment by hand, even when disabled.
10
-
11
- The admin's selection reaches your methods as a `ShipmentInstance`:
12
-
13
- | Property | Contents |
14
- | --- | --- |
15
- | `$instance->order` | The [`Order`](/database/models/order.md) |
16
- | `$instance->items` | The items in this shipment: `[['order_item_id' => int, 'qty' => int], ...]` |
17
- | `$instance->data` | The validated form data, such as `carrier_slug` and `selected_rate_id` |
18
- | `$instance->shipment` | The `Shipment` row when one exists. It is `null` during creation. |
19
-
20
- If your carrier throws while quoting, buying or voiding, the admin gets an error message and the request does not fail.
21
-
22
- The examples on this page use these imports:
23
-
24
- ```
25
- use FluentCart\App\App;
26
- use FluentCart\App\Helpers\Helper;
27
- use FluentCart\App\Models\OrderItem;
28
- use FluentCart\App\Models\Shipment;
29
- use FluentCart\App\Modules\Shipping\Carriers\Concerns\WebhookOutcomes;
30
- use FluentCart\App\Services\ShipmentService;
31
- use FluentCart\App\Services\Shipments\ShipmentInstance;
32
- use FluentCart\Framework\Support\Arr;
33
- ```
34
-
35
- ## Pricing a shipment
36
-
37
- `getShipmentQuote()` fills the rate picker. It buys nothing. Return `null` when your carrier does not quote.
38
-
39
- ```
40
- public function getShipmentQuote(ShipmentInstance $instance)
41
- {
42
- if ($this->settings->get('enable_labels') !== 'yes') {
43
- return new \WP_Error('acme_labels_off', __('Labels are turned off in Acme Parcel settings.', 'acme-parcel-for-fluent-cart'));
44
- }
45
-
46
- $response = $this->request('POST', '/rates', $this->shipmentPayload($instance), 15);
47
- if (is_wp_error($response)) {
48
- return $response;
49
- }
50
-
51
- $rates = [];
52
- foreach ((array) Arr::get($response, 'rates', []) as $rate) {
53
- $rates[] = [
54
- 'rate_object_id' => sanitize_text_field((string) Arr::get($rate, 'id')),
55
- 'service_name' => sanitize_text_field((string) Arr::get($rate, 'name')),
56
- 'cost_cents' => Helper::toCent(Arr::get($rate, 'amount')),
57
- 'currency' => strtoupper((string) Arr::get($rate, 'currency')),
58
- 'estimated_days' => max(0, (int) Arr::get($rate, 'days')),
59
- ];
60
- }
61
-
62
- return [
63
- 'rate_object_id' => $rates ? $rates[0]['rate_object_id'] : '',
64
- 'rates' => $rates,
65
- ];
66
- }
67
- ```
68
-
69
- `rate_object_id` at the top level is the rate selected by default. To match the customer's choice, compare your rates with `$instance->order->config['shipping_method_id']`.
70
-
71
- These rates are what the merchant pays you, so they stay in your billing currency and are not converted. FluentCart adds an approximate figure in the order's currency for the admin.
72
-
73
- ## Buying the label
74
-
75
- `makeShipmentFromShipmentInstance()` runs before the shipment row is written and outside any database transaction, so a refusal leaves nothing behind.
76
-
77
- ```
78
- public function makeShipmentFromShipmentInstance(ShipmentInstance $instance)
79
- {
80
- if ($this->settings->get('enable_labels') !== 'yes') {
81
- return null;
82
- }
83
-
84
- $response = $this->request('POST', '/labels', array_merge($this->shipmentPayload($instance), [
85
- 'rate' => (string) Arr::get($instance->data, 'selected_rate_id', ''),
86
- 'idempotency_key' => (string) Arr::get($instance->data, 'unconfirmed_id', ''),
87
- ]), 30);
88
-
89
- if (is_wp_error($response)) {
90
- $status = (int) Arr::get((array) $response->get_error_data(), 'http_code', 0);
91
- if ($status === 0 || $status >= 500) {
92
- return new \WP_Error(
93
- 'acme_purchase_unconfirmed',
94
- __('Acme Parcel did not confirm the purchase. Check your dashboard before trying again.', 'acme-parcel-for-fluent-cart'),
95
- ['purchase_unconfirmed' => true]
96
- );
97
- }
98
-
99
- return $response;
100
- }
101
-
102
- return [
103
- 'tracking_number' => (string) Arr::get($response, 'tracking_number'),
104
- 'tracking_url' => (string) Arr::get($response, 'tracking_url'),
105
- 'service_name' => (string) Arr::get($response, 'service_name'),
106
- 'label_url' => (string) Arr::get($response, 'label_url'),
107
- 'transaction_id' => (string) Arr::get($response, 'id'),
108
- 'cost' => Helper::toCent(Arr::get($response, 'amount')),
109
- 'currency' => strtoupper((string) Arr::get($response, 'currency')),
110
- ];
111
- }
112
- ```
113
-
114
- | Return | Result |
115
- | --- | --- |
116
- | Array | The shipment is recorded with this label. |
117
- | `WP_Error` | Nothing is recorded and the admin sees the message. |
118
- | `null` | Your carrier does not dispatch this shipment. It is recorded from what the admin typed. |
119
-
120
- The array keys FluentCart keeps:
121
-
122
- | Key | Stored as |
123
- | --- | --- |
124
- | `tracking_number`, `tracking_url` | Shipment columns. They replace anything the admin typed. |
125
- | `service_name`, `label_url` | `$shipment->meta` |
126
- | `transaction_id` | `$shipment->meta`. Your label ID, used to void and fetch the label again. |
127
- | `cost`, `currency` | `$shipment->meta['cost']` and `['cost_currency']`. Integer cents in the label's own currency. |
128
-
129
- Read the address from the order and the package details from the order items:
130
-
131
- ```
132
- protected function shipmentPayload(ShipmentInstance $instance): array
133
- {
134
- $order = $instance->order;
135
- $address = $order->shipping_address ?: $order->billing_address;
136
-
137
- return [
138
- 'from' => $this->buildOrigin(),
139
- 'to' => [
140
- 'name' => (string) $address->name,
141
- 'address_1' => (string) $address->address_1,
142
- 'address_2' => (string) $address->address_2,
143
- 'city' => (string) $address->city,
144
- 'state' => (string) $address->state,
145
- 'postcode' => (string) $address->postcode,
146
- 'country' => strtoupper((string) $address->country),
147
- 'phone' => (string) $address->phone,
148
- ],
149
- 'lines' => $this->dispatchLines($instance),
150
- ];
151
- }
152
-
153
- protected function dispatchLines(ShipmentInstance $instance): array
154
- {
155
- $orderItems = OrderItem::query()
156
- ->whereIn('id', array_map('intval', array_column($instance->items, 'order_item_id')))
157
- ->where('order_id', $instance->order->id)
158
- ->get()
159
- ->keyBy('id');
160
-
161
- $lines = [];
162
- foreach ($instance->items as $dispatched) {
163
- $itemId = (int) $dispatched['order_item_id'];
164
- if (!isset($orderItems[$itemId])) {
165
- continue;
166
- }
167
- $info = (array) $orderItems[$itemId]->other_info;
168
- $lines[] = [
169
- 'sku' => (string) $orderItems[$itemId]->object_id,
170
- 'quantity' => (int) $dispatched['qty'],
171
- 'weight' => (float) Arr::get($info, 'weight', 0),
172
- 'weight_unit' => (string) Arr::get($info, 'weight_unit', ''),
173
- 'box' => Arr::only($info, ['package_length', 'package_width', 'package_height', 'package_dimension_unit', 'package_weight', 'package_weight_unit']),
174
- ];
175
- }
176
-
177
- return $lines;
178
- }
179
- ```
180
-
181
- `weight` is one unit's weight, without its box. The `package_*` keys describe the box as it was when the order was placed, and `package_weight` is the empty box. The shipment's `getPackages()` helper reads only the box, so use it for dimensions and take the contents' weight from `weight`.
182
-
183
- To store more on the shipment, such as parcel details for a multi-parcel label, listen to `fluent_cart/order_shipment_created` and save to `$shipment->meta`.
184
-
185
- ### When the purchase result is unknown
186
-
187
- A timeout or 5xx during purchase may still have bought a label, and a retry could buy a second one. Tell FluentCart the result is unknown by adding `purchase_unconfirmed` to the error data, or by ending the error code with `_purchase_unconfirmed` or `_label_pending`:
188
-
189
- ```
190
- return new \WP_Error('acme_purchase_unconfirmed', $message, ['purchase_unconfirmed' => true]);
191
- ```
192
-
193
- FluentCart saves the attempt before calling you, and keeps it on the order after this error. The admin can then mark it resolved. Each attempt has an ID in `$instance->data['unconfirmed_id']`, which makes a good idempotency key for your API.
194
-
195
- To add a **Check again** button, implement `supportsUnconfirmedRecheck()` and return `true`. FluentCart then calls `makeShipmentFromShipmentInstance()` again with `$instance->data['lookup_only']` set to true. You must never buy in this case:
196
-
197
- ```
198
- if (!empty($instance->data['lookup_only'])) {
199
- // Your own lookup, by the attempt ID you sent as the idempotency key.
200
- $label = $this->findLabelByAttempt((string) $instance->data['unconfirmed_id']);
201
-
202
- return $label ?: new \WP_Error(
203
- 'acme_label_not_found',
204
- __('No label was found. You can buy a new one.', 'acme-parcel-for-fluent-cart')
205
- );
206
- }
207
- ```
208
-
209
- Return the same array as a purchase when you find the label. An error code ending in `_label_not_found` closes the attempt, unless the attempt is less than 5 minutes old or the error data has `purchase_unconfirmed`. Any other error leaves the attempt open. `fluent_cart/shipping/unconfirmed_purchase_resolved` fires when an attempt closes, if you keep your own records for it.
210
-
211
- ### When the label arrives later
212
-
213
- Some carriers accept the order first and send the tracking number and label later. Return the array without them, keeping the `transaction_id` so you can find the shipment again. FluentCart records the shipment with an empty tracking number.
214
-
215
- When your carrier sends the details, usually by webhook, save them on the shipment:
216
-
217
- ```
218
- protected function applyLateLabel(array $payload): array
219
- {
220
- $labelId = sanitize_text_field((string) Arr::get($payload, 'label_id'));
221
- $shipments = Shipment::query()
222
- ->where('carrier_slug', self::SLUG)
223
- ->where('order_id', (int) Arr::get($payload, 'reference'))
224
- ->get();
225
-
226
- foreach ($shipments as $shipment) {
227
- $meta = (array) $shipment->meta;
228
- if ((string) Arr::get($meta, 'transaction_id') !== $labelId) {
229
- continue;
230
- }
231
-
232
- $meta['label_url'] = esc_url_raw((string) Arr::get($payload, 'label_url'), ['https']);
233
- $shipment->meta = $meta;
234
- $shipment->tracking_number = sanitize_text_field((string) Arr::get($payload, 'tracking_number'));
235
- $shipment->tracking_url = $this->getTrackingUrl($shipment->tracking_number);
236
- $shipment->save();
237
-
238
- return $this->webhookApplied($shipment, true);
239
- }
240
-
241
- return $this->webhookIgnored('unknown_shipment');
242
- }
243
- ```
244
-
245
- Send your carrier the order ID as the reference, so the webhook can find the order. `processWebhook()` then sends this event to the method above:
246
-
247
- ```
248
- if (Arr::get($payload, 'event') === 'label.updated') {
249
- return $this->applyLateLabel($payload);
250
- }
251
- ```
252
-
253
- Until the details arrive:
254
-
255
- - The refresh action does not appear, because the shipment has no tracking number.
256
- - `hasLabel()` is true as soon as the shipment has a `transaction_id`. If `getLabelDownloadUrl()` has no link yet, return a `WP_Error` that says the label is not ready. An empty string shows "This shipment has no label to print."
257
- - If the admin leaves the customer notification on, the shipment email goes out straight away, without the tracking number. The customer's order page shows the number once you save it.
258
-
259
- ## Voiding a label
260
-
261
- FluentCart calls this when an admin deletes a shipment, and when a label was bought but the shipment could not be recorded.
262
-
263
- ```
264
- public function cancelShipmentFromShipmentInstance(ShipmentInstance $instance)
265
- {
266
- $labelId = (string) Arr::get($instance->data, 'transaction_id', '');
267
- if ($labelId === '') {
268
- return null;
269
- }
270
-
271
- $response = $this->request('DELETE', '/labels/' . rawurlencode($labelId), [], 15);
272
-
273
- return is_wp_error($response) ? $response : true;
274
- }
275
- ```
276
-
277
- The label ID is always in `$instance->data['transaction_id']`. Return `true` when voided, a `WP_Error` when your carrier refused, and `null` when there was nothing to void. A refusal is shown to the admin and logged on the order.
278
-
279
- ## Printing a label
280
-
281
- Label links expire, so FluentCart stores no PDF and asks you for a link each time.
282
-
283
- ```
284
- public function hasLabel(Shipment $shipment): bool
285
- {
286
- return (string) Arr::get((array) $shipment->meta, 'transaction_id', '') !== '';
287
- }
288
-
289
- public function getLabelDownloadUrl(Shipment $shipment)
290
- {
291
- $response = $this->request('GET', '/labels/' . rawurlencode((string) Arr::get((array) $shipment->meta, 'transaction_id', '')), [], 8);
292
- if (is_wp_error($response)) {
293
- return $response;
294
- }
295
-
296
- return esc_url_raw((string) Arr::get($response, 'label_url'), ['https']);
297
- }
298
- ```
299
-
300
- `hasLabel()` runs for every shipment in a list, so it must not call your API. `getLabelDownloadUrl()` must return an `https://` link to a PDF of at most 5 MB, an empty string when there is no label, or a `WP_Error`.
301
-
302
- ## Tracking
303
-
304
- `getTrackingUrl()` gives the public link used when your label result has no `tracking_url`, and when an admin types a tracking number.
305
-
306
- ```
307
- public function getTrackingUrl(string $trackingNumber): string
308
- {
309
- return 'https://track.acme-parcel.example/' . rawurlencode($trackingNumber);
310
- }
311
- ```
312
-
313
- To add the admin's refresh action, implement the two sync methods and report the status through `ShipmentService::applyTrackingUpdate()`:
314
-
315
- ```
316
- public function supportsTrackingSync(): bool
317
- {
318
- return $this->isEnabled();
319
- }
320
-
321
- public function syncTrackingFromShipmentInstance(ShipmentInstance $instance)
322
- {
323
- return $instance->shipment ? $this->pullTracking($instance->shipment) : null;
324
- }
325
-
326
- /**
327
- * @return bool|\WP_Error True when a new status was applied.
328
- */
329
- protected function pullTracking(Shipment $shipment)
330
- {
331
- $track = $this->request('GET', '/tracking/' . rawurlencode((string) $shipment->tracking_number), [], 8);
332
- if (is_wp_error($track)) {
333
- return $track;
334
- }
335
-
336
- $statuses = [
337
- 'accepted' => Shipment::STATUS_DISPATCHED,
338
- 'in_transit' => Shipment::STATUS_IN_TRANSIT,
339
- 'delivered' => Shipment::STATUS_DELIVERED,
340
- 'returned' => Shipment::STATUS_RETURNED,
341
- 'failed' => Shipment::STATUS_FAILED,
342
- ];
343
- $status = (string) Arr::get($track, 'status');
344
- if (!isset($statuses[$status])) {
345
- return false;
346
- }
347
-
348
- $result = ShipmentService::applyTrackingUpdate($shipment, $statuses[$status], [
349
- 'tracking_status' => $status,
350
- 'tracking_status_date' => sanitize_text_field((string) Arr::get($track, 'updated_at')),
351
- 'tracking_status_details' => sanitize_text_field((string) Arr::get($track, 'details')),
352
- ]);
353
-
354
- return is_wp_error($result) ? $result : (bool) $result;
355
- }
356
- ```
357
-
358
- `applyTrackingUpdate()` is safe to call with old or repeated events:
359
-
360
- - An event no newer than the stored one is ignored. It compares `tracking_status_date` when both events have one, and otherwise the shipment's stage.
361
- - `delivered` and `returned` are final. Later events can add details but cannot change the status.
362
- - It returns `true` only when the status changed.
363
-
364
- | Shipment status | Constant |
365
- | --- | --- |
366
- | `dispatched` | `Shipment::STATUS_DISPATCHED` |
367
- | `in_transit` | `Shipment::STATUS_IN_TRANSIT` |
368
- | `delivered` | `Shipment::STATUS_DELIVERED` |
369
- | `returned` | `Shipment::STATUS_RETURNED` |
370
- | `failed` | `Shipment::STATUS_FAILED` |
371
-
372
- When the last shipment is delivered, FluentCart moves the order's shipping status to `delivered`. A change fires `fluent_cart/shipment_tracking_updated`, then `fluent_cart/order_shipment_status_changed_to_{status}` and `fluent_cart/order_shipment_status_changed`.
373
-
374
- The refresh action appears for a shipment with a tracking number and a status that can still change, when it has a `transaction_id`. To track shipments without one, implement `canTrackWithoutLabel()` and return `true`.
375
-
376
- ## Webhooks
377
-
378
- FluentCart gives every carrier a public endpoint:
379
-
380
- ```
381
- https://your-site.com/?fluent-cart=fct_shipping_listener_webhook&carrier={slug}
382
- ```
383
-
384
- It finds your carrier by `carrier` and calls `handleWebhook()`. An unknown slug gets a 404, and an exception from your code gets a 500 so your carrier retries. **You authenticate the request and send the response.**
385
-
386
- Create the secret when settings are saved. It is not a declared field, so it is never returned by the settings API.
387
-
388
- ```
389
- public function validateSettings(array $settings)
390
- {
391
- if (!$this->settings->get('webhook_secret')) {
392
- $settings['webhook_secret'] = wp_generate_password(32, false);
393
- }
394
-
395
- return $settings;
396
- }
397
-
398
- public function getWebhookUrl(): string
399
- {
400
- $secret = (string) $this->settings->get('webhook_secret');
401
- if ($secret === '') {
402
- return '';
403
- }
404
-
405
- return add_query_arg([
406
- 'fluent-cart' => 'fct_shipping_listener_webhook',
407
- 'carrier' => self::SLUG,
408
- 'token' => $secret,
409
- ], home_url('/'));
410
- }
411
-
412
- public function handleWebhook(): void
413
- {
414
- $token = (string) App::request()->getSafe('token', 'sanitize_text_field');
415
- $payload = json_decode((string) file_get_contents('php://input'), true);
416
-
417
- list($status, $body) = $this->processWebhook($token, is_array($payload) ? $payload : []);
418
-
419
- wp_send_json($body, $status);
420
- }
421
-
422
- public function processWebhook(string $token, array $payload): array
423
- {
424
- $secret = (string) $this->settings->get('webhook_secret');
425
- if ($secret === '' || !hash_equals($secret, $token)) {
426
- return $this->webhookRejected(401, 'invalid_token');
427
- }
428
-
429
- if (Arr::get($payload, 'event') !== 'tracking.updated') {
430
- return $this->webhookIgnored('event');
431
- }
432
-
433
- $shipment = Shipment::query()
434
- ->where('carrier_slug', self::SLUG)
435
- ->where('tracking_number', sanitize_text_field((string) Arr::get($payload, 'tracking_number')))
436
- ->first();
437
-
438
- if (!$shipment) {
439
- return $this->webhookIgnored('unknown_shipment');
440
- }
441
-
442
- $applied = $this->pullTracking($shipment);
443
- if (is_wp_error($applied)) {
444
- return $this->webhookFailed(502, 'refetch_failed', $applied->get_error_message(), $shipment);
445
- }
446
-
447
- return $this->webhookApplied($shipment, $applied);
448
- }
449
- ```
450
-
451
- Treat the webhook body as a notice only. Use it to find the shipment, then read the status from your API, so a forged or replayed event cannot change anything.
452
-
453
- `getWebhookUrl()` returns the URL the merchant copies. FluentCart shows it on the settings page with `meta()['webhook_hint']` as the instructions. Return an empty string if your carrier takes no webhooks.
454
-
455
- ### Outcomes
456
-
457
- The `WebhookOutcomes` trait gives every response the same shape. FluentCart reads the response to write a log entry, which never includes the token or body.
458
-
459
- | Method | HTTP | `outcome` | Use it when |
460
- | --- | --- | --- | --- |
461
- | `webhookApplied($shipment, true)` | 200 | `applied` | The status changed. |
462
- | `webhookApplied($shipment, false)` | 200 | `unchanged` | Nothing changed. |
463
- | `webhookIgnored($reason, $shipment, $details)` | 200 | `ignored` | You will never use this event, so your carrier should not retry it. |
464
- | `webhookRejected($status, $reason, $message)` | your status | `rejected` | Authentication failed. |
465
- | `webhookFailed($status, $reason, $message, $shipment)` | your status | `error` | Your read failed. Use a 5xx so your carrier retries. |
466
-
467
- Repeated outcomes are logged at most once an hour. Turn off these log entries with `fluent_cart/shipping/log_carrier_webhooks`.
468
-
469
- ## Changing a shipment before dispatch
470
-
471
- Other plugins can adjust the instance before your carrier is called, or skip the carrier and record the shipment by hand:
472
-
473
- ```
474
- add_filter('fluent_cart/before_carrier_dispatch', function ($instance, $context) {
475
- if ($context['carrier_slug'] === 'acme' && $instance->order->total_amount > 100000) {
476
- return null; // Not a ShipmentInstance: the carrier is skipped.
477
- }
478
-
479
- return $instance;
480
- }, 10, 2);
481
- ```
1
+ # Labels and Tracking
2
+
3
+ An admin creates a shipment from the order screen by choosing a carrier and the items to send. These methods connect your carrier to that flow. Add `labels` and `tracking` to `meta()['supports']`, and an `enable_labels` toggle to your settings.
4
+
5
+ ```
6
+ 'supports' => ['rates', 'labels', 'tracking'],
7
+ ```
8
+
9
+ The form offers your label purchase only when the carrier is enabled, `supports` lists `labels`, and the `enable_labels` setting is `yes`. Your rate picker follows the same rule when you declare both `rates` and `labels`. All registered carriers can be picked to record a shipment by hand, even when disabled.
10
+
11
+ The admin's selection reaches your methods as a `ShipmentInstance`:
12
+
13
+ | Property | Contents |
14
+ | --- | --- |
15
+ | `$instance->order` | The [`Order`](/database/models/order.md) |
16
+ | `$instance->items` | The items in this shipment: `[['order_item_id' => int, 'qty' => int], ...]` |
17
+ | `$instance->data` | The validated form data, such as `carrier_slug` and `selected_rate_id` |
18
+ | `$instance->shipment` | The `Shipment` row when one exists. It is `null` during creation. |
19
+
20
+ If your carrier throws while quoting, buying or voiding, the admin gets an error message and the request does not fail.
21
+
22
+ The examples on this page use these imports:
23
+
24
+ ```
25
+ use FluentCart\App\App;
26
+ use FluentCart\App\Helpers\Helper;
27
+ use FluentCart\App\Models\OrderItem;
28
+ use FluentCart\App\Models\Shipment;
29
+ use FluentCart\App\Modules\Shipping\Carriers\Concerns\WebhookOutcomes;
30
+ use FluentCart\App\Services\ShipmentService;
31
+ use FluentCart\App\Services\Shipments\ShipmentInstance;
32
+ use FluentCart\Framework\Support\Arr;
33
+ ```
34
+
35
+ ## Pricing a shipment
36
+
37
+ `getShipmentQuote()` fills the rate picker. It buys nothing. Return `null` when your carrier does not quote.
38
+
39
+ ```
40
+ public function getShipmentQuote(ShipmentInstance $instance)
41
+ {
42
+ if ($this->settings->get('enable_labels') !== 'yes') {
43
+ return new \WP_Error('acme_labels_off', __('Labels are turned off in Acme Parcel settings.', 'acme-parcel-for-fluent-cart'));
44
+ }
45
+
46
+ $response = $this->request('POST', '/rates', $this->shipmentPayload($instance), 15);
47
+ if (is_wp_error($response)) {
48
+ return $response;
49
+ }
50
+
51
+ $rates = [];
52
+ foreach ((array) Arr::get($response, 'rates', []) as $rate) {
53
+ $rates[] = [
54
+ 'rate_object_id' => sanitize_text_field((string) Arr::get($rate, 'id')),
55
+ 'service_name' => sanitize_text_field((string) Arr::get($rate, 'name')),
56
+ 'cost_cents' => Helper::toCent(Arr::get($rate, 'amount')),
57
+ 'currency' => strtoupper((string) Arr::get($rate, 'currency')),
58
+ 'estimated_days' => max(0, (int) Arr::get($rate, 'days')),
59
+ ];
60
+ }
61
+
62
+ return [
63
+ 'rate_object_id' => $rates ? $rates[0]['rate_object_id'] : '',
64
+ 'rates' => $rates,
65
+ ];
66
+ }
67
+ ```
68
+
69
+ `rate_object_id` at the top level is the rate selected by default. To match the customer's choice, compare your rates with `$instance->order->config['shipping_method_id']`.
70
+
71
+ These rates are what the merchant pays you, so they stay in your billing currency and are not converted. FluentCart adds an approximate figure in the order's currency for the admin.
72
+
73
+ ## Buying the label
74
+
75
+ `makeShipmentFromShipmentInstance()` runs before the shipment row is written and outside any database transaction, so a refusal leaves nothing behind.
76
+
77
+ ```
78
+ public function makeShipmentFromShipmentInstance(ShipmentInstance $instance)
79
+ {
80
+ if ($this->settings->get('enable_labels') !== 'yes') {
81
+ return null;
82
+ }
83
+
84
+ $response = $this->request('POST', '/labels', array_merge($this->shipmentPayload($instance), [
85
+ 'rate' => (string) Arr::get($instance->data, 'selected_rate_id', ''),
86
+ 'idempotency_key' => (string) Arr::get($instance->data, 'unconfirmed_id', ''),
87
+ ]), 30);
88
+
89
+ if (is_wp_error($response)) {
90
+ $status = (int) Arr::get((array) $response->get_error_data(), 'http_code', 0);
91
+ if ($status === 0 || $status >= 500) {
92
+ return new \WP_Error(
93
+ 'acme_purchase_unconfirmed',
94
+ __('Acme Parcel did not confirm the purchase. Check your dashboard before trying again.', 'acme-parcel-for-fluent-cart'),
95
+ ['purchase_unconfirmed' => true]
96
+ );
97
+ }
98
+
99
+ return $response;
100
+ }
101
+
102
+ return [
103
+ 'tracking_number' => (string) Arr::get($response, 'tracking_number'),
104
+ 'tracking_url' => (string) Arr::get($response, 'tracking_url'),
105
+ 'service_name' => (string) Arr::get($response, 'service_name'),
106
+ 'label_url' => (string) Arr::get($response, 'label_url'),
107
+ 'transaction_id' => (string) Arr::get($response, 'id'),
108
+ 'cost' => Helper::toCent(Arr::get($response, 'amount')),
109
+ 'currency' => strtoupper((string) Arr::get($response, 'currency')),
110
+ ];
111
+ }
112
+ ```
113
+
114
+ | Return | Result |
115
+ | --- | --- |
116
+ | Array | The shipment is recorded with this label. |
117
+ | `WP_Error` | Nothing is recorded and the admin sees the message. |
118
+ | `null` | Your carrier does not dispatch this shipment. It is recorded from what the admin typed. |
119
+
120
+ The array keys FluentCart keeps:
121
+
122
+ | Key | Stored as |
123
+ | --- | --- |
124
+ | `tracking_number`, `tracking_url` | Shipment columns. They replace anything the admin typed. |
125
+ | `service_name`, `label_url` | `$shipment->meta` |
126
+ | `transaction_id` | `$shipment->meta`. Your label ID, used to void and fetch the label again. |
127
+ | `cost`, `currency` | `$shipment->meta['cost']` and `['cost_currency']`. Integer cents in the label's own currency. |
128
+
129
+ Read the address from the order and the package details from the order items:
130
+
131
+ ```
132
+ protected function shipmentPayload(ShipmentInstance $instance): array
133
+ {
134
+ $order = $instance->order;
135
+ $address = $order->shipping_address ?: $order->billing_address;
136
+
137
+ return [
138
+ 'from' => $this->buildOrigin(),
139
+ 'to' => [
140
+ 'name' => (string) $address->name,
141
+ 'address_1' => (string) $address->address_1,
142
+ 'address_2' => (string) $address->address_2,
143
+ 'city' => (string) $address->city,
144
+ 'state' => (string) $address->state,
145
+ 'postcode' => (string) $address->postcode,
146
+ 'country' => strtoupper((string) $address->country),
147
+ 'phone' => (string) $address->phone,
148
+ ],
149
+ 'lines' => $this->dispatchLines($instance),
150
+ ];
151
+ }
152
+
153
+ protected function dispatchLines(ShipmentInstance $instance): array
154
+ {
155
+ $orderItems = OrderItem::query()
156
+ ->whereIn('id', array_map('intval', array_column($instance->items, 'order_item_id')))
157
+ ->where('order_id', $instance->order->id)
158
+ ->get()
159
+ ->keyBy('id');
160
+
161
+ $lines = [];
162
+ foreach ($instance->items as $dispatched) {
163
+ $itemId = (int) $dispatched['order_item_id'];
164
+ if (!isset($orderItems[$itemId])) {
165
+ continue;
166
+ }
167
+ $info = (array) $orderItems[$itemId]->other_info;
168
+ $lines[] = [
169
+ 'sku' => (string) $orderItems[$itemId]->object_id,
170
+ 'quantity' => (int) $dispatched['qty'],
171
+ 'weight' => (float) Arr::get($info, 'weight', 0),
172
+ 'weight_unit' => (string) Arr::get($info, 'weight_unit', ''),
173
+ 'box' => Arr::only($info, ['package_length', 'package_width', 'package_height', 'package_dimension_unit', 'package_weight', 'package_weight_unit']),
174
+ ];
175
+ }
176
+
177
+ return $lines;
178
+ }
179
+ ```
180
+
181
+ `weight` is one unit's weight, without its box. The `package_*` keys describe the box as it was when the order was placed, and `package_weight` is the empty box. The shipment's `getPackages()` helper reads only the box, so use it for dimensions and take the contents' weight from `weight`.
182
+
183
+ To store more on the shipment, such as parcel details for a multi-parcel label, listen to `fluent_cart/order_shipment_created` and save to `$shipment->meta`.
184
+
185
+ ### When the purchase result is unknown
186
+
187
+ A timeout or 5xx during purchase may still have bought a label, and a retry could buy a second one. Tell FluentCart the result is unknown by adding `purchase_unconfirmed` to the error data, or by ending the error code with `_purchase_unconfirmed` or `_label_pending`:
188
+
189
+ ```
190
+ return new \WP_Error('acme_purchase_unconfirmed', $message, ['purchase_unconfirmed' => true]);
191
+ ```
192
+
193
+ FluentCart saves the attempt before calling you, and keeps it on the order after this error. The admin can then mark it resolved. Each attempt has an ID in `$instance->data['unconfirmed_id']`, which makes a good idempotency key for your API.
194
+
195
+ To add a **Check again** button, implement `supportsUnconfirmedRecheck()` and return `true`. FluentCart then calls `makeShipmentFromShipmentInstance()` again with `$instance->data['lookup_only']` set to true. You must never buy in this case:
196
+
197
+ ```
198
+ if (!empty($instance->data['lookup_only'])) {
199
+ // Your own lookup, by the attempt ID you sent as the idempotency key.
200
+ $label = $this->findLabelByAttempt((string) $instance->data['unconfirmed_id']);
201
+
202
+ return $label ?: new \WP_Error(
203
+ 'acme_label_not_found',
204
+ __('No label was found. You can buy a new one.', 'acme-parcel-for-fluent-cart')
205
+ );
206
+ }
207
+ ```
208
+
209
+ Return the same array as a purchase when you find the label. An error code ending in `_label_not_found` closes the attempt, unless the attempt is less than 5 minutes old or the error data has `purchase_unconfirmed`. Any other error leaves the attempt open. `fluent_cart/shipping/unconfirmed_purchase_resolved` fires when an attempt closes, if you keep your own records for it.
210
+
211
+ ### When the label arrives later
212
+
213
+ Some carriers accept the order first and send the tracking number and label later. Return the array without them, keeping the `transaction_id` so you can find the shipment again. FluentCart records the shipment with an empty tracking number.
214
+
215
+ When your carrier sends the details, usually by webhook, save them on the shipment:
216
+
217
+ ```
218
+ protected function applyLateLabel(array $payload): array
219
+ {
220
+ $labelId = sanitize_text_field((string) Arr::get($payload, 'label_id'));
221
+ $shipments = Shipment::query()
222
+ ->where('carrier_slug', self::SLUG)
223
+ ->where('order_id', (int) Arr::get($payload, 'reference'))
224
+ ->get();
225
+
226
+ foreach ($shipments as $shipment) {
227
+ $meta = (array) $shipment->meta;
228
+ if ((string) Arr::get($meta, 'transaction_id') !== $labelId) {
229
+ continue;
230
+ }
231
+
232
+ $meta['label_url'] = esc_url_raw((string) Arr::get($payload, 'label_url'), ['https']);
233
+ $shipment->meta = $meta;
234
+ $shipment->tracking_number = sanitize_text_field((string) Arr::get($payload, 'tracking_number'));
235
+ $shipment->tracking_url = $this->getTrackingUrl($shipment->tracking_number);
236
+ $shipment->save();
237
+
238
+ return $this->webhookApplied($shipment, true);
239
+ }
240
+
241
+ return $this->webhookIgnored('unknown_shipment');
242
+ }
243
+ ```
244
+
245
+ Send your carrier the order ID as the reference, so the webhook can find the order. `processWebhook()` then sends this event to the method above:
246
+
247
+ ```
248
+ if (Arr::get($payload, 'event') === 'label.updated') {
249
+ return $this->applyLateLabel($payload);
250
+ }
251
+ ```
252
+
253
+ Until the details arrive:
254
+
255
+ - The refresh action does not appear, because the shipment has no tracking number.
256
+ - `hasLabel()` is true as soon as the shipment has a `transaction_id`. If `getLabelDownloadUrl()` has no link yet, return a `WP_Error` that says the label is not ready. An empty string shows "This shipment has no label to print."
257
+ - If the admin leaves the customer notification on, the shipment email goes out straight away, without the tracking number. The customer's order page shows the number once you save it.
258
+
259
+ ## Voiding a label
260
+
261
+ FluentCart calls this when an admin deletes a shipment, and when a label was bought but the shipment could not be recorded.
262
+
263
+ ```
264
+ public function cancelShipmentFromShipmentInstance(ShipmentInstance $instance)
265
+ {
266
+ $labelId = (string) Arr::get($instance->data, 'transaction_id', '');
267
+ if ($labelId === '') {
268
+ return null;
269
+ }
270
+
271
+ $response = $this->request('DELETE', '/labels/' . rawurlencode($labelId), [], 15);
272
+
273
+ return is_wp_error($response) ? $response : true;
274
+ }
275
+ ```
276
+
277
+ The label ID is always in `$instance->data['transaction_id']`. Return `true` when voided, a `WP_Error` when your carrier refused, and `null` when there was nothing to void. A refusal is shown to the admin and logged on the order.
278
+
279
+ ## Printing a label
280
+
281
+ Label links expire, so FluentCart stores no PDF and asks you for a link each time.
282
+
283
+ ```
284
+ public function hasLabel(Shipment $shipment): bool
285
+ {
286
+ return (string) Arr::get((array) $shipment->meta, 'transaction_id', '') !== '';
287
+ }
288
+
289
+ public function getLabelDownloadUrl(Shipment $shipment)
290
+ {
291
+ $response = $this->request('GET', '/labels/' . rawurlencode((string) Arr::get((array) $shipment->meta, 'transaction_id', '')), [], 8);
292
+ if (is_wp_error($response)) {
293
+ return $response;
294
+ }
295
+
296
+ return esc_url_raw((string) Arr::get($response, 'label_url'), ['https']);
297
+ }
298
+ ```
299
+
300
+ `hasLabel()` runs for every shipment in a list, so it must not call your API. `getLabelDownloadUrl()` must return an `https://` link to a PDF of at most 5 MB, an empty string when there is no label, or a `WP_Error`.
301
+
302
+ ## Tracking
303
+
304
+ `getTrackingUrl()` gives the public link used when your label result has no `tracking_url`, and when an admin types a tracking number.
305
+
306
+ ```
307
+ public function getTrackingUrl(string $trackingNumber): string
308
+ {
309
+ return 'https://track.acme-parcel.example/' . rawurlencode($trackingNumber);
310
+ }
311
+ ```
312
+
313
+ To add the admin's refresh action, implement the two sync methods and report the status through `ShipmentService::applyTrackingUpdate()`:
314
+
315
+ ```
316
+ public function supportsTrackingSync(): bool
317
+ {
318
+ return $this->isEnabled();
319
+ }
320
+
321
+ public function syncTrackingFromShipmentInstance(ShipmentInstance $instance)
322
+ {
323
+ return $instance->shipment ? $this->pullTracking($instance->shipment) : null;
324
+ }
325
+
326
+ /**
327
+ * @return bool|\WP_Error True when a new status was applied.
328
+ */
329
+ protected function pullTracking(Shipment $shipment)
330
+ {
331
+ $track = $this->request('GET', '/tracking/' . rawurlencode((string) $shipment->tracking_number), [], 8);
332
+ if (is_wp_error($track)) {
333
+ return $track;
334
+ }
335
+
336
+ $statuses = [
337
+ 'accepted' => Shipment::STATUS_DISPATCHED,
338
+ 'in_transit' => Shipment::STATUS_IN_TRANSIT,
339
+ 'delivered' => Shipment::STATUS_DELIVERED,
340
+ 'returned' => Shipment::STATUS_RETURNED,
341
+ 'failed' => Shipment::STATUS_FAILED,
342
+ ];
343
+ $status = (string) Arr::get($track, 'status');
344
+ if (!isset($statuses[$status])) {
345
+ return false;
346
+ }
347
+
348
+ $result = ShipmentService::applyTrackingUpdate($shipment, $statuses[$status], [
349
+ 'tracking_status' => $status,
350
+ 'tracking_status_date' => sanitize_text_field((string) Arr::get($track, 'updated_at')),
351
+ 'tracking_status_details' => sanitize_text_field((string) Arr::get($track, 'details')),
352
+ ]);
353
+
354
+ return is_wp_error($result) ? $result : (bool) $result;
355
+ }
356
+ ```
357
+
358
+ `applyTrackingUpdate()` is safe to call with old or repeated events:
359
+
360
+ - An event no newer than the stored one is ignored. It compares `tracking_status_date` when both events have one, and otherwise the shipment's stage.
361
+ - `delivered` and `returned` are final. Later events can add details but cannot change the status.
362
+ - It returns `true` only when the status changed.
363
+
364
+ | Shipment status | Constant |
365
+ | --- | --- |
366
+ | `dispatched` | `Shipment::STATUS_DISPATCHED` |
367
+ | `in_transit` | `Shipment::STATUS_IN_TRANSIT` |
368
+ | `delivered` | `Shipment::STATUS_DELIVERED` |
369
+ | `returned` | `Shipment::STATUS_RETURNED` |
370
+ | `failed` | `Shipment::STATUS_FAILED` |
371
+
372
+ When the last shipment is delivered, FluentCart moves the order's shipping status to `delivered`. A change fires `fluent_cart/shipment_tracking_updated`, then `fluent_cart/order_shipment_status_changed_to_{status}` and `fluent_cart/order_shipment_status_changed`.
373
+
374
+ The refresh action appears for a shipment with a tracking number and a status that can still change, when it has a `transaction_id`. To track shipments without one, implement `canTrackWithoutLabel()` and return `true`.
375
+
376
+ ## Webhooks
377
+
378
+ FluentCart gives every carrier a public endpoint:
379
+
380
+ ```
381
+ https://your-site.com/?fluent-cart=fct_shipping_listener_webhook&carrier={slug}
382
+ ```
383
+
384
+ It finds your carrier by `carrier` and calls `handleWebhook()`. An unknown slug gets a 404, and an exception from your code gets a 500 so your carrier retries. **You authenticate the request and send the response.**
385
+
386
+ Create the secret when settings are saved. It is not a declared field, so it is never returned by the settings API.
387
+
388
+ ```
389
+ public function validateSettings(array $settings)
390
+ {
391
+ if (!$this->settings->get('webhook_secret')) {
392
+ $settings['webhook_secret'] = wp_generate_password(32, false);
393
+ }
394
+
395
+ return $settings;
396
+ }
397
+
398
+ public function getWebhookUrl(): string
399
+ {
400
+ $secret = (string) $this->settings->get('webhook_secret');
401
+ if ($secret === '') {
402
+ return '';
403
+ }
404
+
405
+ return add_query_arg([
406
+ 'fluent-cart' => 'fct_shipping_listener_webhook',
407
+ 'carrier' => self::SLUG,
408
+ 'token' => $secret,
409
+ ], home_url('/'));
410
+ }
411
+
412
+ public function handleWebhook(): void
413
+ {
414
+ $token = (string) App::request()->getSafe('token', 'sanitize_text_field');
415
+ $payload = json_decode((string) file_get_contents('php://input'), true);
416
+
417
+ list($status, $body) = $this->processWebhook($token, is_array($payload) ? $payload : []);
418
+
419
+ wp_send_json($body, $status);
420
+ }
421
+
422
+ public function processWebhook(string $token, array $payload): array
423
+ {
424
+ $secret = (string) $this->settings->get('webhook_secret');
425
+ if ($secret === '' || !hash_equals($secret, $token)) {
426
+ return $this->webhookRejected(401, 'invalid_token');
427
+ }
428
+
429
+ if (Arr::get($payload, 'event') !== 'tracking.updated') {
430
+ return $this->webhookIgnored('event');
431
+ }
432
+
433
+ $shipment = Shipment::query()
434
+ ->where('carrier_slug', self::SLUG)
435
+ ->where('tracking_number', sanitize_text_field((string) Arr::get($payload, 'tracking_number')))
436
+ ->first();
437
+
438
+ if (!$shipment) {
439
+ return $this->webhookIgnored('unknown_shipment');
440
+ }
441
+
442
+ $applied = $this->pullTracking($shipment);
443
+ if (is_wp_error($applied)) {
444
+ return $this->webhookFailed(502, 'refetch_failed', $applied->get_error_message(), $shipment);
445
+ }
446
+
447
+ return $this->webhookApplied($shipment, $applied);
448
+ }
449
+ ```
450
+
451
+ Treat the webhook body as a notice only. Use it to find the shipment, then read the status from your API, so a forged or replayed event cannot change anything.
452
+
453
+ `getWebhookUrl()` returns the URL the merchant copies. FluentCart shows it on the settings page with `meta()['webhook_hint']` as the instructions. Return an empty string if your carrier takes no webhooks.
454
+
455
+ ### Outcomes
456
+
457
+ The `WebhookOutcomes` trait gives every response the same shape. FluentCart reads the response to write a log entry, which never includes the token or body.
458
+
459
+ | Method | HTTP | `outcome` | Use it when |
460
+ | --- | --- | --- | --- |
461
+ | `webhookApplied($shipment, true)` | 200 | `applied` | The status changed. |
462
+ | `webhookApplied($shipment, false)` | 200 | `unchanged` | Nothing changed. |
463
+ | `webhookIgnored($reason, $shipment, $details)` | 200 | `ignored` | You will never use this event, so your carrier should not retry it. |
464
+ | `webhookRejected($status, $reason, $message)` | your status | `rejected` | Authentication failed. |
465
+ | `webhookFailed($status, $reason, $message, $shipment)` | your status | `error` | Your read failed. Use a 5xx so your carrier retries. |
466
+
467
+ Repeated outcomes are logged at most once an hour. Turn off these log entries with `fluent_cart/shipping/log_carrier_webhooks`.
468
+
469
+ ## Changing a shipment before dispatch
470
+
471
+ Other plugins can adjust the instance before your carrier is called, or skip the carrier and record the shipment by hand:
472
+
473
+ ```
474
+ add_filter('fluent_cart/before_carrier_dispatch', function ($instance, $context) {
475
+ if ($context['carrier_slug'] === 'acme' && $instance->order->total_amount > 100000) {
476
+ return null; // Not a ShipmentInstance: the carrier is skipped.
477
+ }
478
+
479
+ return $instance;
480
+ }, 10, 2);
481
+ ```