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,800 @@
1
+ # Shipping API
2
+
3
+ Configure shipping zones, manage shipping methods within zones, and organize products with shipping classes in FluentCart.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
6
+ **Policy:** `StoreSensitivePolicy`
7
+ **Permission:** `store/sensitive`
8
+
9
+ > All monetary values (shipping costs, amounts) are in **cents** (e.g., `$10.00` = `1000`).
10
+
11
+ ---
12
+
13
+ ## Endpoints Overview
14
+
15
+ | Group | Method | Endpoint | Request Class | Description |
16
+ |-------|--------|----------|---------------|-------------|
17
+ | **Shipping Zones** | GET | `/shipping/zones` | — | List Shipping Zones (paginated) |
18
+ | | POST | `/shipping/zones` | `ShippingZoneRequest` | Create Shipping Zone |
19
+ | | GET | `/shipping/zones/{id}` | — | Get Single Shipping Zone Details |
20
+ | | PUT | `/shipping/zones/{id}` | `ShippingZoneRequest` | Update Shipping Zone |
21
+ | | DELETE | `/shipping/zones/{id}` | — | Delete Shipping Zone (cascading) |
22
+ | | POST | `/shipping/zones/update-order` | — | Reorder Shipping Zones |
23
+ | | GET | `/shipping/zone/states` | — | Get State Options & Locale Config |
24
+ | **Shipping Methods** | POST | `/shipping/methods` | `ShippingMethodRequest` | Create Shipping Method |
25
+ | | PUT | `/shipping/methods` | `ShippingMethodRequest` | Update Shipping Method |
26
+ | | DELETE | `/shipping/methods/{method_id}` | — | Delete Shipping Method |
27
+ | **Shipping Classes** | GET | `/shipping/classes` | — | List Shipping Classes (paginated) |
28
+ | | POST | `/shipping/classes` | `ShippingClassRequest` | Create Shipping Class |
29
+ | | GET | `/shipping/classes/{id}` | — | Get Single Shipping Class |
30
+ | | PUT | `/shipping/classes/{id}` | `ShippingClassRequest` | Update Shipping Class |
31
+ | | DELETE | `/shipping/classes/{id}` | — | Delete Shipping Class |
32
+
33
+ ---
34
+
35
+ ## Shipping Zones
36
+
37
+ Shipping zones define geographic regions (countries) to which specific shipping methods apply. Each zone contains a country code (or `all` for worldwide) and can hold multiple shipping methods.
38
+
39
+ **Prefix:** `/fluent-cart/v2/shipping/zones` | **Policy:** `StoreSensitivePolicy` (`store/sensitive`)
40
+
41
+ ### List Shipping Zones
42
+
43
+ `GET /fluent-cart/v2/shipping/zones`
44
+
45
+ Retrieve a paginated list of shipping zones with filtering and sorting capabilities.
46
+
47
+ #### Parameters
48
+
49
+ | Parameter | Type | Location | Required | Description |
50
+ |-----------|------|----------|----------|-------------|
51
+ | `search` | string | query | No | Search zones by name |
52
+ | `per_page` | integer | query | No | Number of results per page (default: 10, max: 200) |
53
+ | `page` | integer | query | No | Page number for pagination |
54
+ | `sort_by` | string | query | No | Column to sort by (default: `order`) |
55
+ | `sort_type` | string | query | No | Sort direction: `asc` or `desc` (default: `asc`) |
56
+ | `filter_type` | string | query | No | `simple` or `advanced` |
57
+
58
+ #### Response
59
+
60
+ ```json
61
+ {
62
+ "shipping_zones": {
63
+ "total": 3,
64
+ "per_page": 10,
65
+ "current_page": 1,
66
+ "last_page": 1,
67
+ "data": [
68
+ {
69
+ "id": 1,
70
+ "name": "Domestic",
71
+ "region": "US",
72
+ "order": 0,
73
+ "formatted_region": "United States",
74
+ "created_at": "2025-01-15 12:00:00",
75
+ "updated_at": "2025-01-15 12:00:00"
76
+ },
77
+ {
78
+ "id": 2,
79
+ "name": "Rest of World",
80
+ "region": "all",
81
+ "order": 1,
82
+ "formatted_region": "Whole World",
83
+ "created_at": "2025-01-16 10:00:00",
84
+ "updated_at": "2025-01-16 10:00:00"
85
+ }
86
+ ]
87
+ }
88
+ }
89
+ ```
90
+
91
+ #### Example
92
+
93
+ ```bash
94
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/shipping/zones?per_page=20&search=domestic" \
95
+ -u "username:app_password"
96
+ ```
97
+
98
+ ---
99
+
100
+ ### Create Shipping Zone
101
+
102
+ `POST /fluent-cart/v2/shipping/zones`
103
+
104
+ Create a new shipping zone.
105
+
106
+ **Request Class:** `ShippingZoneRequest`
107
+
108
+ #### Parameters
109
+
110
+ | Parameter | Type | Location | Required | Description |
111
+ |-----------|------|----------|----------|-------------|
112
+ | `name` | string | body | Yes | Zone name (max 192 characters) |
113
+ | `region` | string | body | No | ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`) or `all` for worldwide. Only one `all` zone is allowed. |
114
+ | `order` | integer | body | No | Sort order for display priority |
115
+
116
+ #### Response
117
+
118
+ ```json
119
+ {
120
+ "shipping_zone": {
121
+ "id": 3,
122
+ "name": "Europe",
123
+ "region": "DE",
124
+ "order": 2,
125
+ "formatted_region": "Germany",
126
+ "created_at": "2025-02-01 08:00:00",
127
+ "updated_at": "2025-02-01 08:00:00"
128
+ },
129
+ "message": "Shipping zone has been created successfully"
130
+ }
131
+ ```
132
+
133
+ #### Example
134
+
135
+ ```bash
136
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/shipping/zones" \
137
+ -u "username:app_password" \
138
+ -H "Content-Type: application/json" \
139
+ -d '{
140
+ "name": "Europe",
141
+ "region": "DE",
142
+ "order": 2
143
+ }'
144
+ ```
145
+
146
+ ---
147
+
148
+ ### Get Shipping Zone
149
+
150
+ `GET /fluent-cart/v2/shipping/zones/{id}`
151
+
152
+ Retrieve a single shipping zone by ID, including its associated shipping methods.
153
+
154
+ #### Parameters
155
+
156
+ | Parameter | Type | Location | Required | Description |
157
+ |-----------|------|----------|----------|-------------|
158
+ | `id` | integer | path | Yes | The shipping zone ID |
159
+
160
+ #### Response
161
+
162
+ ```json
163
+ {
164
+ "shipping_zone": {
165
+ "id": 1,
166
+ "name": "Domestic",
167
+ "region": "US",
168
+ "order": 0,
169
+ "formatted_region": "United States",
170
+ "created_at": "2025-01-15 12:00:00",
171
+ "updated_at": "2025-01-15 12:00:00",
172
+ "methods": [
173
+ {
174
+ "id": 10,
175
+ "zone_id": 1,
176
+ "title": "Standard Shipping",
177
+ "type": "flat_rate",
178
+ "amount": 500,
179
+ "is_enabled": true,
180
+ "states": [],
181
+ "settings": {},
182
+ "meta": {},
183
+ "order": 0,
184
+ "formatted_states": [],
185
+ "created_at": "2025-01-15 12:30:00",
186
+ "updated_at": "2025-01-15 12:30:00"
187
+ }
188
+ ]
189
+ }
190
+ }
191
+ ```
192
+
193
+ #### Example
194
+
195
+ ```bash
196
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/shipping/zones/1" \
197
+ -u "username:app_password"
198
+ ```
199
+
200
+ ---
201
+
202
+ ### Update Shipping Zone
203
+
204
+ `PUT /fluent-cart/v2/shipping/zones/{id}`
205
+
206
+ Update an existing shipping zone.
207
+
208
+ **Request Class:** `ShippingZoneRequest`
209
+
210
+ #### Parameters
211
+
212
+ | Parameter | Type | Location | Required | Description |
213
+ |-----------|------|----------|----------|-------------|
214
+ | `id` | integer | path | Yes | The shipping zone ID |
215
+ | `name` | string | body | Yes | Zone name (max 192 characters) |
216
+ | `region` | string | body | No | ISO 3166-1 alpha-2 country code or `all`. Only one `all` zone is allowed. |
217
+ | `order` | integer | body | No | Sort order for display priority |
218
+
219
+ > **Region Change Side Effect:** When the `region` value changes, all shipping methods in the zone have their `states` arrays reset to `[]`. This is because states/provinces are country-specific.
220
+
221
+ #### Response
222
+
223
+ ```json
224
+ {
225
+ "shipping_zone": {
226
+ "id": 1,
227
+ "name": "United States",
228
+ "region": "US",
229
+ "order": 0,
230
+ "formatted_region": "United States",
231
+ "created_at": "2025-01-15 12:00:00",
232
+ "updated_at": "2025-02-01 09:00:00"
233
+ },
234
+ "message": "Shipping zone has been updated successfully"
235
+ }
236
+ ```
237
+
238
+ #### Example
239
+
240
+ ```bash
241
+ curl -X PUT "https://example.com/wp-json/fluent-cart/v2/shipping/zones/1" \
242
+ -u "username:app_password" \
243
+ -H "Content-Type: application/json" \
244
+ -d '{
245
+ "name": "United States",
246
+ "region": "US",
247
+ "order": 0
248
+ }'
249
+ ```
250
+
251
+ ---
252
+
253
+ ### Delete Shipping Zone
254
+
255
+ `DELETE /fluent-cart/v2/shipping/zones/{id}`
256
+
257
+ Delete a shipping zone and all its associated shipping methods.
258
+
259
+ > **Cascading Delete:** Deleting a zone will also permanently delete all shipping methods associated with that zone.
260
+
261
+ #### Parameters
262
+
263
+ | Parameter | Type | Location | Required | Description |
264
+ |-----------|------|----------|----------|-------------|
265
+ | `id` | integer | path | Yes | The shipping zone ID |
266
+
267
+ #### Response
268
+
269
+ ```json
270
+ {
271
+ "message": "Shipping zone has been deleted successfully"
272
+ }
273
+ ```
274
+
275
+ #### Example
276
+
277
+ ```bash
278
+ curl -X DELETE "https://example.com/wp-json/fluent-cart/v2/shipping/zones/1" \
279
+ -u "username:app_password"
280
+ ```
281
+
282
+ ---
283
+
284
+ ### Update Zone Order
285
+
286
+ `POST /fluent-cart/v2/shipping/zones/update-order`
287
+
288
+ Reorder shipping zones by providing an array of zone IDs in the desired order. Each zone's `order` field is updated to match its index position.
289
+
290
+ #### Parameters
291
+
292
+ | Parameter | Type | Location | Required | Description |
293
+ |-----------|------|----------|----------|-------------|
294
+ | `zones` | array | body | Yes | Array of zone IDs in the desired display order |
295
+
296
+ #### Response
297
+
298
+ ```json
299
+ {
300
+ "message": "Shipping zones order has been updated"
301
+ }
302
+ ```
303
+
304
+ #### Error Response
305
+
306
+ ```json
307
+ {
308
+ "message": "Invalid data provided"
309
+ }
310
+ ```
311
+
312
+ #### Example
313
+
314
+ ```bash
315
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/shipping/zones/update-order" \
316
+ -u "username:app_password" \
317
+ -H "Content-Type: application/json" \
318
+ -d '{
319
+ "zones": [3, 1, 2]
320
+ }'
321
+ ```
322
+ *(In this example, zone `3` gets `order: 0`, zone `1` gets `order: 1`, and zone `2` gets `order: 2`.)*
323
+
324
+ ---
325
+
326
+ ### Get Zone States
327
+
328
+ `GET /fluent-cart/v2/shipping/zone/states`
329
+
330
+ Retrieve state/province options and address locale configuration for a given country. Useful for populating state selectors when configuring shipping methods within a zone.
331
+
332
+ #### Parameters
333
+
334
+ | Parameter | Type | Location | Required | Description |
335
+ |-----------|------|----------|----------|-------------|
336
+ | `country_code` | string | query | No | ISO 3166-1 alpha-2 country code (e.g., `US`, `CA`, `GB`) |
337
+
338
+ #### Response (with country code)
339
+
340
+ ```json
341
+ {
342
+ "data": {
343
+ "country_code": "US",
344
+ "states": {
345
+ "AL": "Alabama",
346
+ "AK": "Alaska",
347
+ "AZ": "Arizona",
348
+ "CA": "California",
349
+ "NY": "New York"
350
+ },
351
+ "address_locale": {
352
+ "state": {
353
+ "label": "State",
354
+ "required": true
355
+ },
356
+ "postcode": {
357
+ "label": "ZIP Code",
358
+ "required": true
359
+ }
360
+ }
361
+ }
362
+ }
363
+ ```
364
+
365
+ #### Response (empty / no states)
366
+
367
+ ```json
368
+ {
369
+ "data": {
370
+ "country_code": "",
371
+ "states": [],
372
+ "address_locale": []
373
+ }
374
+ }
375
+ ```
376
+
377
+ #### Example
378
+
379
+ ```bash
380
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/shipping/zone/states?country_code=US" \
381
+ -u "username:app_password"
382
+ ```
383
+
384
+ ---
385
+
386
+ ## Shipping Methods
387
+
388
+ Shipping methods define how items are shipped within a zone. Each method belongs to a zone and can be scoped to specific states/provinces within that zone's country.
389
+
390
+ **Prefix:** `/fluent-cart/v2/shipping/methods` | **Policy:** `StoreSensitivePolicy` (`store/sensitive`)
391
+
392
+ ### Create Shipping Method
393
+
394
+ `POST /fluent-cart/v2/shipping/methods`
395
+
396
+ Create a new shipping method within a shipping zone.
397
+
398
+ **Request Class:** `ShippingMethodRequest`
399
+
400
+ #### Parameters
401
+
402
+ | Parameter | Type | Location | Required | Description |
403
+ |-----------|------|----------|----------|-------------|
404
+ | `zone_id` | integer | body | Yes | ID of the parent shipping zone |
405
+ | `title` | string | body | Yes | Method display title (max 192 characters) |
406
+ | `type` | string | body | Yes | Shipping method type (max 192 characters), e.g., `flat_rate`, `free_shipping`, `local_pickup` |
407
+ | `amount` | string | body | No | Shipping cost in cents (e.g., `500` for `$5.00`) |
408
+ | `is_enabled` | integer | body | No | Enable/disable the method: `1` (enabled) or `0` (disabled). Default: `1` |
409
+ | `states` | array | body | No | Array of state/province codes to restrict this method to (e.g. `["CA", "NY"]`). Empty array means all states. |
410
+ | `settings` | object | body | No | Additional settings object |
411
+ | `settings.configure_rate` | string | body | No | Rate configuration type (e.g., `per_order`) |
412
+ | `settings.class_aggregation` | string | body | No | How shipping classes are aggregated (e.g., `per_class`) |
413
+ | `meta` | object | body | No | Additional metadata key-value pairs (string values only) |
414
+
415
+ #### Response
416
+
417
+ ```json
418
+ {
419
+ "message": "Shipping method has been created successfully"
420
+ }
421
+ ```
422
+
423
+ #### Example
424
+
425
+ ```bash
426
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/shipping/methods" \
427
+ -u "username:app_password" \
428
+ -H "Content-Type: application/json" \
429
+ -d '{
430
+ "zone_id": 1,
431
+ "title": "Standard Shipping",
432
+ "type": "flat_rate",
433
+ "amount": "500",
434
+ "is_enabled": 1,
435
+ "states": ["CA", "NY"],
436
+ "settings": {
437
+ "configure_rate": "per_order",
438
+ "class_aggregation": "per_class"
439
+ }
440
+ }'
441
+ ```
442
+
443
+ ---
444
+
445
+ ### Update Shipping Method
446
+
447
+ `PUT /fluent-cart/v2/shipping/methods`
448
+
449
+ Update an existing shipping method. The method ID is passed in the request body.
450
+
451
+ **Request Class:** `ShippingMethodRequest`
452
+
453
+ #### Parameters
454
+
455
+ | Parameter | Type | Location | Required | Description |
456
+ |-----------|------|----------|----------|-------------|
457
+ | `method_id` | integer | body | Yes | ID of the shipping method to update |
458
+ | `zone_id` | integer | body | Yes | ID of the parent shipping zone |
459
+ | `title` | string | body | Yes | Method display title (max 192 characters) |
460
+ | `type` | string | body | Yes | Shipping method type (max 192 characters), e.g., `flat_rate`, `free_shipping`, `local_pickup` |
461
+ | `amount` | string | body | No | Shipping cost in cents (e.g., `500` for `$5.00`) |
462
+ | `is_enabled` | integer | body | No | Enable/disable the method: `1` (enabled) or `0` (disabled) |
463
+ | `states` | array | body | No | Array of state/province codes to restrict this method to. Empty array means all states. |
464
+ | `settings` | object | body | No | Additional settings for the method |
465
+ | `settings.configure_rate` | string | body | No | Rate configuration type |
466
+ | `settings.class_aggregation` | string | body | No | How shipping classes are aggregated |
467
+ | `meta` | object | body | No | Additional metadata key-value pairs (string values only) |
468
+
469
+ #### Response
470
+
471
+ ```json
472
+ {
473
+ "message": "Shipping method has been updated successfully"
474
+ }
475
+ ```
476
+
477
+ #### Example
478
+
479
+ ```bash
480
+ curl -X PUT "https://example.com/wp-json/fluent-cart/v2/shipping/methods" \
481
+ -u "username:app_password" \
482
+ -H "Content-Type: application/json" \
483
+ -d '{
484
+ "method_id": 10,
485
+ "zone_id": 1,
486
+ "title": "Express Shipping",
487
+ "type": "flat_rate",
488
+ "amount": "1200",
489
+ "is_enabled": 1,
490
+ "states": []
491
+ }'
492
+ ```
493
+
494
+ ---
495
+
496
+ ### Delete Shipping Method
497
+
498
+ `DELETE /fluent-cart/v2/shipping/methods/{method_id}`
499
+
500
+ Delete a shipping method by ID.
501
+
502
+ #### Parameters
503
+
504
+ | Parameter | Type | Location | Required | Description |
505
+ |-----------|------|----------|----------|-------------|
506
+ | `method_id` | integer | path | Yes | The shipping method ID |
507
+
508
+ #### Response
509
+
510
+ ```json
511
+ {
512
+ "message": "Shipping method has been deleted successfully"
513
+ }
514
+ ```
515
+
516
+ #### Example
517
+
518
+ ```bash
519
+ curl -X DELETE "https://example.com/wp-json/fluent-cart/v2/shipping/methods/10" \
520
+ -u "username:app_password"
521
+ ```
522
+
523
+ ---
524
+
525
+ ## Shipping Classes
526
+
527
+ Shipping classes allow you to group products with similar shipping requirements. Each class defines a cost (fixed or percentage) that can be applied per order or per item.
528
+
529
+ **Prefix:** `/fluent-cart/v2/shipping/classes` | **Policy:** `StoreSensitivePolicy` (`store/sensitive`)
530
+
531
+ ### List Shipping Classes
532
+
533
+ `GET /fluent-cart/v2/shipping/classes`
534
+
535
+ Retrieve a paginated list of shipping classes with filtering and sorting capabilities.
536
+
537
+ #### Parameters
538
+
539
+ | Parameter | Type | Location | Required | Description |
540
+ |-----------|------|----------|----------|-------------|
541
+ | `search` | string | query | No | Search classes by name |
542
+ | `per_page` | integer | query | No | Number of results per page (default: 10, max: 200) |
543
+ | `page` | integer | query | No | Page number for pagination |
544
+ | `sort_by` | string | query | No | Column to sort by (default: `id`) |
545
+ | `sort_type` | string | query | No | Sort direction: `asc` or `desc` (default: `desc`) |
546
+ | `filter_type` | string | query | No | `simple` or `advanced` |
547
+
548
+ #### Response
549
+
550
+ ```json
551
+ {
552
+ "shipping_classes": {
553
+ "total": 3,
554
+ "per_page": 10,
555
+ "current_page": 1,
556
+ "last_page": 1,
557
+ "data": [
558
+ {
559
+ "id": 1,
560
+ "name": "Heavy Items",
561
+ "cost": 15.00,
562
+ "type": "fixed",
563
+ "per_item": 1,
564
+ "created_at": "2025-01-20 09:00:00",
565
+ "updated_at": "2025-01-20 09:00:00"
566
+ },
567
+ {
568
+ "id": 2,
569
+ "name": "Fragile Items",
570
+ "cost": 10.00,
571
+ "type": "percentage",
572
+ "per_item": 0,
573
+ "created_at": "2025-01-21 10:00:00",
574
+ "updated_at": "2025-01-21 10:00:00"
575
+ }
576
+ ]
577
+ }
578
+ }
579
+ ```
580
+
581
+ #### Example
582
+
583
+ ```bash
584
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/shipping/classes?search=heavy&per_page=20" \
585
+ -u "username:app_password"
586
+ ```
587
+
588
+ ---
589
+
590
+ ### Create Shipping Class
591
+
592
+ `POST /fluent-cart/v2/shipping/classes`
593
+
594
+ Create a new shipping class.
595
+
596
+ **Request Class:** `ShippingClassRequest`
597
+
598
+ #### Parameters
599
+
600
+ | Parameter | Type | Location | Required | Description |
601
+ |-----------|------|----------|----------|-------------|
602
+ | `name` | string | body | Yes | Class name (max 192 characters) |
603
+ | `cost` | numeric | body | Yes | Cost value (minimum: 0). Flat amount for fixed type, percentage value for percentage type |
604
+ | `type` | string | body | Yes | Cost type: `fixed` or `percentage` |
605
+ | `per_item` | integer | body | No | Apply cost per item (`1`) or per order (`0`). Default: `0` |
606
+
607
+ #### Response
608
+
609
+ ```json
610
+ {
611
+ "shipping_class": {
612
+ "id": 3,
613
+ "name": "Oversized Items",
614
+ "cost": 25.00,
615
+ "type": "fixed",
616
+ "per_item": 1,
617
+ "created_at": "2025-02-01 11:00:00",
618
+ "updated_at": "2025-02-01 11:00:00"
619
+ },
620
+ "message": "Shipping class has been created successfully"
621
+ }
622
+ ```
623
+
624
+ #### Example
625
+
626
+ ```bash
627
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/shipping/classes" \
628
+ -u "username:app_password" \
629
+ -H "Content-Type: application/json" \
630
+ -d '{
631
+ "name": "Oversized Items",
632
+ "cost": 25.00,
633
+ "type": "fixed",
634
+ "per_item": 1
635
+ }'
636
+ ```
637
+
638
+ ---
639
+
640
+ ### Get Shipping Class
641
+
642
+ `GET /fluent-cart/v2/shipping/classes/{id}`
643
+
644
+ Retrieve a single shipping class by ID.
645
+
646
+ #### Parameters
647
+
648
+ | Parameter | Type | Location | Required | Description |
649
+ |-----------|------|----------|----------|-------------|
650
+ | `id` | integer | path | Yes | The shipping class ID |
651
+
652
+ #### Response
653
+
654
+ ```json
655
+ {
656
+ "shipping_class": {
657
+ "id": 1,
658
+ "name": "Heavy Items",
659
+ "cost": 15.00,
660
+ "type": "fixed",
661
+ "per_item": 1,
662
+ "created_at": "2025-01-20 09:00:00",
663
+ "updated_at": "2025-01-20 09:00:00"
664
+ }
665
+ }
666
+ ```
667
+
668
+ #### Example
669
+
670
+ ```bash
671
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/shipping/classes/1" \
672
+ -u "username:app_password"
673
+ ```
674
+
675
+ ---
676
+
677
+ ### Update Shipping Class
678
+
679
+ `PUT /fluent-cart/v2/shipping/classes/{id}`
680
+
681
+ Update an existing shipping class.
682
+
683
+ **Request Class:** `ShippingClassRequest`
684
+
685
+ #### Parameters
686
+
687
+ | Parameter | Type | Location | Required | Description |
688
+ |-----------|------|----------|----------|-------------|
689
+ | `id` | integer | path | Yes | The shipping class ID |
690
+ | `name` | string | body | Yes | Class name (max 192 characters) |
691
+ | `cost` | numeric | body | Yes | Cost value (minimum: 0) |
692
+ | `type` | string | body | Yes | Cost type: `fixed` or `percentage` |
693
+ | `per_item` | integer | body | No | Apply cost per item (`1`) or per order (`0`). Default: `0` |
694
+
695
+ #### Response
696
+
697
+ ```json
698
+ {
699
+ "shipping_class": {
700
+ "id": 1,
701
+ "name": "Heavy Items",
702
+ "cost": 20.00,
703
+ "type": "fixed",
704
+ "per_item": 1,
705
+ "created_at": "2025-01-20 09:00:00",
706
+ "updated_at": "2025-02-05 14:00:00"
707
+ },
708
+ "message": "Shipping class has been updated successfully"
709
+ }
710
+ ```
711
+
712
+ #### Example
713
+
714
+ ```bash
715
+ curl -X PUT "https://example.com/wp-json/fluent-cart/v2/shipping/classes/1" \
716
+ -u "username:app_password" \
717
+ -H "Content-Type: application/json" \
718
+ -d '{
719
+ "name": "Heavy Items",
720
+ "cost": 20.00,
721
+ "type": "fixed",
722
+ "per_item": 1
723
+ }'
724
+ ```
725
+
726
+ ---
727
+
728
+ ### Delete Shipping Class
729
+
730
+ `DELETE /fluent-cart/v2/shipping/classes/{id}`
731
+
732
+ Delete a shipping class by ID.
733
+
734
+ #### Parameters
735
+
736
+ | Parameter | Type | Location | Required | Description |
737
+ |-----------|------|----------|----------|-------------|
738
+ | `id` | integer | path | Yes | The shipping class ID |
739
+
740
+ #### Response
741
+
742
+ ```json
743
+ {
744
+ "message": "Shipping class has been deleted successfully"
745
+ }
746
+ ```
747
+
748
+ #### Example
749
+
750
+ ```bash
751
+ curl -X DELETE "https://example.com/wp-json/fluent-cart/v2/shipping/classes/1" \
752
+ -u "username:app_password"
753
+ ```
754
+
755
+ ---
756
+
757
+ ## Data Models
758
+
759
+ ### Shipping Zone Object
760
+
761
+ | Field | Type | Description |
762
+ |-------|------|-------------|
763
+ | `id` | integer | Unique zone identifier |
764
+ | `name` | string | Zone display name |
765
+ | `region` | string | ISO 3166-1 alpha-2 country code or `all` for worldwide |
766
+ | `order` | integer | Sort order for display priority |
767
+ | `formatted_region` | string | Human-readable region name (computed) |
768
+ | `methods` | array | Associated shipping methods (included when fetching single zone) |
769
+ | `created_at` | string | Creation timestamp (UTC) |
770
+ | `updated_at` | string | Last update timestamp (UTC) |
771
+
772
+ ### Shipping Method Object
773
+
774
+ | Field | Type | Description |
775
+ |-------|------|-------------|
776
+ | `id` | integer | Unique method identifier |
777
+ | `zone_id` | integer | Parent shipping zone ID |
778
+ | `title` | string | Method display title |
779
+ | `type` | string | Method type (e.g., `flat_rate`, `free_shipping`, `local_pickup`) |
780
+ | `amount` | integer | Shipping cost in cents |
781
+ | `is_enabled` | boolean | Whether the method is active |
782
+ | `states` | array | State/province codes this method applies to (empty array = all states) |
783
+ | `settings` | object | Additional configuration settings (`configure_rate`, `class_aggregation`) |
784
+ | `meta` | object | Additional metadata key-value pairs |
785
+ | `order` | integer | Sort order within the zone |
786
+ | `formatted_states` | array | Human-readable state names (computed) |
787
+ | `created_at` | string | Creation timestamp (UTC) |
788
+ | `updated_at` | string | Last update timestamp (UTC) |
789
+
790
+ ### Shipping Class Object
791
+
792
+ | Field | Type | Description |
793
+ |-------|------|-------------|
794
+ | `id` | integer | Unique class identifier |
795
+ | `name` | string | Class display name |
796
+ | `cost` | float | Cost value (flat amount or percentage, depending on type) |
797
+ | `type` | string | Cost type: `fixed` or `percentage` |
798
+ | `per_item` | integer | `1` = cost applied per item, `0` = cost applied per order |
799
+ | `created_at` | string | Creation timestamp (UTC) |
800
+ | `updated_at` | string | Last update timestamp (UTC) |