fluentcart-developer 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
@@ -0,0 +1,606 @@
1
+ # Subscriptions API
2
+
3
+ Manage recurring subscriptions including listing, cancellation, reactivation, payment method updates, and customer self-service operations.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
6
+
7
+ > All monetary values are in cents (e.g., `$10.00` = `1000`).
8
+
9
+ ---
10
+
11
+ ## Endpoints Overview
12
+
13
+ ### Admin Endpoints
14
+
15
+ | Method | Endpoint | Description |
16
+ |--------|----------|-------------|
17
+ | GET | `/subscriptions` | List Subscriptions |
18
+ | GET | `/subscriptions/{subscriptionOrderId}` | Get Subscription Details |
19
+ | PUT | `/orders/{order}/subscriptions/{subscription}/cancel` | Cancel Subscription |
20
+ | PUT | `/orders/{order}/subscriptions/{subscription}/fetch` | Fetch Subscription from Remote |
21
+ | POST | `/orders/{order}/subscriptions/{subscription}/early-payment-link` | Generate Early Payment Link |
22
+ | PUT | `/orders/{order}/subscriptions/{subscription}/reactivate` | Reactivate Subscription (Reserved) |
23
+ | PUT | `/orders/{order}/subscriptions/{subscription}/pause` | Pause Subscription (Reserved) |
24
+ | PUT | `/orders/{order}/subscriptions/{subscription}/resume` | Resume Subscription (Reserved) |
25
+
26
+ ### Customer Portal Endpoints
27
+
28
+ | Method | Endpoint | Description |
29
+ |--------|----------|-------------|
30
+ | GET | `/customer-profile/subscriptions` | List Customer Subscriptions |
31
+ | GET | `/customer-profile/subscriptions/{subscription_uuid}` | Get Customer Subscription Details |
32
+ | GET | `/customer-profile/subscriptions/{subscription_uuid}/setup-intent-attempts` | Get Setup Intent Attempts |
33
+ | POST | `/customer-profile/subscriptions/{subscription_uuid}/update-payment-method` | Update Payment Method |
34
+ | POST | `/customer-profile/subscriptions/{subscription_uuid}/get-or-create-plan` | Get or Create Plan |
35
+ | POST | `/customer-profile/subscriptions/{subscription_uuid}/switch-payment-method` | Switch Payment Method |
36
+ | POST | `/customer-profile/subscriptions/{subscription_uuid}/confirm-subscription-switch` | Confirm Subscription Switch |
37
+ | POST | `/customer-profile/subscriptions/{subscription_uuid}/cancel-auto-renew` | Cancel Auto-Renew |
38
+ | POST | `/customer-profile/subscriptions/{subscription_uuid}/initiate-early-payment` | Initiate Early Payment |
39
+
40
+ ---
41
+
42
+ ## Admin Endpoints
43
+
44
+ Admin endpoints require an authenticated WordPress user with the appropriate FluentCart capability. Authorization is handled by `OrderPolicy`.
45
+
46
+ ### List Subscriptions
47
+
48
+ `GET /fluent-cart/v2/subscriptions`
49
+
50
+ Retrieve a paginated list of subscriptions with optional filtering, sorting, and search.
51
+
52
+ **Permission:** `subscriptions/view`
53
+
54
+ **Policy:** `OrderPolicy`
55
+
56
+ #### Parameters
57
+
58
+ | Parameter | Type | Location | Required | Description |
59
+ |-----------|------|----------|----------|-------------|
60
+ | `page` | integer | query | No | Page number for pagination |
61
+ | `per_page` | integer | query | No | Number of records per page (default: 10, max: 200) |
62
+ | `search` | string | query | No | Search term (`#123` for ID, `user@example.com` for email, `canceled`, or general text across vendor IDs, payment method, interval) |
63
+ | `sort_by` | string | query | No | Column to sort by (default: `id`) |
64
+ | `sort_type` | string | query | No | Sort direction: `asc` or `desc` (default: `desc`) |
65
+ | `active_view` | string | query | No | Tab filter: `active`, `pending`, `intended`, `paused`, `trialing`, `canceled`, `failing`, `expiring`, `expired` |
66
+ | `filter_type` | string | query | No | Filter mode: `simple` (default) or `advanced` |
67
+ | `advanced_filters` | string (JSON) | query | No | JSON-encoded array of advanced filter groups (requires Pro) |
68
+ | `with` | array/string | query | No | Eager-load relations |
69
+ | `select` | array/string | query | No | Comma-separated list of columns to select |
70
+ | `scopes` | array | query | No | Model scopes to apply |
71
+ | `include_ids` | array/string | query | No | Comma-separated IDs that must always be included |
72
+ | `limit` | integer | query | No | Limit number of records |
73
+ | `offset` | integer | query | No | Offset for records |
74
+ | `user_tz` | string | query | No | User timezone for date filtering (e.g., `America/New_York`) |
75
+
76
+ #### Response
77
+
78
+ ```json
79
+ {
80
+ "data": {
81
+ "current_page": 1,
82
+ "data": [
83
+ {
84
+ "id": 1,
85
+ "uuid": "abc123-def456",
86
+ "status": "active",
87
+ "item_name": "Pro Plan",
88
+ "parent_order_id": 10,
89
+ "customer_id": 5,
90
+ "product_id": 3,
91
+ "variation_id": 7,
92
+ "vendor_subscription_id": "sub_1234567890",
93
+ "vendor_customer_id": "cus_abc123",
94
+ "vendor_plan_id": "price_xyz789",
95
+ "current_payment_method": "stripe",
96
+ "billing_interval": "monthly",
97
+ "recurring_amount": 2999,
98
+ "bill_times": 0,
99
+ "bill_count": 6,
100
+ "next_billing_date": "2025-02-15 00:00:00",
101
+ "created_at": "2025-01-15 10:30:00",
102
+ "updated_at": "2025-01-15 10:35:00"
103
+ }
104
+ ],
105
+ "per_page": 10,
106
+ "total": 50,
107
+ "last_page": 5
108
+ }
109
+ }
110
+ ```
111
+
112
+ #### Example
113
+
114
+ ```bash
115
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/subscriptions?page=1&per_page=10&active_view=active" \
116
+ -u "username:app_password"
117
+ ```
118
+
119
+ ---
120
+
121
+ ### Get Subscription Details
122
+
123
+ `GET /fluent-cart/v2/subscriptions/{subscriptionOrderId}`
124
+
125
+ Retrieve the full details of a single subscription including customer addresses, labels, activities, and related orders.
126
+
127
+ **Permission:** `subscriptions/view`
128
+
129
+ **Policy:** `OrderPolicy`
130
+
131
+ #### Parameters
132
+
133
+ | Parameter | Type | Location | Required | Description |
134
+ |-----------|------|----------|----------|-------------|
135
+ | `subscriptionOrderId` | integer | path | Yes | The subscription ID |
136
+
137
+ #### Response
138
+
139
+ ```json
140
+ {
141
+ "subscription": {
142
+ "id": 1,
143
+ "uuid": "abc123-def456",
144
+ "status": "active",
145
+ "item_name": "Pro Plan",
146
+ "parent_order_id": 10,
147
+ "customer_id": 5,
148
+ "product_id": 3,
149
+ "variation_id": 7,
150
+ "vendor_subscription_id": "sub_1234567890",
151
+ "vendor_customer_id": "cus_abc123",
152
+ "current_payment_method": "stripe",
153
+ "billing_interval": "monthly",
154
+ "recurring_amount": 2999,
155
+ "bill_times": 0,
156
+ "bill_count": 6,
157
+ "next_billing_date": "2025-02-15 00:00:00",
158
+ "billing_address": { ... },
159
+ "shipping_address": { ... },
160
+ "labels": [ ... ],
161
+ "activities": [ ... ],
162
+ "customer": {
163
+ "id": 5,
164
+ "shipping_address": { ... },
165
+ "billing_address": { ... }
166
+ },
167
+ "related_orders": [
168
+ {
169
+ "id": 10,
170
+ "order_items": [
171
+ {
172
+ "id": 1,
173
+ "order_id": 10,
174
+ "post_title": "Pro Plan",
175
+ "title": "Pro Plan",
176
+ "quantity": 1,
177
+ "payment_type": "subscription",
178
+ "line_meta": { ... }
179
+ }
180
+ ]
181
+ }
182
+ ]
183
+ },
184
+ "selected_labels": [1, 3, 5]
185
+ }
186
+ ```
187
+
188
+ #### Example
189
+
190
+ ```bash
191
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/subscriptions/1" \
192
+ -u "username:app_password"
193
+ ```
194
+
195
+ ---
196
+
197
+ ### Cancel Subscription
198
+
199
+ `PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/cancel`
200
+
201
+ Cancel a subscription both locally and with the remote payment gateway.
202
+
203
+ **Permission:** `subscriptions/manage`
204
+
205
+ **Policy:** `OrderPolicy`
206
+
207
+ #### Parameters
208
+
209
+ | Parameter | Type | Location | Required | Description |
210
+ |-----------|------|----------|----------|-------------|
211
+ | `order` | integer | path | Yes | The parent order ID |
212
+ | `subscription` | integer | path | Yes | The subscription ID |
213
+ | `cancel_reason` | string | body | Yes | Reason for cancellation |
214
+
215
+ #### Response
216
+
217
+ ```json
218
+ {
219
+ "message": "Subscription has been cancelled successfully!",
220
+ "subscription": {
221
+ "id": 1,
222
+ "status": "canceled"
223
+ }
224
+ }
225
+ ```
226
+
227
+ #### Example
228
+
229
+ ```bash
230
+ curl -X PUT "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/cancel" \
231
+ -u "username:app_password" \
232
+ -H "Content-Type: application/json" \
233
+ -d '{"cancel_reason": "Customer requested cancellation"}'
234
+ ```
235
+
236
+ ---
237
+
238
+ ### Fetch Subscription from Remote
239
+
240
+ `PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/fetch`
241
+
242
+ Re-sync a subscription's data from the remote payment gateway (e.g., Stripe, PayPal).
243
+
244
+ **Permission:** `subscriptions/view`
245
+
246
+ **Policy:** `OrderPolicy`
247
+
248
+ #### Parameters
249
+
250
+ | Parameter | Type | Location | Required | Description |
251
+ |-----------|------|----------|----------|-------------|
252
+ | `order` | integer | path | Yes | The parent order ID |
253
+ | `subscription` | integer | path | Yes | The subscription ID |
254
+
255
+ #### Response
256
+
257
+ ```json
258
+ {
259
+ "message": "Subscription fetched successfully from remote payment gateway!",
260
+ "subscription": {
261
+ "id": 1,
262
+ "status": "active",
263
+ "vendor_subscription_id": "sub_1234567890"
264
+ }
265
+ }
266
+ ```
267
+
268
+ #### Example
269
+
270
+ ```bash
271
+ curl -X PUT "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/fetch" \
272
+ -u "username:app_password"
273
+ ```
274
+
275
+ ---
276
+
277
+ ### Generate Early Payment Link
278
+
279
+ `POST /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/early-payment-link`
280
+
281
+ Generate a URL that allows early payment of remaining installments on an installment-based subscription.
282
+
283
+ **Permission:** `subscriptions/manage`
284
+
285
+ **Policy:** `OrderPolicy`
286
+
287
+ #### Parameters
288
+
289
+ | Parameter | Type | Location | Required | Description |
290
+ |-----------|------|----------|----------|-------------|
291
+ | `order` | integer | path | Yes | The parent order ID |
292
+ | `subscription` | integer | path | Yes | The subscription ID |
293
+
294
+ #### Response
295
+
296
+ ```json
297
+ {
298
+ "message": "Early payment link generated.",
299
+ "payment_url": "https://your-site.com/?fluent-cart=early-installment-payment&subscription_hash=abc123-def456"
300
+ }
301
+ ```
302
+
303
+ #### Example
304
+
305
+ ```bash
306
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/orders/10/subscriptions/1/early-payment-link" \
307
+ -u "username:app_password"
308
+ ```
309
+
310
+ ---
311
+
312
+ ### Reserved Admin Endpoints
313
+
314
+ - `PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/reactivate`
315
+ - `PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/pause`
316
+ - `PUT /fluent-cart/v2/orders/{order}/subscriptions/{subscription}/resume`
317
+
318
+ *Note: Registered but currently return "Not available yet". Reserved for future implementation.*
319
+
320
+ ---
321
+
322
+ ## Customer Portal Endpoints
323
+
324
+ Authenticated via logged-in WordPress user session. Uses subscription `uuid` (not numeric ID). Authorization: `CustomerFrontendPolicy`.
325
+
326
+ ### List Customer Subscriptions
327
+
328
+ `GET /fluent-cart/v2/customer-profile/subscriptions`
329
+
330
+ Retrieve a paginated list of subscriptions belonging to the currently logged-in customer. Pending/intended subscriptions are excluded.
331
+
332
+ **Auth:** Logged-in WordPress user
333
+
334
+ **Policy:** `CustomerFrontendPolicy`
335
+
336
+ #### Parameters
337
+
338
+ | Parameter | Type | Location | Required | Description |
339
+ |-----------|------|----------|----------|-------------|
340
+ | `page` | integer | query | No | Page number for pagination (default: 1) |
341
+ | `per_page` | integer | query | No | Number of records per page (default: 10) |
342
+
343
+ #### Response
344
+
345
+ ```json
346
+ {
347
+ "message": "Success",
348
+ "subscriptions": {
349
+ "data": [
350
+ {
351
+ "uuid": "abc123-def456",
352
+ "status": "active",
353
+ "item_name": "Pro Plan",
354
+ "billing_interval": "monthly",
355
+ "recurring_amount": 2999,
356
+ "next_billing_date": "2025-02-15 00:00:00",
357
+ "bill_times": 0,
358
+ "bill_count": 6
359
+ }
360
+ ],
361
+ "total": 5,
362
+ "per_page": 10,
363
+ "current_page": 1,
364
+ "last_page": 1
365
+ }
366
+ }
367
+ ```
368
+
369
+ #### Example
370
+
371
+ ```bash
372
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions?page=1&per_page=10" \
373
+ -H "X-WP-Nonce: <nonce>"
374
+ ```
375
+
376
+ ---
377
+
378
+ ### Get Customer Subscription Details
379
+
380
+ `GET /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}`
381
+
382
+ Retrieve full details of a specific subscription for the currently logged-in customer, including transactions, upgrade eligibility, and payment method capabilities.
383
+
384
+ **Auth:** Logged-in WordPress user
385
+
386
+ **Policy:** `CustomerFrontendPolicy`
387
+
388
+ #### Parameters
389
+
390
+ | Parameter | Type | Location | Required | Description |
391
+ |-----------|------|----------|----------|-------------|
392
+ | `subscription_uuid` | string | path | Yes | The subscription UUID |
393
+
394
+ #### Response
395
+
396
+ ```json
397
+ {
398
+ "message": "Success",
399
+ "subscription": {
400
+ "uuid": "abc123-def456",
401
+ "status": "active",
402
+ "overridden_status": null,
403
+ "vendor_subscription_id": "sub_1234567890",
404
+ "next_billing_date": "2025-02-15 00:00:00",
405
+ "billing_info": {
406
+ "interval": "monthly",
407
+ "interval_count": 1,
408
+ "amount": 2999,
409
+ "currency": "USD"
410
+ },
411
+ "current_payment_method": "stripe",
412
+ "payment_method": "stripe",
413
+ "bill_times": 0,
414
+ "bill_count": 6,
415
+ "variation_id": 7,
416
+ "product_id": 3,
417
+ "reactivate_url": "https://your-site.com/?fluent-cart=reactivate&hash=abc123",
418
+ "title": "Pro Plan",
419
+ "can_upgrade": true,
420
+ "can_switch_payment_method": true,
421
+ "switchable_payment_methods": ["stripe", "paypal"],
422
+ "can_update_payment_method": true,
423
+ "order": {
424
+ "uuid": "order-uuid-here"
425
+ },
426
+ "billing_addresses": [ ... ],
427
+ "recurring_amount": 2999,
428
+ "can_early_pay": false,
429
+ "remaining_installments": 0,
430
+ "transactions": [ ... ]
431
+ }
432
+ }
433
+ ```
434
+
435
+ #### Example
436
+
437
+ ```bash
438
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456" \
439
+ -H "X-WP-Nonce: <nonce>"
440
+ ```
441
+
442
+ ---
443
+
444
+ ### Get Setup Intent Remaining Attempts
445
+
446
+ `GET /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/setup-intent-attempts`
447
+
448
+ Check remaining Stripe SetupIntent attempts (Stripe only).
449
+
450
+ **Auth:** Logged-in WordPress user
451
+
452
+ #### Response
453
+
454
+ ```json
455
+ {
456
+ "remaining": 5
457
+ }
458
+ ```
459
+
460
+ ---
461
+
462
+ ### Update Payment Method
463
+
464
+ `POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/update-payment-method`
465
+
466
+ Update the payment method card/details on file within the same payment gateway.
467
+
468
+ **Auth:** Logged-in WordPress user
469
+
470
+ #### Parameters
471
+
472
+ | Parameter | Type | Location | Required | Description |
473
+ |-----------|------|----------|----------|-------------|
474
+ | `subscription_uuid` | string | path | Yes | The subscription UUID |
475
+ | `data.method` | string | body | Yes | Gateway slug (e.g., `stripe`, `paypal`) |
476
+
477
+ #### Example
478
+
479
+ ```bash
480
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/update-payment-method" \
481
+ -H "X-WP-Nonce: <nonce>" \
482
+ -H "Content-Type: application/json" \
483
+ -d '{
484
+ "data": {
485
+ "method": "stripe",
486
+ "payment_method_id": "pm_1234567890"
487
+ }
488
+ }'
489
+ ```
490
+
491
+ ---
492
+
493
+ ### Get or Create Plan
494
+
495
+ `POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/get-or-create-plan`
496
+
497
+ Ensure target gateway has a matching plan configured during payment method switch.
498
+
499
+ **Auth:** Logged-in WordPress user
500
+
501
+ ---
502
+
503
+ ### Switch Payment Method
504
+
505
+ `POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/switch-payment-method`
506
+
507
+ Switch payment method from one gateway to another (e.g., Stripe to PayPal).
508
+
509
+ **Auth:** Logged-in WordPress user
510
+
511
+ #### Example
512
+
513
+ ```bash
514
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/switch-payment-method" \
515
+ -H "X-WP-Nonce: <nonce>" \
516
+ -H "Content-Type: application/json" \
517
+ -d '{
518
+ "data": {
519
+ "newPaymentMethod": "paypal",
520
+ "currentPaymentMethod": "stripe"
521
+ }
522
+ }'
523
+ ```
524
+
525
+ ---
526
+
527
+ ### Confirm Subscription Switch
528
+
529
+ `POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/confirm-subscription-switch`
530
+
531
+ Confirm a two-step payment method switch on the target gateway.
532
+
533
+ **Auth:** Logged-in WordPress user
534
+
535
+ ---
536
+
537
+ ### Cancel Auto-Renew
538
+
539
+ `POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/cancel-auto-renew`
540
+
541
+ Cancel auto-renewal from customer portal (reasons set to `cancelled_by_customer`).
542
+
543
+ **Auth:** Logged-in WordPress user
544
+
545
+ #### Response
546
+
547
+ ```json
548
+ {
549
+ "message": "Your subscription has been successfully cancelled"
550
+ }
551
+ ```
552
+
553
+ #### Example
554
+
555
+ ```bash
556
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/customer-profile/subscriptions/abc123-def456/cancel-auto-renew" \
557
+ -H "X-WP-Nonce: <nonce>"
558
+ ```
559
+
560
+ ---
561
+
562
+ ### Initiate Early Payment
563
+
564
+ `POST /fluent-cart/v2/customer-profile/subscriptions/{subscription_uuid}/initiate-early-payment`
565
+
566
+ Generate a checkout URL for paying remaining installments early on installment subscriptions.
567
+
568
+ **Auth:** Logged-in WordPress user
569
+
570
+ #### Response
571
+
572
+ ```json
573
+ {
574
+ "message": "Early payment URL generated.",
575
+ "checkout_url": "https://your-site.com/?fluent-cart=early-installment-payment&subscription_hash=abc123-def456"
576
+ }
577
+ ```
578
+
579
+ ---
580
+
581
+ ## Subscription Statuses & Hooks Reference
582
+
583
+ ### Statuses
584
+
585
+ | Status | Constant | Description |
586
+ |--------|----------|-------------|
587
+ | `pending` | `SUBSCRIPTION_PENDING` | Created but not yet activated |
588
+ | `intended` | `SUBSCRIPTION_INTENDED` | Payment intent created, awaiting completion |
589
+ | `trialing` | `SUBSCRIPTION_TRIALING` | In trial period |
590
+ | `active` | `SUBSCRIPTION_ACTIVE` | Active and billing normally |
591
+ | `paused` | `SUBSCRIPTION_PAUSED` | Temporarily paused |
592
+ | `failing` | `SUBSCRIPTION_FAILING` | Payment attempts failing |
593
+ | `expiring` | `SUBSCRIPTION_EXPIRING` | Approaching expiration |
594
+ | `expired` | `SUBSCRIPTION_EXPIRED` | Expired |
595
+ | `canceled` | `SUBSCRIPTION_CANCELED` | Cancelled by admin or customer |
596
+ | `past_due` | `SUBSCRIPTION_PAST_DUE` | Payment is overdue |
597
+ | `completed` | `SUBSCRIPTION_COMPLETED` | All installments paid |
598
+ | `authenticated` | `SUBSCRIPTION_AUTHENTICATED` | SCA flow completed |
599
+ | `created` | `SUBSCRIPTION_CREATED` | Created on remote gateway |
600
+
601
+ ### Hooks & Filters
602
+
603
+ - `fluent_cart/subscription/view` — Filter subscription data before returning in admin detail view.
604
+ - `fluent_cart/customer_portal/subscription_data` — Filter subscription data in customer portal detail view.
605
+ - `fluent_cart/subscriptions_list_filter_query` — Filter subscription list query before execution.
606
+ - `fluent_cart/subscriptions_filter/{provider}/{property}` — Custom advanced filter handler.