fluentcart-developer 1.1.0 → 1.1.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 (65) hide show
  1. package/CLAUDE.md +22 -22
  2. package/LICENSE +21 -21
  3. package/README.md +169 -127
  4. package/SKILL.md +127 -127
  5. package/bin/index.js +281 -281
  6. package/package.json +48 -37
  7. package/skills/fluentcart-developer/SKILL.md +172 -172
  8. package/skills/fluentcart-developer/examples/README.md +25 -25
  9. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  10. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  11. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -114
  12. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -149
  13. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  14. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -62
  15. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -787
  16. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  17. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  18. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  19. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  20. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  21. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  22. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  23. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  24. package/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  25. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -940
  26. package/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  27. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  28. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  29. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -902
  30. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  31. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -1319
  32. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  33. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  34. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  35. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  36. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  37. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  38. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -286
  39. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -794
  40. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  41. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  42. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  43. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  44. package/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  45. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  46. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  47. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -171
  48. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  49. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -1241
  50. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  51. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -2563
  52. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  53. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  54. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  55. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  56. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  57. package/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  58. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -606
  59. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  60. package/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  61. package/skills/fluentcart-developer/scripts/cli.js +1 -1
  62. package/.gitattributes +0 -2
  63. package/CONTRIBUTING.md +0 -73
  64. package/copy-skills.js +0 -43
  65. package/skills.sh.json +0 -13
@@ -1,794 +1,794 @@
1
- # Coupons API
2
-
3
- Create and manage discount coupons, apply coupons to orders, and configure coupon settings.
4
-
5
- **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/coupons`
6
-
7
- **Policy:** `CouponPolicy`
8
-
9
- > All monetary values are in cents (e.g., `$10.00` = `1000`).
10
-
11
- ---
12
-
13
- ## Endpoints Overview
14
-
15
- | Method | Endpoint | Description |
16
- |--------|----------|-------------|
17
- | GET | `/coupons/listCoupons` | List Coupon Codes (lightweight array) |
18
- | GET | `/coupons` | List Coupons (Paginated with filters) |
19
- | GET | `/coupons/getSettings` | Get Coupon Settings |
20
- | GET | `/coupons/{id}` | View Coupon Details |
21
- | POST | `/coupons` | Create Coupon |
22
- | PUT | `/coupons/{id}` | Update Coupon |
23
- | DELETE | `/coupons/{id}` | Delete Coupon |
24
- | POST | `/coupons/apply` | Apply Coupon to order items |
25
- | POST | `/coupons/cancel` | Cancel Coupon from order |
26
- | POST | `/coupons/re-apply` | Re-apply Coupons on item change |
27
- | POST | `/coupons/checkProductEligibility` | Check Product Eligibility for coupons |
28
- | POST | `/coupons/storeCouponSettings` | Store Coupon Settings |
29
-
30
- ---
31
-
32
- ## List Coupon Codes
33
-
34
- `GET /fluent-cart/v2/coupons/listCoupons`
35
-
36
- Retrieve a simple array of active coupon codes. This lightweight endpoint is designed for use in order creation forms and quick coupon lookups.
37
-
38
- **Permission:** `orders/create` or `orders/manage` or `coupons/view`
39
-
40
- ### Response
41
-
42
- ```json
43
- {
44
- "coupons": [
45
- "SAVE10",
46
- "WELCOME20",
47
- "FREESHIP"
48
- ]
49
- }
50
- ```
51
-
52
- *The response returns only the code values of coupons with active status.*
53
-
54
- ### Example
55
-
56
- ```bash
57
- curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons/listCoupons" \
58
- -u "username:app_password"
59
- ```
60
-
61
- ---
62
-
63
- ## List Coupons (Paginated)
64
-
65
- `GET /fluent-cart/v2/coupons`
66
-
67
- Retrieve a paginated list of coupons with optional filtering, sorting, and search. Coupon statuses are automatically updated based on their start/end dates before the response is returned.
68
-
69
- **Permission:** `coupons/view`
70
-
71
- ### Parameters
72
-
73
- | Parameter | Type | Location | Required | Description |
74
- |-----------|------|----------|----------|-------------|
75
- | `page` | integer | query | No | Page number for pagination |
76
- | `per_page` | integer | query | No | Number of records per page (1-199, default: 10) |
77
- | `search` | string | query | No | Search by coupon title, code, or ID. If search contains `%`, searches percentage coupons by amount. Numeric values match amount (cents). Supports operator syntax (e.g., `status = active`, `id > 5`) |
78
- | `sort_by` | string | query | No | Column to sort by (default: `id`). Must be a fillable column on Coupon model |
79
- | `sort_type` | string | query | No | Sort direction: `asc` or `desc` (default: `desc`) |
80
- | `active_view` | string | query | No | Tab filter: `active` or `expired` |
81
- | `filter_type` | string | query | No | Filter mode: `simple` (default) or `advanced` |
82
- | `advanced_filters` | string (JSON) | query | No | JSON-encoded array of advanced filter groups (Pro only) |
83
- | `with` | array/string | query | No | Eager-load relations |
84
- | `select` | array/string | query | No | Comma-separated list of columns to select |
85
- | `include_ids` | array/string | query | No | Comma-separated IDs that must always be included |
86
- | `user_tz` | string | query | No | User timezone for date filtering (e.g., `America/New_York`) |
87
-
88
- ### Active View Filters
89
-
90
- | View | Behavior |
91
- |------|----------|
92
- | `active` | Coupons where `status = 'active'` |
93
- | `expired` | Coupons where `end_date` has passed (and is not null/empty), or status != `'active'` |
94
-
95
- ### Response
96
-
97
- ```json
98
- {
99
- "coupons": {
100
- "total": 25,
101
- "per_page": 10,
102
- "current_page": 1,
103
- "last_page": 3,
104
- "data": [
105
- {
106
- "id": 1,
107
- "parent": null,
108
- "title": "10% Off Everything",
109
- "code": "SAVE10",
110
- "status": "active",
111
- "type": "percentage",
112
- "conditions": {
113
- "min_purchase_amount": 5000,
114
- "max_discount_amount": 10000,
115
- "max_purchase_amount": 0,
116
- "apply_to_whole_cart": "no",
117
- "apply_to_quantity": "no",
118
- "max_uses": 100,
119
- "max_per_customer": 1,
120
- "excluded_categories": [],
121
- "included_categories": [],
122
- "excluded_products": [],
123
- "included_products": [],
124
- "email_restrictions": "",
125
- "is_recurring": "no"
126
- },
127
- "amount": 10,
128
- "stackable": "yes",
129
- "priority": 1,
130
- "use_count": 12,
131
- "notes": "",
132
- "show_on_checkout": "yes",
133
- "start_date": "2025-01-01 00:00:00",
134
- "end_date": "2025-12-31 23:59:59",
135
- "created_at": "2025-01-01 10:00:00",
136
- "updated_at": "2025-06-15 14:30:00",
137
- "total_items": 12
138
- }
139
- ]
140
- }
141
- }
142
- ```
143
-
144
- ### Example
145
-
146
- ```bash
147
- curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons?page=1&per_page=20&search=SAVE&active_view=active" \
148
- -u "username:app_password"
149
- ```
150
-
151
- ---
152
-
153
- ## Get Coupon Settings
154
-
155
- `GET /fluent-cart/v2/coupons/getSettings`
156
-
157
- Retrieve the global coupon settings (currently, whether coupon input is shown on the checkout page).
158
-
159
- **Permission:** `coupons/view`
160
-
161
- ### Response
162
-
163
- ```json
164
- {
165
- "show_on_checkout": 1
166
- }
167
- ```
168
-
169
- ### Example
170
-
171
- ```bash
172
- curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons/getSettings" \
173
- -u "username:app_password"
174
- ```
175
-
176
- ---
177
-
178
- ## View Coupon Details
179
-
180
- `GET /fluent-cart/v2/coupons/{id}`
181
-
182
- Retrieve detailed information about a specific coupon, including its activity log.
183
-
184
- **Permission:** `coupons/view`
185
-
186
- ### Parameters
187
-
188
- | Parameter | Type | Location | Required | Description |
189
- |-----------|------|----------|----------|-------------|
190
- | `id` | integer | path | Yes | The coupon ID |
191
-
192
- ### Response
193
-
194
- ```json
195
- {
196
- "coupon": {
197
- "id": 1,
198
- "parent": null,
199
- "title": "10% Off Everything",
200
- "code": "SAVE10",
201
- "status": "active",
202
- "type": "percentage",
203
- "conditions": {
204
- "min_purchase_amount": 5000,
205
- "max_discount_amount": 10000,
206
- "max_purchase_amount": 0,
207
- "apply_to_whole_cart": "no",
208
- "apply_to_quantity": "no",
209
- "max_uses": 100,
210
- "max_per_customer": 1,
211
- "excluded_categories": [],
212
- "included_categories": [],
213
- "excluded_products": [],
214
- "included_products": [],
215
- "email_restrictions": "",
216
- "is_recurring": "no"
217
- },
218
- "amount": 10,
219
- "stackable": "yes",
220
- "priority": 1,
221
- "use_count": 12,
222
- "notes": "Internal note about this coupon",
223
- "show_on_checkout": "yes",
224
- "start_date": "2025-01-01 00:00:00",
225
- "end_date": "2025-12-31 23:59:59",
226
- "created_at": "2025-01-01 10:00:00",
227
- "updated_at": "2025-06-15 14:30:00",
228
- "activities": [
229
- {
230
- "id": 1,
231
- "title": "Coupon Created",
232
- "content": "Coupon \"SAVE10\" created by Admin",
233
- "status": "success",
234
- "user_id": 1,
235
- "created_at": "2025-01-01 10:00:00",
236
- "user": {
237
- "ID": 1,
238
- "display_name": "Admin"
239
- }
240
- }
241
- ]
242
- }
243
- }
244
- ```
245
-
246
- ### Example
247
-
248
- ```bash
249
- curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons/1" \
250
- -u "username:app_password"
251
- ```
252
-
253
- ---
254
-
255
- ## Create Coupon
256
-
257
- `POST /fluent-cart/v2/coupons`
258
-
259
- Create a new discount coupon.
260
-
261
- **Permission:** `coupons/manage`
262
-
263
- ### Parameters
264
-
265
- | Parameter | Type | Location | Required | Description |
266
- |-----------|------|----------|----------|-------------|
267
- | `title` | string | body | Yes | Coupon display name. Max 200 characters. |
268
- | `code` | string | body | Yes | Unique coupon code. Max 50 characters. Must be unique. |
269
- | `type` | string | body | Yes | Discount type: `fixed`, `percentage`, `free_shipping`, `buy_x_get_y` |
270
- | `amount` | number | body | Yes | Discount amount. Percentage: 0-100. Fixed: amount in store currency (auto-converted to cents). |
271
- | `status` | string | body | Yes | Coupon status: `active`, `expired`, `disabled`, `scheduled` |
272
- | `stackable` | string | body | Yes | Combine with others: `yes` or `no`. Max 50 chars. |
273
- | `show_on_checkout` | string | body | Yes | Display on checkout: `yes` or `no`. Max 50 chars. |
274
- | `priority` | integer | body | No | Sort priority for discount calculation order. Min: 0. |
275
- | `notes` | string | body | No | Internal notes about the coupon. |
276
- | `start_date` | string | body | Conditional | Start date. Required if `end_date` provided. Auto-converted to GMT. |
277
- | `end_date` | string | body | No | End date. Must be after `start_date` if provided. Auto-converted to GMT. |
278
- | `conditions` | object | body | No | Coupon conditions and restrictions (see below). |
279
-
280
- ### Conditions Object
281
-
282
- | Field | Type | Description |
283
- |-------|------|-------------|
284
- | `min_purchase_amount` | number | Minimum purchase amount in store currency. Auto-converted to cents. |
285
- | `max_discount_amount` | number | Maximum discount cap in store currency. Auto-converted to cents. |
286
- | `max_purchase_amount` | number | Maximum purchase amount allowed. |
287
- | `apply_to_whole_cart` | string | Apply discount to entire cart (`yes` or `no`). |
288
- | `apply_to_quantity` | string | Apply discount per quantity (`yes` or `no`). |
289
- | `max_uses` | integer | Maximum total uses across all customers (>= `max_per_customer`). |
290
- | `max_per_customer` | integer | Maximum uses per customer. |
291
- | `included_products` | array | Product IDs coupon is limited to. |
292
- | `excluded_products` | array | Product IDs excluded from coupon. |
293
- | `included_categories` | array | Category term IDs coupon is limited to. |
294
- | `excluded_categories` | array | Category term IDs excluded from coupon. |
295
- | `email_restrictions` | string | Email-based restriction. |
296
- | `is_recurring` | string | Applies to subscription renewals (`yes` or `no`). |
297
- | `buy_products` | array | Product IDs for buy part of buy-x-get-y coupons. |
298
- | `get_products` | array | Product IDs for get part of buy-x-get-y coupons. |
299
-
300
- ### Response
301
-
302
- ```json
303
- {
304
- "message": "Coupon created successfully!",
305
- "data": {
306
- "id": 5,
307
- "parent": null,
308
- "title": "Summer Sale 20%",
309
- "code": "SUMMER20",
310
- "status": "active",
311
- "type": "percentage",
312
- "conditions": {
313
- "min_purchase_amount": 2000,
314
- "max_discount_amount": 5000,
315
- "max_purchase_amount": 0,
316
- "apply_to_whole_cart": "yes",
317
- "apply_to_quantity": "no",
318
- "max_uses": 500,
319
- "max_per_customer": 2,
320
- "excluded_categories": [],
321
- "included_categories": [],
322
- "excluded_products": [],
323
- "included_products": [],
324
- "email_restrictions": "",
325
- "is_recurring": "no"
326
- },
327
- "amount": 20,
328
- "stackable": "yes",
329
- "priority": 1,
330
- "use_count": 0,
331
- "notes": "",
332
- "show_on_checkout": "yes",
333
- "start_date": "2025-06-01 00:00:00",
334
- "end_date": "2025-08-31 23:59:59",
335
- "created_at": "2025-05-25 10:00:00",
336
- "updated_at": "2025-05-25 10:00:00"
337
- }
338
- }
339
- ```
340
-
341
- ### Example
342
-
343
- ```bash
344
- curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons" \
345
- -u "username:app_password" \
346
- -H "Content-Type: application/json" \
347
- -d '{
348
- "title": "Summer Sale 20%",
349
- "code": "SUMMER20",
350
- "type": "percentage",
351
- "amount": 20,
352
- "status": "active",
353
- "stackable": "yes",
354
- "show_on_checkout": "yes",
355
- "priority": 1,
356
- "start_date": "2025-06-01 00:00:00",
357
- "end_date": "2025-08-31 23:59:59",
358
- "conditions": {
359
- "min_purchase_amount": 20.00,
360
- "max_discount_amount": 50.00,
361
- "max_uses": 500,
362
- "max_per_customer": 2,
363
- "apply_to_whole_cart": "yes",
364
- "is_recurring": "no"
365
- }
366
- }'
367
- ```
368
-
369
- ---
370
-
371
- ## Update Coupon
372
-
373
- `PUT /fluent-cart/v2/coupons/{id}`
374
-
375
- Update an existing coupon. Accepts the same fields as Create Coupon.
376
-
377
- **Permission:** `coupons/manage`
378
-
379
- ### Parameters
380
-
381
- | Parameter | Type | Location | Required | Description |
382
- |-----------|------|----------|----------|-------------|
383
- | `id` | integer | path | Yes | The coupon ID |
384
-
385
- ### Response
386
-
387
- ```json
388
- {
389
- "message": "Coupon updated successfully!",
390
- "data": {
391
- "id": 5,
392
- "title": "Summer Sale 25%",
393
- "code": "SUMMER25",
394
- "status": "active",
395
- "type": "percentage",
396
- "amount": 25,
397
- "conditions": { ... },
398
- "stackable": "yes",
399
- "priority": 1,
400
- "use_count": 12,
401
- "notes": "",
402
- "show_on_checkout": "yes",
403
- "start_date": "2025-06-01 00:00:00",
404
- "end_date": "2025-08-31 23:59:59",
405
- "created_at": "2025-05-25 10:00:00",
406
- "updated_at": "2025-06-20 11:00:00"
407
- }
408
- }
409
- ```
410
-
411
- ### Example
412
-
413
- ```bash
414
- curl -X PUT "https://example.com/wp-json/fluent-cart/v2/coupons/5" \
415
- -u "username:app_password" \
416
- -H "Content-Type: application/json" \
417
- -d '{
418
- "title": "Summer Sale 25%",
419
- "code": "SUMMER25",
420
- "type": "percentage",
421
- "amount": 25,
422
- "status": "active",
423
- "stackable": "yes",
424
- "show_on_checkout": "yes"
425
- }'
426
- ```
427
-
428
- ---
429
-
430
- ## Delete Coupon
431
-
432
- `DELETE /fluent-cart/v2/coupons/{id}`
433
-
434
- Permanently delete a coupon.
435
-
436
- **Permission:** `coupons/delete`
437
-
438
- ### Parameters
439
-
440
- | Parameter | Type | Location | Required | Description |
441
- |-----------|------|----------|----------|-------------|
442
- | `id` | integer | path/body | Yes | The coupon ID |
443
-
444
- ### Response
445
-
446
- ```json
447
- {
448
- "message": "Coupon successfully deleted.",
449
- "data": ""
450
- }
451
- ```
452
-
453
- ### Example
454
-
455
- ```bash
456
- curl -X DELETE "https://example.com/wp-json/fluent-cart/v2/coupons/5" \
457
- -u "username:app_password"
458
- ```
459
-
460
- ---
461
-
462
- ## Apply Coupon
463
-
464
- `POST /fluent-cart/v2/coupons/apply`
465
-
466
- Apply a coupon code to a set of order line items and return recalculated discount breakdown.
467
-
468
- **Permission:** `orders/create` or `orders/manage`
469
-
470
- ### Parameters
471
-
472
- | Parameter | Type | Location | Required | Description |
473
- |-----------|------|----------|----------|-------------|
474
- | `coupon_code` | string | body | Yes | The coupon code to apply |
475
- | `order_items` | array | body | Yes | Array of order line item objects |
476
- | `order_uuid` | string | body | No | UUID of an existing order to apply coupon to |
477
- | `applied_coupons` | array | body | No | Array of coupon IDs already applied |
478
- | `customer_email` | string | body | No | Customer email for restrictions |
479
-
480
- ### Response
481
-
482
- ```json
483
- {
484
- "applied_coupons": {
485
- "SAVE10": {
486
- "id": 1,
487
- "title": "10% Off",
488
- "code": "SAVE10",
489
- "type": "percentage",
490
- "amount": 10,
491
- "discount_amount": 500,
492
- "stackable": "yes",
493
- "priority": 1
494
- }
495
- },
496
- "calculated_items": [
497
- {
498
- "post_id": 42,
499
- "quantity": 2,
500
- "price": 2500,
501
- "discounted_price": 2250,
502
- "discount_total": 500
503
- }
504
- ]
505
- }
506
- ```
507
-
508
- ### Example
509
-
510
- ```bash
511
- curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/apply" \
512
- -u "username:app_password" \
513
- -H "Content-Type: application/json" \
514
- -d '{
515
- "coupon_code": "SAVE10",
516
- "order_items": [
517
- {
518
- "post_id": 42,
519
- "quantity": 2,
520
- "price": 2500,
521
- "unit_price": 2500,
522
- "item_total": 5000,
523
- "line_total": 5000,
524
- "other_info": {
525
- "payment_type": "onetime"
526
- }
527
- }
528
- ],
529
- "applied_coupons": []
530
- }'
531
- ```
532
-
533
- ---
534
-
535
- ## Cancel Coupon
536
-
537
- `POST /fluent-cart/v2/coupons/cancel`
538
-
539
- Remove a coupon from an order and recalculate remaining discounts.
540
-
541
- **Permission:** `orders/create` or `orders/manage`
542
-
543
- ### Parameters
544
-
545
- | Parameter | Type | Location | Required | Description |
546
- |-----------|------|----------|----------|-------------|
547
- | `coupon_code` | string | body | Yes | Coupon code to cancel |
548
- | `order_items` | array | body | Yes | Array of current order line item objects |
549
- | `id` | integer | body | No | Applied coupon record ID (from `fct_applied_coupons`) |
550
- | `order_uuid` | string | body | No | UUID of existing order |
551
- | `applied_coupons` | array | body | No | Array of remaining coupon IDs |
552
- | `customer_email` | string | body | No | Customer email address |
553
-
554
- ### Response
555
-
556
- ```json
557
- {
558
- "applied_coupons": {
559
- "WELCOME5": {
560
- "id": 2,
561
- "title": "Welcome $5 Off",
562
- "code": "WELCOME5",
563
- "type": "fixed",
564
- "amount": 500,
565
- "discount_amount": 500,
566
- "stackable": "yes",
567
- "priority": 2
568
- }
569
- },
570
- "calculated_items": [
571
- {
572
- "post_id": 42,
573
- "quantity": 2,
574
- "price": 2500,
575
- "discounted_price": 2250,
576
- "discount_total": 500
577
- }
578
- ]
579
- }
580
- ```
581
-
582
- ### Example
583
-
584
- ```bash
585
- curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/cancel" \
586
- -u "username:app_password" \
587
- -H "Content-Type: application/json" \
588
- -d '{
589
- "coupon_code": "SAVE10",
590
- "id": 15,
591
- "order_uuid": "abc123-def456",
592
- "order_items": [
593
- {
594
- "post_id": 42,
595
- "quantity": 2,
596
- "price": 2500,
597
- "unit_price": 2500,
598
- "item_total": 5000,
599
- "line_total": 5000
600
- }
601
- ],
602
- "applied_coupons": [2]
603
- }'
604
- ```
605
-
606
- ---
607
-
608
- ## Re-apply Coupons
609
-
610
- `POST /fluent-cart/v2/coupons/re-apply`
611
-
612
- Recalculate all previously applied coupons against current order items.
613
-
614
- **Permission:** `orders/create` or `orders/manage`
615
-
616
- ### Parameters
617
-
618
- | Parameter | Type | Location | Required | Description |
619
- |-----------|------|----------|----------|-------------|
620
- | `order_uuid` | string | body | No | UUID of existing order |
621
- | `order_items` | array | body | No | Array of current order line item objects |
622
- | `applied_coupons` | array | body | No | Array of coupon IDs to include |
623
-
624
- ### Response
625
-
626
- ```json
627
- {
628
- "applied_coupons": {
629
- "SAVE10": {
630
- "id": 1,
631
- "title": "10% Off",
632
- "code": "SAVE10",
633
- "type": "percentage",
634
- "amount": 10,
635
- "discount_amount": 450,
636
- "stackable": "yes",
637
- "priority": 1
638
- }
639
- },
640
- "calculated_items": [
641
- {
642
- "post_id": 42,
643
- "quantity": 1,
644
- "price": 2500,
645
- "discounted_price": 2250,
646
- "discount_total": 250
647
- }
648
- ]
649
- }
650
- ```
651
-
652
- ### Example
653
-
654
- ```bash
655
- curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/re-apply" \
656
- -u "username:app_password" \
657
- -H "Content-Type: application/json" \
658
- -d '{
659
- "order_uuid": "abc123-def456",
660
- "order_items": [
661
- {
662
- "post_id": 42,
663
- "quantity": 1,
664
- "price": 2500,
665
- "unit_price": 2500,
666
- "item_total": 2500,
667
- "line_total": 2500
668
- }
669
- ],
670
- "applied_coupons": [1]
671
- }'
672
- ```
673
-
674
- ---
675
-
676
- ## Check Product Eligibility
677
-
678
- `POST /fluent-cart/v2/coupons/checkProductEligibility`
679
-
680
- Check whether a product is eligible for a set of applied coupons.
681
-
682
- **Permission:** `orders/create` or `orders/manage`
683
-
684
- ### Parameters
685
-
686
- | Parameter | Type | Location | Required | Description |
687
- |-----------|------|----------|----------|-------------|
688
- | `productId` | integer | body | Yes | Product (post) ID to check |
689
- | `appliedCoupons` | array | body | No | Array of coupon codes currently applied |
690
- | `origin` | string | body | No | Context origin (e.g., `checkout`) |
691
-
692
- ### Response
693
-
694
- Eligible:
695
- ```json
696
- {
697
- "isApplicable": true
698
- }
699
- ```
700
-
701
- Not Eligible:
702
- ```json
703
- {
704
- "isApplicable": false,
705
- "message": "Product A conflicts with SAVE10 coupon. Remove the coupon first."
706
- }
707
- ```
708
-
709
- ### Example
710
-
711
- ```bash
712
- curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/checkProductEligibility" \
713
- -u "username:app_password" \
714
- -H "Content-Type: application/json" \
715
- -d '{
716
- "productId": 42,
717
- "appliedCoupons": ["SAVE10", "WELCOME5"],
718
- "origin": "admin_order"
719
- }'
720
- ```
721
-
722
- ---
723
-
724
- ## Store Coupon Settings
725
-
726
- `POST /fluent-cart/v2/coupons/storeCouponSettings`
727
-
728
- Update the global coupon settings.
729
-
730
- **Permission:** `coupons/manage`
731
-
732
- ### Parameters
733
-
734
- | Parameter | Type | Location | Required | Description |
735
- |-----------|------|----------|----------|-------------|
736
- | `show_on_checkout` | boolean | body | No | Whether to show coupon input on checkout page |
737
-
738
- ### Response
739
-
740
- ```json
741
- true
742
- ```
743
-
744
- ### Example
745
-
746
- ```bash
747
- curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/storeCouponSettings" \
748
- -u "username:app_password" \
749
- -H "Content-Type: application/json" \
750
- -d '{
751
- "show_on_checkout": true
752
- }'
753
- ```
754
-
755
- ---
756
-
757
- ## Coupon Model & Database Reference
758
-
759
- ### Coupon Types
760
-
761
- | Type | Description | Amount Handling |
762
- |------|-------------|-----------------|
763
- | `fixed` | Fixed amount discount | Stored in cents (e.g., 1000 = $10.00) |
764
- | `percentage` | Percentage discount | Stored as percentage (e.g., 10 = 10%). Max: 100 |
765
- | `free_shipping` | Free shipping coupon | Amount is typically 0 |
766
- | `buy_x_get_y` | Buy X Get Y promotion | Uses `conditions.buy_products` & `conditions.get_products` |
767
-
768
- ### Database Table (`fct_coupons`)
769
-
770
- | Column | Type | Description |
771
- |--------|------|-------------|
772
- | `id` | BIGINT (PK) | Auto-increment ID |
773
- | `parent` | BIGINT | Parent coupon ID |
774
- | `title` | VARCHAR(200) | Display name |
775
- | `code` | VARCHAR(50) | Unique coupon code |
776
- | `status` | VARCHAR(20) | Coupon status (`active`, `expired`, `disabled`, `scheduled`) |
777
- | `type` | VARCHAR(20) | Discount type |
778
- | `conditions` | TEXT (JSON) | JSON-encoded conditions object |
779
- | `amount` | BIGINT | Discount amount (cents or percentage) |
780
- | `stackable` | VARCHAR(10) | Stackability flag (`yes`/`no`) |
781
- | `priority` | INT | Sort priority |
782
- | `use_count` | INT | Usage count |
783
- | `notes` | TEXT | Internal notes |
784
- | `show_on_checkout` | VARCHAR(10) | Display on checkout flag |
785
- | `start_date` | DATETIME | Start date (GMT) |
786
- | `end_date` | DATETIME | End date (GMT) |
787
- | `created_at` | DATETIME | Creation timestamp |
788
- | `updated_at` | DATETIME | Last update timestamp |
789
-
790
- ### Hooks
791
-
792
- - `fluent_cart/coupon_created` — Action fired after coupon creation.
793
- - `fluent_cart/coupon_updated` — Action fired after coupon update.
794
- - `fluent_cart/coupons_list_filter_query` — Filter to modify coupon list query.
1
+ # Coupons API
2
+
3
+ Create and manage discount coupons, apply coupons to orders, and configure coupon settings.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/coupons`
6
+
7
+ **Policy:** `CouponPolicy`
8
+
9
+ > All monetary values are in cents (e.g., `$10.00` = `1000`).
10
+
11
+ ---
12
+
13
+ ## Endpoints Overview
14
+
15
+ | Method | Endpoint | Description |
16
+ |--------|----------|-------------|
17
+ | GET | `/coupons/listCoupons` | List Coupon Codes (lightweight array) |
18
+ | GET | `/coupons` | List Coupons (Paginated with filters) |
19
+ | GET | `/coupons/getSettings` | Get Coupon Settings |
20
+ | GET | `/coupons/{id}` | View Coupon Details |
21
+ | POST | `/coupons` | Create Coupon |
22
+ | PUT | `/coupons/{id}` | Update Coupon |
23
+ | DELETE | `/coupons/{id}` | Delete Coupon |
24
+ | POST | `/coupons/apply` | Apply Coupon to order items |
25
+ | POST | `/coupons/cancel` | Cancel Coupon from order |
26
+ | POST | `/coupons/re-apply` | Re-apply Coupons on item change |
27
+ | POST | `/coupons/checkProductEligibility` | Check Product Eligibility for coupons |
28
+ | POST | `/coupons/storeCouponSettings` | Store Coupon Settings |
29
+
30
+ ---
31
+
32
+ ## List Coupon Codes
33
+
34
+ `GET /fluent-cart/v2/coupons/listCoupons`
35
+
36
+ Retrieve a simple array of active coupon codes. This lightweight endpoint is designed for use in order creation forms and quick coupon lookups.
37
+
38
+ **Permission:** `orders/create` or `orders/manage` or `coupons/view`
39
+
40
+ ### Response
41
+
42
+ ```json
43
+ {
44
+ "coupons": [
45
+ "SAVE10",
46
+ "WELCOME20",
47
+ "FREESHIP"
48
+ ]
49
+ }
50
+ ```
51
+
52
+ *The response returns only the code values of coupons with active status.*
53
+
54
+ ### Example
55
+
56
+ ```bash
57
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons/listCoupons" \
58
+ -u "username:app_password"
59
+ ```
60
+
61
+ ---
62
+
63
+ ## List Coupons (Paginated)
64
+
65
+ `GET /fluent-cart/v2/coupons`
66
+
67
+ Retrieve a paginated list of coupons with optional filtering, sorting, and search. Coupon statuses are automatically updated based on their start/end dates before the response is returned.
68
+
69
+ **Permission:** `coupons/view`
70
+
71
+ ### Parameters
72
+
73
+ | Parameter | Type | Location | Required | Description |
74
+ |-----------|------|----------|----------|-------------|
75
+ | `page` | integer | query | No | Page number for pagination |
76
+ | `per_page` | integer | query | No | Number of records per page (1-199, default: 10) |
77
+ | `search` | string | query | No | Search by coupon title, code, or ID. If search contains `%`, searches percentage coupons by amount. Numeric values match amount (cents). Supports operator syntax (e.g., `status = active`, `id > 5`) |
78
+ | `sort_by` | string | query | No | Column to sort by (default: `id`). Must be a fillable column on Coupon model |
79
+ | `sort_type` | string | query | No | Sort direction: `asc` or `desc` (default: `desc`) |
80
+ | `active_view` | string | query | No | Tab filter: `active` or `expired` |
81
+ | `filter_type` | string | query | No | Filter mode: `simple` (default) or `advanced` |
82
+ | `advanced_filters` | string (JSON) | query | No | JSON-encoded array of advanced filter groups (Pro only) |
83
+ | `with` | array/string | query | No | Eager-load relations |
84
+ | `select` | array/string | query | No | Comma-separated list of columns to select |
85
+ | `include_ids` | array/string | query | No | Comma-separated IDs that must always be included |
86
+ | `user_tz` | string | query | No | User timezone for date filtering (e.g., `America/New_York`) |
87
+
88
+ ### Active View Filters
89
+
90
+ | View | Behavior |
91
+ |------|----------|
92
+ | `active` | Coupons where `status = 'active'` |
93
+ | `expired` | Coupons where `end_date` has passed (and is not null/empty), or status != `'active'` |
94
+
95
+ ### Response
96
+
97
+ ```json
98
+ {
99
+ "coupons": {
100
+ "total": 25,
101
+ "per_page": 10,
102
+ "current_page": 1,
103
+ "last_page": 3,
104
+ "data": [
105
+ {
106
+ "id": 1,
107
+ "parent": null,
108
+ "title": "10% Off Everything",
109
+ "code": "SAVE10",
110
+ "status": "active",
111
+ "type": "percentage",
112
+ "conditions": {
113
+ "min_purchase_amount": 5000,
114
+ "max_discount_amount": 10000,
115
+ "max_purchase_amount": 0,
116
+ "apply_to_whole_cart": "no",
117
+ "apply_to_quantity": "no",
118
+ "max_uses": 100,
119
+ "max_per_customer": 1,
120
+ "excluded_categories": [],
121
+ "included_categories": [],
122
+ "excluded_products": [],
123
+ "included_products": [],
124
+ "email_restrictions": "",
125
+ "is_recurring": "no"
126
+ },
127
+ "amount": 10,
128
+ "stackable": "yes",
129
+ "priority": 1,
130
+ "use_count": 12,
131
+ "notes": "",
132
+ "show_on_checkout": "yes",
133
+ "start_date": "2025-01-01 00:00:00",
134
+ "end_date": "2025-12-31 23:59:59",
135
+ "created_at": "2025-01-01 10:00:00",
136
+ "updated_at": "2025-06-15 14:30:00",
137
+ "total_items": 12
138
+ }
139
+ ]
140
+ }
141
+ }
142
+ ```
143
+
144
+ ### Example
145
+
146
+ ```bash
147
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons?page=1&per_page=20&search=SAVE&active_view=active" \
148
+ -u "username:app_password"
149
+ ```
150
+
151
+ ---
152
+
153
+ ## Get Coupon Settings
154
+
155
+ `GET /fluent-cart/v2/coupons/getSettings`
156
+
157
+ Retrieve the global coupon settings (currently, whether coupon input is shown on the checkout page).
158
+
159
+ **Permission:** `coupons/view`
160
+
161
+ ### Response
162
+
163
+ ```json
164
+ {
165
+ "show_on_checkout": 1
166
+ }
167
+ ```
168
+
169
+ ### Example
170
+
171
+ ```bash
172
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons/getSettings" \
173
+ -u "username:app_password"
174
+ ```
175
+
176
+ ---
177
+
178
+ ## View Coupon Details
179
+
180
+ `GET /fluent-cart/v2/coupons/{id}`
181
+
182
+ Retrieve detailed information about a specific coupon, including its activity log.
183
+
184
+ **Permission:** `coupons/view`
185
+
186
+ ### Parameters
187
+
188
+ | Parameter | Type | Location | Required | Description |
189
+ |-----------|------|----------|----------|-------------|
190
+ | `id` | integer | path | Yes | The coupon ID |
191
+
192
+ ### Response
193
+
194
+ ```json
195
+ {
196
+ "coupon": {
197
+ "id": 1,
198
+ "parent": null,
199
+ "title": "10% Off Everything",
200
+ "code": "SAVE10",
201
+ "status": "active",
202
+ "type": "percentage",
203
+ "conditions": {
204
+ "min_purchase_amount": 5000,
205
+ "max_discount_amount": 10000,
206
+ "max_purchase_amount": 0,
207
+ "apply_to_whole_cart": "no",
208
+ "apply_to_quantity": "no",
209
+ "max_uses": 100,
210
+ "max_per_customer": 1,
211
+ "excluded_categories": [],
212
+ "included_categories": [],
213
+ "excluded_products": [],
214
+ "included_products": [],
215
+ "email_restrictions": "",
216
+ "is_recurring": "no"
217
+ },
218
+ "amount": 10,
219
+ "stackable": "yes",
220
+ "priority": 1,
221
+ "use_count": 12,
222
+ "notes": "Internal note about this coupon",
223
+ "show_on_checkout": "yes",
224
+ "start_date": "2025-01-01 00:00:00",
225
+ "end_date": "2025-12-31 23:59:59",
226
+ "created_at": "2025-01-01 10:00:00",
227
+ "updated_at": "2025-06-15 14:30:00",
228
+ "activities": [
229
+ {
230
+ "id": 1,
231
+ "title": "Coupon Created",
232
+ "content": "Coupon \"SAVE10\" created by Admin",
233
+ "status": "success",
234
+ "user_id": 1,
235
+ "created_at": "2025-01-01 10:00:00",
236
+ "user": {
237
+ "ID": 1,
238
+ "display_name": "Admin"
239
+ }
240
+ }
241
+ ]
242
+ }
243
+ }
244
+ ```
245
+
246
+ ### Example
247
+
248
+ ```bash
249
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/coupons/1" \
250
+ -u "username:app_password"
251
+ ```
252
+
253
+ ---
254
+
255
+ ## Create Coupon
256
+
257
+ `POST /fluent-cart/v2/coupons`
258
+
259
+ Create a new discount coupon.
260
+
261
+ **Permission:** `coupons/manage`
262
+
263
+ ### Parameters
264
+
265
+ | Parameter | Type | Location | Required | Description |
266
+ |-----------|------|----------|----------|-------------|
267
+ | `title` | string | body | Yes | Coupon display name. Max 200 characters. |
268
+ | `code` | string | body | Yes | Unique coupon code. Max 50 characters. Must be unique. |
269
+ | `type` | string | body | Yes | Discount type: `fixed`, `percentage`, `free_shipping`, `buy_x_get_y` |
270
+ | `amount` | number | body | Yes | Discount amount. Percentage: 0-100. Fixed: amount in store currency (auto-converted to cents). |
271
+ | `status` | string | body | Yes | Coupon status: `active`, `expired`, `disabled`, `scheduled` |
272
+ | `stackable` | string | body | Yes | Combine with others: `yes` or `no`. Max 50 chars. |
273
+ | `show_on_checkout` | string | body | Yes | Display on checkout: `yes` or `no`. Max 50 chars. |
274
+ | `priority` | integer | body | No | Sort priority for discount calculation order. Min: 0. |
275
+ | `notes` | string | body | No | Internal notes about the coupon. |
276
+ | `start_date` | string | body | Conditional | Start date. Required if `end_date` provided. Auto-converted to GMT. |
277
+ | `end_date` | string | body | No | End date. Must be after `start_date` if provided. Auto-converted to GMT. |
278
+ | `conditions` | object | body | No | Coupon conditions and restrictions (see below). |
279
+
280
+ ### Conditions Object
281
+
282
+ | Field | Type | Description |
283
+ |-------|------|-------------|
284
+ | `min_purchase_amount` | number | Minimum purchase amount in store currency. Auto-converted to cents. |
285
+ | `max_discount_amount` | number | Maximum discount cap in store currency. Auto-converted to cents. |
286
+ | `max_purchase_amount` | number | Maximum purchase amount allowed. |
287
+ | `apply_to_whole_cart` | string | Apply discount to entire cart (`yes` or `no`). |
288
+ | `apply_to_quantity` | string | Apply discount per quantity (`yes` or `no`). |
289
+ | `max_uses` | integer | Maximum total uses across all customers (>= `max_per_customer`). |
290
+ | `max_per_customer` | integer | Maximum uses per customer. |
291
+ | `included_products` | array | Product IDs coupon is limited to. |
292
+ | `excluded_products` | array | Product IDs excluded from coupon. |
293
+ | `included_categories` | array | Category term IDs coupon is limited to. |
294
+ | `excluded_categories` | array | Category term IDs excluded from coupon. |
295
+ | `email_restrictions` | string | Email-based restriction. |
296
+ | `is_recurring` | string | Applies to subscription renewals (`yes` or `no`). |
297
+ | `buy_products` | array | Product IDs for buy part of buy-x-get-y coupons. |
298
+ | `get_products` | array | Product IDs for get part of buy-x-get-y coupons. |
299
+
300
+ ### Response
301
+
302
+ ```json
303
+ {
304
+ "message": "Coupon created successfully!",
305
+ "data": {
306
+ "id": 5,
307
+ "parent": null,
308
+ "title": "Summer Sale 20%",
309
+ "code": "SUMMER20",
310
+ "status": "active",
311
+ "type": "percentage",
312
+ "conditions": {
313
+ "min_purchase_amount": 2000,
314
+ "max_discount_amount": 5000,
315
+ "max_purchase_amount": 0,
316
+ "apply_to_whole_cart": "yes",
317
+ "apply_to_quantity": "no",
318
+ "max_uses": 500,
319
+ "max_per_customer": 2,
320
+ "excluded_categories": [],
321
+ "included_categories": [],
322
+ "excluded_products": [],
323
+ "included_products": [],
324
+ "email_restrictions": "",
325
+ "is_recurring": "no"
326
+ },
327
+ "amount": 20,
328
+ "stackable": "yes",
329
+ "priority": 1,
330
+ "use_count": 0,
331
+ "notes": "",
332
+ "show_on_checkout": "yes",
333
+ "start_date": "2025-06-01 00:00:00",
334
+ "end_date": "2025-08-31 23:59:59",
335
+ "created_at": "2025-05-25 10:00:00",
336
+ "updated_at": "2025-05-25 10:00:00"
337
+ }
338
+ }
339
+ ```
340
+
341
+ ### Example
342
+
343
+ ```bash
344
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons" \
345
+ -u "username:app_password" \
346
+ -H "Content-Type: application/json" \
347
+ -d '{
348
+ "title": "Summer Sale 20%",
349
+ "code": "SUMMER20",
350
+ "type": "percentage",
351
+ "amount": 20,
352
+ "status": "active",
353
+ "stackable": "yes",
354
+ "show_on_checkout": "yes",
355
+ "priority": 1,
356
+ "start_date": "2025-06-01 00:00:00",
357
+ "end_date": "2025-08-31 23:59:59",
358
+ "conditions": {
359
+ "min_purchase_amount": 20.00,
360
+ "max_discount_amount": 50.00,
361
+ "max_uses": 500,
362
+ "max_per_customer": 2,
363
+ "apply_to_whole_cart": "yes",
364
+ "is_recurring": "no"
365
+ }
366
+ }'
367
+ ```
368
+
369
+ ---
370
+
371
+ ## Update Coupon
372
+
373
+ `PUT /fluent-cart/v2/coupons/{id}`
374
+
375
+ Update an existing coupon. Accepts the same fields as Create Coupon.
376
+
377
+ **Permission:** `coupons/manage`
378
+
379
+ ### Parameters
380
+
381
+ | Parameter | Type | Location | Required | Description |
382
+ |-----------|------|----------|----------|-------------|
383
+ | `id` | integer | path | Yes | The coupon ID |
384
+
385
+ ### Response
386
+
387
+ ```json
388
+ {
389
+ "message": "Coupon updated successfully!",
390
+ "data": {
391
+ "id": 5,
392
+ "title": "Summer Sale 25%",
393
+ "code": "SUMMER25",
394
+ "status": "active",
395
+ "type": "percentage",
396
+ "amount": 25,
397
+ "conditions": { ... },
398
+ "stackable": "yes",
399
+ "priority": 1,
400
+ "use_count": 12,
401
+ "notes": "",
402
+ "show_on_checkout": "yes",
403
+ "start_date": "2025-06-01 00:00:00",
404
+ "end_date": "2025-08-31 23:59:59",
405
+ "created_at": "2025-05-25 10:00:00",
406
+ "updated_at": "2025-06-20 11:00:00"
407
+ }
408
+ }
409
+ ```
410
+
411
+ ### Example
412
+
413
+ ```bash
414
+ curl -X PUT "https://example.com/wp-json/fluent-cart/v2/coupons/5" \
415
+ -u "username:app_password" \
416
+ -H "Content-Type: application/json" \
417
+ -d '{
418
+ "title": "Summer Sale 25%",
419
+ "code": "SUMMER25",
420
+ "type": "percentage",
421
+ "amount": 25,
422
+ "status": "active",
423
+ "stackable": "yes",
424
+ "show_on_checkout": "yes"
425
+ }'
426
+ ```
427
+
428
+ ---
429
+
430
+ ## Delete Coupon
431
+
432
+ `DELETE /fluent-cart/v2/coupons/{id}`
433
+
434
+ Permanently delete a coupon.
435
+
436
+ **Permission:** `coupons/delete`
437
+
438
+ ### Parameters
439
+
440
+ | Parameter | Type | Location | Required | Description |
441
+ |-----------|------|----------|----------|-------------|
442
+ | `id` | integer | path/body | Yes | The coupon ID |
443
+
444
+ ### Response
445
+
446
+ ```json
447
+ {
448
+ "message": "Coupon successfully deleted.",
449
+ "data": ""
450
+ }
451
+ ```
452
+
453
+ ### Example
454
+
455
+ ```bash
456
+ curl -X DELETE "https://example.com/wp-json/fluent-cart/v2/coupons/5" \
457
+ -u "username:app_password"
458
+ ```
459
+
460
+ ---
461
+
462
+ ## Apply Coupon
463
+
464
+ `POST /fluent-cart/v2/coupons/apply`
465
+
466
+ Apply a coupon code to a set of order line items and return recalculated discount breakdown.
467
+
468
+ **Permission:** `orders/create` or `orders/manage`
469
+
470
+ ### Parameters
471
+
472
+ | Parameter | Type | Location | Required | Description |
473
+ |-----------|------|----------|----------|-------------|
474
+ | `coupon_code` | string | body | Yes | The coupon code to apply |
475
+ | `order_items` | array | body | Yes | Array of order line item objects |
476
+ | `order_uuid` | string | body | No | UUID of an existing order to apply coupon to |
477
+ | `applied_coupons` | array | body | No | Array of coupon IDs already applied |
478
+ | `customer_email` | string | body | No | Customer email for restrictions |
479
+
480
+ ### Response
481
+
482
+ ```json
483
+ {
484
+ "applied_coupons": {
485
+ "SAVE10": {
486
+ "id": 1,
487
+ "title": "10% Off",
488
+ "code": "SAVE10",
489
+ "type": "percentage",
490
+ "amount": 10,
491
+ "discount_amount": 500,
492
+ "stackable": "yes",
493
+ "priority": 1
494
+ }
495
+ },
496
+ "calculated_items": [
497
+ {
498
+ "post_id": 42,
499
+ "quantity": 2,
500
+ "price": 2500,
501
+ "discounted_price": 2250,
502
+ "discount_total": 500
503
+ }
504
+ ]
505
+ }
506
+ ```
507
+
508
+ ### Example
509
+
510
+ ```bash
511
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/apply" \
512
+ -u "username:app_password" \
513
+ -H "Content-Type: application/json" \
514
+ -d '{
515
+ "coupon_code": "SAVE10",
516
+ "order_items": [
517
+ {
518
+ "post_id": 42,
519
+ "quantity": 2,
520
+ "price": 2500,
521
+ "unit_price": 2500,
522
+ "item_total": 5000,
523
+ "line_total": 5000,
524
+ "other_info": {
525
+ "payment_type": "onetime"
526
+ }
527
+ }
528
+ ],
529
+ "applied_coupons": []
530
+ }'
531
+ ```
532
+
533
+ ---
534
+
535
+ ## Cancel Coupon
536
+
537
+ `POST /fluent-cart/v2/coupons/cancel`
538
+
539
+ Remove a coupon from an order and recalculate remaining discounts.
540
+
541
+ **Permission:** `orders/create` or `orders/manage`
542
+
543
+ ### Parameters
544
+
545
+ | Parameter | Type | Location | Required | Description |
546
+ |-----------|------|----------|----------|-------------|
547
+ | `coupon_code` | string | body | Yes | Coupon code to cancel |
548
+ | `order_items` | array | body | Yes | Array of current order line item objects |
549
+ | `id` | integer | body | No | Applied coupon record ID (from `fct_applied_coupons`) |
550
+ | `order_uuid` | string | body | No | UUID of existing order |
551
+ | `applied_coupons` | array | body | No | Array of remaining coupon IDs |
552
+ | `customer_email` | string | body | No | Customer email address |
553
+
554
+ ### Response
555
+
556
+ ```json
557
+ {
558
+ "applied_coupons": {
559
+ "WELCOME5": {
560
+ "id": 2,
561
+ "title": "Welcome $5 Off",
562
+ "code": "WELCOME5",
563
+ "type": "fixed",
564
+ "amount": 500,
565
+ "discount_amount": 500,
566
+ "stackable": "yes",
567
+ "priority": 2
568
+ }
569
+ },
570
+ "calculated_items": [
571
+ {
572
+ "post_id": 42,
573
+ "quantity": 2,
574
+ "price": 2500,
575
+ "discounted_price": 2250,
576
+ "discount_total": 500
577
+ }
578
+ ]
579
+ }
580
+ ```
581
+
582
+ ### Example
583
+
584
+ ```bash
585
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/cancel" \
586
+ -u "username:app_password" \
587
+ -H "Content-Type: application/json" \
588
+ -d '{
589
+ "coupon_code": "SAVE10",
590
+ "id": 15,
591
+ "order_uuid": "abc123-def456",
592
+ "order_items": [
593
+ {
594
+ "post_id": 42,
595
+ "quantity": 2,
596
+ "price": 2500,
597
+ "unit_price": 2500,
598
+ "item_total": 5000,
599
+ "line_total": 5000
600
+ }
601
+ ],
602
+ "applied_coupons": [2]
603
+ }'
604
+ ```
605
+
606
+ ---
607
+
608
+ ## Re-apply Coupons
609
+
610
+ `POST /fluent-cart/v2/coupons/re-apply`
611
+
612
+ Recalculate all previously applied coupons against current order items.
613
+
614
+ **Permission:** `orders/create` or `orders/manage`
615
+
616
+ ### Parameters
617
+
618
+ | Parameter | Type | Location | Required | Description |
619
+ |-----------|------|----------|----------|-------------|
620
+ | `order_uuid` | string | body | No | UUID of existing order |
621
+ | `order_items` | array | body | No | Array of current order line item objects |
622
+ | `applied_coupons` | array | body | No | Array of coupon IDs to include |
623
+
624
+ ### Response
625
+
626
+ ```json
627
+ {
628
+ "applied_coupons": {
629
+ "SAVE10": {
630
+ "id": 1,
631
+ "title": "10% Off",
632
+ "code": "SAVE10",
633
+ "type": "percentage",
634
+ "amount": 10,
635
+ "discount_amount": 450,
636
+ "stackable": "yes",
637
+ "priority": 1
638
+ }
639
+ },
640
+ "calculated_items": [
641
+ {
642
+ "post_id": 42,
643
+ "quantity": 1,
644
+ "price": 2500,
645
+ "discounted_price": 2250,
646
+ "discount_total": 250
647
+ }
648
+ ]
649
+ }
650
+ ```
651
+
652
+ ### Example
653
+
654
+ ```bash
655
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/re-apply" \
656
+ -u "username:app_password" \
657
+ -H "Content-Type: application/json" \
658
+ -d '{
659
+ "order_uuid": "abc123-def456",
660
+ "order_items": [
661
+ {
662
+ "post_id": 42,
663
+ "quantity": 1,
664
+ "price": 2500,
665
+ "unit_price": 2500,
666
+ "item_total": 2500,
667
+ "line_total": 2500
668
+ }
669
+ ],
670
+ "applied_coupons": [1]
671
+ }'
672
+ ```
673
+
674
+ ---
675
+
676
+ ## Check Product Eligibility
677
+
678
+ `POST /fluent-cart/v2/coupons/checkProductEligibility`
679
+
680
+ Check whether a product is eligible for a set of applied coupons.
681
+
682
+ **Permission:** `orders/create` or `orders/manage`
683
+
684
+ ### Parameters
685
+
686
+ | Parameter | Type | Location | Required | Description |
687
+ |-----------|------|----------|----------|-------------|
688
+ | `productId` | integer | body | Yes | Product (post) ID to check |
689
+ | `appliedCoupons` | array | body | No | Array of coupon codes currently applied |
690
+ | `origin` | string | body | No | Context origin (e.g., `checkout`) |
691
+
692
+ ### Response
693
+
694
+ Eligible:
695
+ ```json
696
+ {
697
+ "isApplicable": true
698
+ }
699
+ ```
700
+
701
+ Not Eligible:
702
+ ```json
703
+ {
704
+ "isApplicable": false,
705
+ "message": "Product A conflicts with SAVE10 coupon. Remove the coupon first."
706
+ }
707
+ ```
708
+
709
+ ### Example
710
+
711
+ ```bash
712
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/checkProductEligibility" \
713
+ -u "username:app_password" \
714
+ -H "Content-Type: application/json" \
715
+ -d '{
716
+ "productId": 42,
717
+ "appliedCoupons": ["SAVE10", "WELCOME5"],
718
+ "origin": "admin_order"
719
+ }'
720
+ ```
721
+
722
+ ---
723
+
724
+ ## Store Coupon Settings
725
+
726
+ `POST /fluent-cart/v2/coupons/storeCouponSettings`
727
+
728
+ Update the global coupon settings.
729
+
730
+ **Permission:** `coupons/manage`
731
+
732
+ ### Parameters
733
+
734
+ | Parameter | Type | Location | Required | Description |
735
+ |-----------|------|----------|----------|-------------|
736
+ | `show_on_checkout` | boolean | body | No | Whether to show coupon input on checkout page |
737
+
738
+ ### Response
739
+
740
+ ```json
741
+ true
742
+ ```
743
+
744
+ ### Example
745
+
746
+ ```bash
747
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/coupons/storeCouponSettings" \
748
+ -u "username:app_password" \
749
+ -H "Content-Type: application/json" \
750
+ -d '{
751
+ "show_on_checkout": true
752
+ }'
753
+ ```
754
+
755
+ ---
756
+
757
+ ## Coupon Model & Database Reference
758
+
759
+ ### Coupon Types
760
+
761
+ | Type | Description | Amount Handling |
762
+ |------|-------------|-----------------|
763
+ | `fixed` | Fixed amount discount | Stored in cents (e.g., 1000 = $10.00) |
764
+ | `percentage` | Percentage discount | Stored as percentage (e.g., 10 = 10%). Max: 100 |
765
+ | `free_shipping` | Free shipping coupon | Amount is typically 0 |
766
+ | `buy_x_get_y` | Buy X Get Y promotion | Uses `conditions.buy_products` & `conditions.get_products` |
767
+
768
+ ### Database Table (`fct_coupons`)
769
+
770
+ | Column | Type | Description |
771
+ |--------|------|-------------|
772
+ | `id` | BIGINT (PK) | Auto-increment ID |
773
+ | `parent` | BIGINT | Parent coupon ID |
774
+ | `title` | VARCHAR(200) | Display name |
775
+ | `code` | VARCHAR(50) | Unique coupon code |
776
+ | `status` | VARCHAR(20) | Coupon status (`active`, `expired`, `disabled`, `scheduled`) |
777
+ | `type` | VARCHAR(20) | Discount type |
778
+ | `conditions` | TEXT (JSON) | JSON-encoded conditions object |
779
+ | `amount` | BIGINT | Discount amount (cents or percentage) |
780
+ | `stackable` | VARCHAR(10) | Stackability flag (`yes`/`no`) |
781
+ | `priority` | INT | Sort priority |
782
+ | `use_count` | INT | Usage count |
783
+ | `notes` | TEXT | Internal notes |
784
+ | `show_on_checkout` | VARCHAR(10) | Display on checkout flag |
785
+ | `start_date` | DATETIME | Start date (GMT) |
786
+ | `end_date` | DATETIME | End date (GMT) |
787
+ | `created_at` | DATETIME | Creation timestamp |
788
+ | `updated_at` | DATETIME | Last update timestamp |
789
+
790
+ ### Hooks
791
+
792
+ - `fluent_cart/coupon_created` — Action fired after coupon creation.
793
+ - `fluent_cart/coupon_updated` — Action fired after coupon update.
794
+ - `fluent_cart/coupons_list_filter_query` — Filter to modify coupon list query.