fluentcart-developer 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (609) hide show
  1. package/LICENSE.md +26 -26
  2. package/README.md +59 -59
  3. package/dist/cards/fluentcart/templates-native.js +1087 -1087
  4. package/dist/cards/fluentcart/tools.js +2309 -2309
  5. package/dist/skills/fluentcart-developer/SKILL.md +108 -108
  6. package/dist/skills/fluentcart-developer/examples/README.md +30 -30
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +113 -113
  10. package/dist/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +148 -148
  11. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  12. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/README.md +22 -22
  13. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/sample-plugin-with-licensing-sdk.php +79 -79
  14. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/FluentLicensing.php +303 -303
  15. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/LicenseSettings.php +566 -566
  16. package/dist/skills/fluentcart-developer/examples/sample-plugin-with-licensing-sdk/updater/PluginUpdater.php +304 -304
  17. package/dist/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +61 -61
  18. package/dist/skills/fluentcart-developer/references/api/authentication.md +452 -452
  19. package/dist/skills/fluentcart-developer/references/api/coupons.md +786 -786
  20. package/dist/skills/fluentcart-developer/references/api/customers.md +889 -889
  21. package/dist/skills/fluentcart-developer/references/api/files.md +609 -609
  22. package/dist/skills/fluentcart-developer/references/api/index.md +432 -432
  23. package/dist/skills/fluentcart-developer/references/api/licensing.md +633 -633
  24. package/dist/skills/fluentcart-developer/references/api/order-bump.md +384 -384
  25. package/dist/skills/fluentcart-developer/references/api/orders.md +814 -814
  26. package/dist/skills/fluentcart-developer/references/api/products.md +866 -866
  27. package/dist/skills/fluentcart-developer/references/api/roles-permissions.md +536 -536
  28. package/dist/skills/fluentcart-developer/references/api/subscriptions.md +827 -827
  29. package/dist/skills/fluentcart-developer/references/database/index.md +44 -44
  30. package/dist/skills/fluentcart-developer/references/database/models/activity.md +178 -178
  31. package/dist/skills/fluentcart-developer/references/database/models/applied-coupon.md +291 -291
  32. package/dist/skills/fluentcart-developer/references/database/models/attribute-group.md +239 -239
  33. package/dist/skills/fluentcart-developer/references/database/models/attribute-relation.md +181 -181
  34. package/dist/skills/fluentcart-developer/references/database/models/attribute-term.md +219 -219
  35. package/dist/skills/fluentcart-developer/references/database/models/cart.md +645 -645
  36. package/dist/skills/fluentcart-developer/references/database/models/coupon.md +427 -427
  37. package/dist/skills/fluentcart-developer/references/database/models/customer-addresses.md +348 -348
  38. package/dist/skills/fluentcart-developer/references/database/models/customer-meta.md +156 -156
  39. package/dist/skills/fluentcart-developer/references/database/models/customer.md +584 -584
  40. package/dist/skills/fluentcart-developer/references/database/models/dynamic-model.md +163 -163
  41. package/dist/skills/fluentcart-developer/references/database/models/label-relationship.md +155 -155
  42. package/dist/skills/fluentcart-developer/references/database/models/label.md +153 -153
  43. package/dist/skills/fluentcart-developer/references/database/models/license-activation.md +182 -182
  44. package/dist/skills/fluentcart-developer/references/database/models/license-meta.md +163 -163
  45. package/dist/skills/fluentcart-developer/references/database/models/license-site.md +208 -208
  46. package/dist/skills/fluentcart-developer/references/database/models/license.md +640 -640
  47. package/dist/skills/fluentcart-developer/references/database/models/meta.md +233 -233
  48. package/dist/skills/fluentcart-developer/references/database/models/order-address.md +391 -391
  49. package/dist/skills/fluentcart-developer/references/database/models/order-download-permission.md +144 -144
  50. package/dist/skills/fluentcart-developer/references/database/models/order-item.md +383 -383
  51. package/dist/skills/fluentcart-developer/references/database/models/order-meta.md +303 -303
  52. package/dist/skills/fluentcart-developer/references/database/models/order-operation.md +158 -158
  53. package/dist/skills/fluentcart-developer/references/database/models/order-promotion-stat.md +175 -175
  54. package/dist/skills/fluentcart-developer/references/database/models/order-promotion.md +250 -250
  55. package/dist/skills/fluentcart-developer/references/database/models/order-tax-rate.md +172 -172
  56. package/dist/skills/fluentcart-developer/references/database/models/order-transaction.md +440 -440
  57. package/dist/skills/fluentcart-developer/references/database/models/order.md +727 -727
  58. package/dist/skills/fluentcart-developer/references/database/models/product-detail.md +397 -397
  59. package/dist/skills/fluentcart-developer/references/database/models/product-download.md +258 -258
  60. package/dist/skills/fluentcart-developer/references/database/models/product-meta.md +153 -153
  61. package/dist/skills/fluentcart-developer/references/database/models/product-variation.md +556 -556
  62. package/dist/skills/fluentcart-developer/references/database/models/product.md +580 -580
  63. package/dist/skills/fluentcart-developer/references/database/models/relationships.md +427 -427
  64. package/dist/skills/fluentcart-developer/references/database/models/scheduled-action.md +175 -175
  65. package/dist/skills/fluentcart-developer/references/database/models/shipping-class.md +148 -148
  66. package/dist/skills/fluentcart-developer/references/database/models/shipping-method.md +280 -280
  67. package/dist/skills/fluentcart-developer/references/database/models/shipping-zone.md +205 -205
  68. package/dist/skills/fluentcart-developer/references/database/models/subscription-meta.md +173 -173
  69. package/dist/skills/fluentcart-developer/references/database/models/subscription.md +528 -528
  70. package/dist/skills/fluentcart-developer/references/database/models/tax-class.md +195 -195
  71. package/dist/skills/fluentcart-developer/references/database/models/tax-rate.md +225 -225
  72. package/dist/skills/fluentcart-developer/references/database/models/user-meta.md +166 -166
  73. package/dist/skills/fluentcart-developer/references/database/models/user.md +220 -220
  74. package/dist/skills/fluentcart-developer/references/database/models.md +404 -404
  75. package/dist/skills/fluentcart-developer/references/database/query-builder.md +860 -860
  76. package/dist/skills/fluentcart-developer/references/database/readme.md +276 -276
  77. package/dist/skills/fluentcart-developer/references/database/schema.md +1002 -1002
  78. package/dist/skills/fluentcart-developer/references/engineering/adding-custom-pages-to-the-customer-dashboard.md +395 -395
  79. package/dist/skills/fluentcart-developer/references/engineering/index.md +4 -4
  80. package/dist/skills/fluentcart-developer/references/engineering.md +4 -4
  81. package/dist/skills/fluentcart-developer/references/getting-started.md +249 -249
  82. package/dist/skills/fluentcart-developer/references/guides/frontend.md +519 -519
  83. package/dist/skills/fluentcart-developer/references/guides/index.md +107 -107
  84. package/dist/skills/fluentcart-developer/references/guides/integrations.md +600 -600
  85. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/index.md +237 -237
  86. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/labels-and-tracking.md +481 -481
  87. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/live-rates.md +269 -269
  88. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/reference.md +223 -223
  89. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier/settings.md +370 -370
  90. package/dist/skills/fluentcart-developer/references/guides/shipping-carrier.md +237 -237
  91. package/dist/skills/fluentcart-developer/references/guides/subscriptions.md +217 -217
  92. package/dist/skills/fluentcart-developer/references/hooks/actions/admin-and-templates.md +1079 -1079
  93. package/dist/skills/fluentcart-developer/references/hooks/actions/cart-and-checkout.md +1795 -1795
  94. package/dist/skills/fluentcart-developer/references/hooks/actions/customers-and-users.md +327 -327
  95. package/dist/skills/fluentcart-developer/references/hooks/actions/licenses.md +829 -829
  96. package/dist/skills/fluentcart-developer/references/hooks/actions/modules.md +81 -81
  97. package/dist/skills/fluentcart-developer/references/hooks/actions/orders.md +757 -757
  98. package/dist/skills/fluentcart-developer/references/hooks/actions/payments-and-integrations.md +1163 -1163
  99. package/dist/skills/fluentcart-developer/references/hooks/actions/pro-modules.md +219 -219
  100. package/dist/skills/fluentcart-developer/references/hooks/actions/products-and-coupons.md +1019 -1019
  101. package/dist/skills/fluentcart-developer/references/hooks/actions/subscriptions.md +1290 -1290
  102. package/dist/skills/fluentcart-developer/references/hooks/actions.md +16 -16
  103. package/dist/skills/fluentcart-developer/references/hooks/deprecated.md +60 -60
  104. package/dist/skills/fluentcart-developer/references/hooks/filters/cart-and-checkout.md +2032 -2032
  105. package/dist/skills/fluentcart-developer/references/hooks/filters/customers-and-subscriptions.md +1746 -1746
  106. package/dist/skills/fluentcart-developer/references/hooks/filters/integrations-and-advanced.md +2439 -2439
  107. package/dist/skills/fluentcart-developer/references/hooks/filters/modules.md +464 -464
  108. package/dist/skills/fluentcart-developer/references/hooks/filters/orders-and-payments.md +2658 -2658
  109. package/dist/skills/fluentcart-developer/references/hooks/filters/pro-modules.md +502 -502
  110. package/dist/skills/fluentcart-developer/references/hooks/filters/products-and-pricing.md +1785 -1785
  111. package/dist/skills/fluentcart-developer/references/hooks/filters/settings-and-configuration.md +2966 -2966
  112. package/dist/skills/fluentcart-developer/references/hooks/filters.md +14 -14
  113. package/dist/skills/fluentcart-developer/references/hooks/index.md +35 -35
  114. package/dist/skills/fluentcart-developer/references/index.md +625 -625
  115. package/dist/skills/fluentcart-developer/references/modules/fee-system.md +427 -427
  116. package/dist/skills/fluentcart-developer/references/modules/ghost-product-selling.md +440 -440
  117. package/dist/skills/fluentcart-developer/references/modules/index.md +484 -484
  118. package/dist/skills/fluentcart-developer/references/modules/licensing.md +342 -342
  119. package/dist/skills/fluentcart-developer/references/modules/order-bump.md +433 -433
  120. package/dist/skills/fluentcart-developer/references/modules/payment-methods.md +129 -129
  121. package/dist/skills/fluentcart-developer/references/modules/refunds.md +170 -170
  122. package/dist/skills/fluentcart-developer/references/modules/shipping.md +846 -846
  123. package/dist/skills/fluentcart-developer/references/modules/storage.md +986 -986
  124. package/dist/skills/fluentcart-developer/references/modules/subscription-vendor-ids.md +186 -186
  125. package/dist/skills/fluentcart-developer/references/modules/subscriptions.md +678 -678
  126. package/dist/skills/fluentcart-developer/references/payment-methods-integration/index.md +164 -164
  127. package/dist/skills/fluentcart-developer/references/payment-methods-integration/paddle-example.md +1648 -1648
  128. package/dist/skills/fluentcart-developer/references/payment-methods-integration/payment/setting/fields.md +353 -353
  129. package/dist/skills/fluentcart-developer/references/payment-methods-integration/quick-implementation.md +1079 -1079
  130. package/dist/skills/fluentcart-developer/references/payment-methods-integration.md +164 -164
  131. package/dist/skills/fluentcart-developer/references/restapi/checkout.md +573 -573
  132. package/dist/skills/fluentcart-developer/references/restapi/coupons.md +958 -958
  133. package/dist/skills/fluentcart-developer/references/restapi/customer-profile.md +1423 -1423
  134. package/dist/skills/fluentcart-developer/references/restapi/customers.md +1103 -1103
  135. package/dist/skills/fluentcart-developer/references/restapi/dashboard.md +1083 -1083
  136. package/dist/skills/fluentcart-developer/references/restapi/data-export.md +132 -132
  137. package/dist/skills/fluentcart-developer/references/restapi/email-notifications.md +846 -846
  138. package/dist/skills/fluentcart-developer/references/restapi/files.md +313 -313
  139. package/dist/skills/fluentcart-developer/references/restapi/index.md +127 -127
  140. package/dist/skills/fluentcart-developer/references/restapi/integrations.md +1000 -1000
  141. package/dist/skills/fluentcart-developer/references/restapi/inventory.md +192 -192
  142. package/dist/skills/fluentcart-developer/references/restapi/labels-and-attributes.md +797 -797
  143. package/dist/skills/fluentcart-developer/references/restapi/licensing.md +1733 -1733
  144. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-available-shipping-methods.md +30 -30
  145. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-checkout-summary.md +28 -28
  146. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-country-info.md +29 -29
  147. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-order-info.md +28 -28
  148. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/get-shipping-methods-list-view.md +30 -30
  149. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/login.md +66 -66
  150. package/dist/skills/fluentcart-developer/references/restapi/operations/checkout/place-order.md +179 -179
  151. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/apply-coupon.md +83 -83
  152. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/cancel-coupon.md +87 -87
  153. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/check-product-eligibility.md +59 -59
  154. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/create-coupon.md +230 -230
  155. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/delete-coupon.md +29 -29
  156. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon-settings.md +20 -20
  157. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/get-coupon.md +27 -27
  158. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupon-codes.md +20 -20
  159. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/list-coupons.md +37 -37
  160. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/re-apply-coupons.md +75 -75
  161. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/store-coupon-settings.md +40 -40
  162. package/dist/skills/fluentcart-developer/references/restapi/operations/coupons/update-coupon.md +133 -133
  163. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-address-checkout.md +138 -138
  164. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/create-profile-address.md +119 -119
  165. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/dashboard-overview.md +22 -22
  166. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/delete-profile-address.md +46 -46
  167. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-order-details.md +30 -30
  168. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-portal-sections.md +29 -29
  169. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-profile-details.md +22 -22
  170. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-transaction-billing-address.md +30 -30
  171. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/get-upgrade-paths.md +31 -31
  172. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-downloads.md +29 -29
  173. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/list-orders.md +28 -28
  174. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/make-profile-address-primary.md +55 -55
  175. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/pause-subscription.md +29 -29
  176. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/resume-subscription.md +29 -29
  177. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/save-transaction-billing-address.md +92 -92
  178. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/select-address-for-checkout.md +32 -32
  179. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-address.md +115 -115
  180. package/dist/skills/fluentcart-developer/references/restapi/operations/customer-profile/update-profile-details.md +69 -69
  181. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/attach-user.md +50 -50
  182. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/bulk-actions.md +65 -65
  183. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-address.md +135 -135
  184. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/create-customer.md +108 -108
  185. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/delete-address.md +62 -62
  186. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/detach-user.md +28 -28
  187. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/find-customer-order.md +27 -27
  188. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-attachable-users.md +20 -20
  189. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-addresses.md +28 -28
  190. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-orders.md +37 -37
  191. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer-stats.md +27 -27
  192. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/get-customer.md +32 -32
  193. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/list-customers.md +37 -37
  194. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/recalculate-ltv.md +28 -28
  195. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/set-primary-address.md +72 -72
  196. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-additional-info.md +55 -55
  197. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-address.md +144 -144
  198. package/dist/skills/fluentcart-developer/references/restapi/operations/customers/update-customer.md +123 -123
  199. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/attach-note-to-order.md +49 -49
  200. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-all-pages.md +21 -21
  201. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/create-single-page.md +55 -55
  202. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/delete-activity.md +28 -28
  203. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-country-info.md +29 -29
  204. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-dashboard-stats.md +22 -22
  205. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-filter-options.md +31 -31
  206. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-data.md +20 -20
  207. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-onboarding-settings.md +20 -20
  208. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-print-templates.md +20 -20
  209. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-search-options.md +27 -27
  210. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/get-widgets.md +28 -28
  211. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/initialize-app.md +20 -20
  212. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-activities.md +33 -33
  213. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-attachments.md +21 -21
  214. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/list-countries.md +20 -20
  215. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/mark-activity-read.md +53 -53
  216. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/run-data-backfills.md +21 -21
  217. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-settings.md +54 -54
  218. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-onboarding-tax-settings.md +73 -73
  219. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/save-print-templates.md +64 -64
  220. package/dist/skills/fluentcart-developer/references/restapi/operations/dashboard/upload-attachment.md +42 -42
  221. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-customers-batch.md +129 -129
  222. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-licenses-batch.md +133 -133
  223. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-orders-batch.md +129 -129
  224. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/export-subscriptions-batch.md +129 -129
  225. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-customers-export-schema.md +21 -21
  226. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-licenses-export-schema.md +26 -26
  227. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-orders-export-schema.md +21 -21
  228. package/dist/skills/fluentcart-developer/references/restapi/operations/data-export/get-subscriptions-export-schema.md +21 -21
  229. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/enable-notification.md +57 -57
  230. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-digest-settings.md +22 -22
  231. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-notification.md +30 -30
  232. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-reminders.md +22 -22
  233. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-settings.md +22 -22
  234. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/get-shortcodes.md +22 -22
  235. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/list-notifications.md +20 -20
  236. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-default-template.md +66 -66
  237. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/preview-notification.md +50 -50
  238. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-digest-settings.md +101 -101
  239. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-reminders.md +162 -162
  240. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/save-settings.md +99 -99
  241. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-digest-test.md +47 -47
  242. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/send-manual-reminder.md +51 -51
  243. package/dist/skills/fluentcart-developer/references/restapi/operations/email-notification/update-notification.md +93 -93
  244. package/dist/skills/fluentcart-developer/references/restapi/operations/files/delete-file.md +31 -31
  245. package/dist/skills/fluentcart-developer/references/restapi/operations/files/get-bucket-list.md +28 -28
  246. package/dist/skills/fluentcart-developer/references/restapi/operations/files/list-files.md +30 -30
  247. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-editor-file.md +32 -32
  248. package/dist/skills/fluentcart-developer/references/restapi/operations/files/upload-file.md +34 -34
  249. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/chained-data-request.md +46 -46
  250. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/change-feed-status.md +51 -51
  251. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/delete-feed.md +27 -27
  252. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-dynamic-options.md +29 -29
  253. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-lists.md +27 -27
  254. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-feed-settings.md +27 -27
  255. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-feeds.md +20 -20
  256. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/get-global-settings.md +26 -26
  257. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/install-addon-plugin.md +49 -49
  258. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/list-addons.md +20 -20
  259. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/save-feed-settings.md +52 -52
  260. package/dist/skills/fluentcart-developer/references/restapi/operations/integration/set-global-settings.md +50 -50
  261. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/bulk-update-stock.md +94 -94
  262. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/export-inventory.md +81 -81
  263. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-adjustment-history.md +26 -26
  264. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/get-inventory-stats.md +21 -21
  265. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/list-inventory.md +33 -33
  266. package/dist/skills/fluentcart-developer/references/restapi/operations/inventory/update-stock.md +75 -75
  267. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-attribute-group.md +31 -31
  268. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-label.md +31 -31
  269. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/create-terms.md +90 -90
  270. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-group.md +28 -28
  271. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/delete-attribute-term.md +29 -29
  272. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-group.md +28 -28
  273. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/get-attribute-library.md +20 -20
  274. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-groups.md +32 -32
  275. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-attribute-terms.md +33 -33
  276. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/list-labels.md +20 -20
  277. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-groups.md +51 -51
  278. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/reorder-terms.md +56 -56
  279. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-group.md +37 -37
  280. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-attribute-term.md +39 -39
  281. package/dist/skills/fluentcart-developer/references/restapi/operations/labels-attributes/update-label-selections.md +32 -32
  282. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-plugin-license.md +41 -41
  283. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/activate-site-admin.md +60 -60
  284. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-plugin-license.md +18 -18
  285. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-admin.md +67 -67
  286. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/deactivate-site-customer.md +47 -47
  287. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/delete-license.md +24 -24
  288. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/extend-license-validity.md +47 -47
  289. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-license-details.md +25 -25
  290. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-customer-licenses-admin.md +26 -26
  291. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-activations.md +25 -25
  292. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-details.md +25 -25
  293. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-license-site.md +30 -30
  294. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-plugin-license-status.md +18 -18
  295. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/get-product-license-settings.md +24 -24
  296. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-customer-licenses.md +25 -25
  297. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-license-sites.md +33 -33
  298. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/list-licenses.md +38 -38
  299. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-activate-license.md +54 -54
  300. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-check-license.md +26 -26
  301. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-deactivate-license.md +46 -46
  302. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-download-license-package.md +23 -23
  303. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/public-get-license-version.md +26 -26
  304. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/regenerate-license-key.md +24 -24
  305. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/save-product-license-settings.md +193 -193
  306. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-activation-limit.md +53 -53
  307. package/dist/skills/fluentcart-developer/references/restapi/operations/licensing/update-license-status.md +52 -52
  308. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/create-order-bump.md +47 -47
  309. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/delete-order-bump.md +25 -25
  310. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/get-order-bump.md +25 -25
  311. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/list-order-bumps.md +29 -29
  312. package/dist/skills/fluentcart-developer/references/restapi/operations/order-bumps/update-order-bump.md +141 -141
  313. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/accept-dispute.md +47 -47
  314. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/bulk-actions.md +72 -72
  315. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-shipping.md +67 -67
  316. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/calculate-tax.md +98 -98
  317. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/change-customer.md +50 -50
  318. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/charge-now.md +29 -29
  319. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-and-change-customer.md +92 -92
  320. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-custom-order-item.md +68 -68
  321. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-order.md +351 -351
  322. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/create-renewal-now.md +29 -29
  323. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/delete-order.md +28 -28
  324. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/generate-missing-licenses.md +29 -29
  325. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order-transactions.md +27 -27
  326. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-order.md +27 -27
  327. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-renewal.md +28 -28
  328. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-shipping-methods.md +28 -28
  329. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/get-single-transaction.md +28 -28
  330. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-order-currencies.md +22 -22
  331. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-orders.md +42 -42
  332. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/list-renewals.md +28 -28
  333. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/mark-as-paid.md +61 -61
  334. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/price-order.md +135 -135
  335. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/refund-order.md +72 -72
  336. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/resend-renewal-invoice.md +29 -29
  337. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/skip-renewal.md +48 -48
  338. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-order-statuses.md +28 -28
  339. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/sync-pending-transaction.md +29 -29
  340. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address-id.md +60 -60
  341. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order-address.md +98 -98
  342. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-order.md +172 -172
  343. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-statuses.md +77 -77
  344. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-subscription-details.md +84 -84
  345. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/update-transaction-status.md +51 -51
  346. package/dist/skills/fluentcart-developer/references/restapi/operations/orders/void-renewal.md +30 -30
  347. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/create-pdf-template.md +42 -42
  348. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/delete-pdf-template.md +26 -26
  349. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/download-pdf-preview.md +44 -44
  350. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-factory-default-templates.md +19 -19
  351. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-status.md +21 -21
  352. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-pdf-template.md +26 -26
  353. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-saved-templates.md +21 -21
  354. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/get-seller-details.md +19 -19
  355. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/list-pdf-templates.md +19 -19
  356. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-pdf-template.md +53 -53
  357. package/dist/skills/fluentcart-developer/references/restapi/operations/pdf-templates/save-seller-details.md +97 -97
  358. package/dist/skills/fluentcart-developer/references/restapi/operations/products/add-product-terms.md +64 -64
  359. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-edit-fetch.md +30 -30
  360. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-insert-products.md +62 -62
  361. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-products.md +59 -59
  362. package/dist/skills/fluentcart-developer/references/restapi/operations/products/bulk-update-variants.md +83 -83
  363. package/dist/skills/fluentcart-developer/references/restapi/operations/products/change-integration-status.md +64 -64
  364. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-dummy-products.md +45 -45
  365. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-product.md +81 -81
  366. package/dist/skills/fluentcart-developer/references/restapi/operations/products/create-variation.md +181 -181
  367. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-downloadable-file.md +27 -27
  368. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product-integration.md +30 -30
  369. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-product.md +27 -27
  370. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-taxonomy-term.md +55 -55
  371. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-upgrade-path.md +27 -27
  372. package/dist/skills/fluentcart-developer/references/restapi/operations/products/delete-variation.md +27 -27
  373. package/dist/skills/fluentcart-developer/references/restapi/operations/products/do-bulk-action.md +56 -56
  374. package/dist/skills/fluentcart-developer/references/restapi/operations/products/duplicate-product.md +56 -56
  375. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-products-by-ids.md +26 -26
  376. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-taxonomy-terms.md +20 -20
  377. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-terms-by-parent.md +60 -60
  378. package/dist/skills/fluentcart-developer/references/restapi/operations/products/fetch-variations-by-ids.md +26 -26
  379. package/dist/skills/fluentcart-developer/references/restapi/operations/products/find-subscription-variants.md +26 -26
  380. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-bundle-info.md +27 -27
  381. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-downloadable-url.md +27 -27
  382. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-max-excerpt-word-count.md +20 -20
  383. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-pricing-widgets.md +27 -27
  384. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-feeds.md +29 -29
  385. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-integration-settings.md +31 -31
  386. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product-pricing.md +28 -28
  387. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-product.md +28 -28
  388. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-related-products.md +31 -31
  389. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-upgrade-settings.md +27 -27
  390. package/dist/skills/fluentcart-developer/references/restapi/operations/products/get-variation-upgrade-paths.md +28 -28
  391. package/dist/skills/fluentcart-developer/references/restapi/operations/products/group-bulk-update-variants.md +103 -103
  392. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-all-variants.md +26 -26
  393. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-product-variations.md +26 -26
  394. package/dist/skills/fluentcart-developer/references/restapi/operations/products/list-products.md +34 -34
  395. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-shipping-class.md +27 -27
  396. package/dist/skills/fluentcart-developer/references/restapi/operations/products/remove-tax-class.md +27 -27
  397. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-bundle-info.md +56 -56
  398. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-product-integration.md +62 -62
  399. package/dist/skills/fluentcart-developer/references/restapi/operations/products/save-upgrade-path.md +78 -78
  400. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-product-variant-options.md +29 -29
  401. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-products-by-name.md +28 -28
  402. package/dist/skills/fluentcart-developer/references/restapi/operations/products/search-variants-by-name.md +28 -28
  403. package/dist/skills/fluentcart-developer/references/restapi/operations/products/set-variation-media.md +74 -74
  404. package/dist/skills/fluentcart-developer/references/restapi/operations/products/suggest-sku.md +28 -28
  405. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-downloadable-files.md +134 -134
  406. package/dist/skills/fluentcart-developer/references/restapi/operations/products/sync-taxonomy-terms.md +61 -61
  407. package/dist/skills/fluentcart-developer/references/restapi/operations/products/toggle-product-tax-exemption.md +56 -56
  408. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-downloadable-file.md +98 -98
  409. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-inventory.md +56 -56
  410. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-long-desc-editor-mode.md +49 -49
  411. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-manage-stock.md +53 -53
  412. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-detail.md +58 -58
  413. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-product-pricing.md +225 -225
  414. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-shipping-class.md +49 -49
  415. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-tax-class.md +49 -49
  416. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-upgrade-path.md +78 -78
  417. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-option.md +79 -79
  418. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variant-tax-exemption.md +56 -56
  419. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation-pricing-table.md +49 -49
  420. package/dist/skills/fluentcart-developer/references/restapi/operations/products/update-variation.md +105 -105
  421. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/get-product-views.md +34 -34
  422. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/list-products.md +42 -42
  423. package/dist/skills/fluentcart-developer/references/restapi/operations/public-shop/search-products.md +30 -30
  424. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/channel-rules.md +24 -24
  425. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/country-heat-map.md +22 -22
  426. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupon-overview.md +37 -37
  427. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/coupons.md +36 -36
  428. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-insights.md +31 -31
  429. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-overview.md +36 -36
  430. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-repeat.md +35 -35
  431. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segment-customers.md +36 -36
  432. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-segments.md +30 -30
  433. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/customer-value.md +34 -34
  434. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/dashboard-stats.md +30 -30
  435. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/failed-orders.md +34 -34
  436. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-new-vs-returning-customer.md +34 -34
  437. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-by-day-and-hour.md +34 -34
  438. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-report-meta.md +29 -29
  439. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/fetch-top-sold-products.md +34 -34
  440. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/future-renewals.md +31 -31
  441. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/generate-retention-snapshots.md +24 -24
  442. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-overview.md +30 -30
  443. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-activities.md +26 -26
  444. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-recent-orders.md +20 -20
  445. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/get-revenue.md +37 -37
  446. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-at-risk.md +35 -35
  447. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments-variations.md +33 -33
  448. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/installments.md +33 -33
  449. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/item-count-distribution.md +34 -34
  450. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-chart.md +30 -30
  451. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-pie-chart.md +22 -22
  452. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/license-summary.md +22 -22
  453. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/locations.md +43 -43
  454. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-chart.md +37 -37
  455. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-completion-time.md +34 -34
  456. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-mix.md +34 -34
  457. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/order-value-distribution.md +34 -34
  458. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-disputes.md +38 -38
  459. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods-methods.md +36 -36
  460. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/payment-methods.md +37 -37
  461. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison-launch.md +33 -33
  462. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-comparison.md +40 -40
  463. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-detail.md +37 -37
  464. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/product-sales.md +37 -37
  465. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/refunds-overview.md +37 -37
  466. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/retention-snapshots-step.md +45 -45
  467. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sales-growth-chart.md +35 -35
  468. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/save-channel-rules.md +73 -73
  469. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/source-channels.md +37 -37
  470. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/sources.md +49 -49
  471. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-cohorts.md +33 -33
  472. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-health.md +30 -30
  473. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-rebuys.md +37 -37
  474. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-retention.md +34 -34
  475. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscription-variations.md +22 -22
  476. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/subscriptions-overview.md +37 -37
  477. package/dist/skills/fluentcart-developer/references/restapi/operations/reports/weeks-between-refund.md +34 -34
  478. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/assign-role.md +48 -48
  479. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/delete-role-assignment.md +47 -47
  480. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/get-role.md +25 -25
  481. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-managers.md +18 -18
  482. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/list-roles.md +18 -18
  483. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/search-users.md +25 -25
  484. package/dist/skills/fluentcart-developer/references/restapi/operations/roles-permissions/update-role.md +43 -43
  485. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/create-saved-view.md +106 -106
  486. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/delete-saved-view.md +26 -26
  487. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/list-saved-views.md +25 -25
  488. package/dist/skills/fluentcart-developer/references/restapi/operations/saved-views/update-saved-view.md +83 -83
  489. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-payment-addon.md +44 -44
  490. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/activate-plugin-addon.md +44 -44
  491. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/change-storage-driver-status.md +56 -56
  492. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/check-paypal-webhook.md +26 -26
  493. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/create-storage-bucket.md +63 -63
  494. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/disconnect-payment-method.md +55 -55
  495. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/exchange-paypal-seller-auth-token.md +62 -62
  496. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-active-storage-drivers.md +20 -20
  497. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-checkout-fields.md +22 -22
  498. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-email-shortcodes.md +20 -20
  499. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-config-snippets.md +26 -26
  500. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-mcp-status.md +20 -20
  501. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-module-settings.md +20 -20
  502. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-connection-info.md +26 -26
  503. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-payment-method-settings.md +26 -26
  504. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-permissions.md +22 -22
  505. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-plugin-addons.md +20 -20
  506. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-storage-driver-settings.md +27 -27
  507. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/get-store-settings.md +26 -26
  508. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-mcp-adapter.md +21 -21
  509. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-payment-addon.md +60 -60
  510. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/install-plugin-addon.md +64 -64
  511. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-payment-methods.md +20 -20
  512. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-all-storage-drivers.md +20 -20
  513. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/list-storage-buckets.md +67 -67
  514. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reorder-payment-methods.md +55 -55
  515. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/reset-storage-driver-settings.md +45 -45
  516. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-checkout-fields.md +133 -133
  517. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-confirmation-settings.md +68 -68
  518. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-module-settings.md +68 -68
  519. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-design.md +67 -67
  520. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-payment-method-settings.md +58 -58
  521. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-permissions.md +68 -68
  522. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-storage-driver-settings.md +62 -62
  523. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/save-store-settings.md +239 -239
  524. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/setup-paypal-webhook.md +48 -48
  525. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/toggle-mcp.md +40 -40
  526. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-storage-driver-connection.md +62 -62
  527. package/dist/skills/fluentcart-developer/references/restapi/operations/settings/verify-turnstile-keys.md +55 -55
  528. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-class.md +73 -73
  529. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-method.md +110 -110
  530. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/create-shipping-zone.md +56 -56
  531. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-class.md +29 -29
  532. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-method.md +29 -29
  533. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/delete-shipping-zone.md +29 -29
  534. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class-profile.md +30 -30
  535. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-class.md +29 -29
  536. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-packages.md +22 -22
  537. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-shipping-zone.md +27 -27
  538. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-countries.md +22 -22
  539. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/get-zone-states.md +28 -28
  540. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-classes.md +31 -31
  541. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/list-shipping-zones.md +31 -31
  542. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/save-shipping-packages.md +112 -112
  543. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-class.md +79 -79
  544. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-method.md +113 -113
  545. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-shipping-zone.md +62 -62
  546. package/dist/skills/fluentcart-developer/references/restapi/operations/shipping/update-zone-order.md +52 -52
  547. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-auto-renew.md +30 -30
  548. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/cancel-subscription.md +52 -52
  549. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/confirm-subscription-switch.md +70 -70
  550. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/fetch-subscription-remote.md +28 -28
  551. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/generate-early-payment-link.md +29 -29
  552. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-customer-subscription.md +27 -27
  553. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-or-create-plan.md +69 -69
  554. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-setup-intent-attempts.md +30 -30
  555. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/get-subscription.md +28 -28
  556. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/initiate-early-payment.md +31 -31
  557. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-customer-subscriptions.md +27 -27
  558. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/list-subscriptions.md +39 -39
  559. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/pause-subscription.md +28 -28
  560. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/reactivate-subscription.md +28 -28
  561. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/resume-subscription.md +28 -28
  562. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/switch-payment-method.md +70 -70
  563. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-payment-method.md +69 -69
  564. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/update-vendor-ids.md +56 -56
  565. package/dist/skills/fluentcart-developer/references/restapi/operations/subscriptions/verify-vendor-ids.md +56 -56
  566. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-class.md +51 -51
  567. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/create-tax-rate.md +117 -117
  568. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-product-override.md +27 -27
  569. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-shipping-tax-override.md +27 -27
  570. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-class.md +28 -28
  571. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/delete-tax-rate.md +27 -27
  572. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-id.md +27 -27
  573. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-country-tax-rates.md +28 -28
  574. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-eu-vat-product-overrides.md +20 -20
  575. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-oss-country-rates.md +20 -20
  576. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-preconfigured-tax-rates.md +20 -20
  577. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-product-overrides.md +27 -27
  578. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/get-tax-settings.md +20 -20
  579. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-all-tax-rates.md +20 -20
  580. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-classes.md +20 -20
  581. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/list-tax-records.md +37 -37
  582. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/mark-taxes-as-filed.md +58 -58
  583. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/reset-eu-vat-rates.md +21 -21
  584. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-configured-countries.md +57 -57
  585. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-country-tax-id.md +50 -50
  586. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-eu-vat-cross-border-settings.md +127 -127
  587. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-oss-country-rates.md +100 -100
  588. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-product-override.md +110 -110
  589. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-shipping-tax-override.md +52 -52
  590. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/save-tax-settings.md +166 -166
  591. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-country-status.md +54 -54
  592. package/dist/skills/fluentcart-developer/references/restapi/operations/tax/update-tax-rate.md +116 -116
  593. package/dist/skills/fluentcart-developer/references/restapi/order-bumps.md +433 -433
  594. package/dist/skills/fluentcart-developer/references/restapi/orders.md +1212 -1212
  595. package/dist/skills/fluentcart-developer/references/restapi/pdf-templates.md +212 -212
  596. package/dist/skills/fluentcart-developer/references/restapi/products.md +2485 -2485
  597. package/dist/skills/fluentcart-developer/references/restapi/public-shop.md +191 -191
  598. package/dist/skills/fluentcart-developer/references/restapi/reports.md +3773 -3773
  599. package/dist/skills/fluentcart-developer/references/restapi/roles.md +403 -403
  600. package/dist/skills/fluentcart-developer/references/restapi/saved-views.md +136 -136
  601. package/dist/skills/fluentcart-developer/references/restapi/settings.md +1423 -1423
  602. package/dist/skills/fluentcart-developer/references/restapi/shipping.md +905 -905
  603. package/dist/skills/fluentcart-developer/references/restapi/subscriptions.md +1169 -1169
  604. package/dist/skills/fluentcart-developer/references/restapi/tax.md +1551 -1551
  605. package/dist/skills/fluentcart-developer/references/restapi.md +127 -127
  606. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  607. package/dist/version.d.ts +1 -1
  608. package/dist/version.js +1 -1
  609. package/package.json +66 -65
@@ -1,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
+ ```