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.
- package/.gitattributes +2 -0
- package/CLAUDE.md +22 -0
- package/CONTRIBUTING.md +73 -0
- package/LICENSE +21 -0
- package/README.md +127 -0
- package/SKILL.md +127 -0
- package/bin/index.js +281 -0
- package/copy-skills.js +43 -0
- package/package.json +38 -0
- package/skills/fluentcart-developer/SKILL.md +172 -0
- package/skills/fluentcart-developer/examples/README.md +25 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
- package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
- package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
- package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
- package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
- package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
- package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
- package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
- package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
- package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
- package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
- package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
- package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
- package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
- package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
- package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
- package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
- package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
- package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
- package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
- package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
- package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
- package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
- package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
- package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
- package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
- package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
- package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
- package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
- package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
- package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
- package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
- package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
- package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
- package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
- package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
- package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
- package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
- package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
- package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
- package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
- package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
- package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
- package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
- package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
- package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
- package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
- package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
- package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
- package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
- package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
- package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
- package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
- package/skills/fluentcart-developer/scripts/cli.js +1 -0
- package/skills.sh.json +13 -0
|
@@ -0,0 +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.
|