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,286 @@
|
|
|
1
|
+
# Checkout API
|
|
2
|
+
|
|
3
|
+
Public storefront checkout endpoints for submitting orders, calculating cart summaries, loading payment gateway UI configurations, querying shipping method availability, and authenticating users.
|
|
4
|
+
|
|
5
|
+
**Base URLs:**
|
|
6
|
+
- Checkout: `https://your-site.com/wp-json/fluent-cart/v2/checkout`
|
|
7
|
+
- User Login: `https://your-site.com/wp-json/fluent-cart/v2/user/login`
|
|
8
|
+
|
|
9
|
+
**Policy:** `PublicPolicy` (No authentication required for most endpoints)
|
|
10
|
+
|
|
11
|
+
> All monetary values (shipping charges, unformatted totals) are in **cents** (`$10.00` = `1000`).
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Endpoints Overview
|
|
16
|
+
|
|
17
|
+
| Group | Method | Endpoint | Auth / Headers | Description |
|
|
18
|
+
|-------|--------|----------|----------------|-------------|
|
|
19
|
+
| **Checkout** | POST | `/checkout/place-order` | Optional | Submit order, validate cart, & initiate payment (Rate limit: 5 req/60s) |
|
|
20
|
+
| | GET | `/checkout/get-order-info` | Optional | Get gateway-specific payment UI init config (Stripe Elements, PayPal) |
|
|
21
|
+
| | GET | `/checkout/get-checkout-summary-view` | Session/Cookie | Retrieve cart HTML view & totals for selected shipping method |
|
|
22
|
+
| | GET | `/checkout/get-available-shipping-methods` | Public | List shipping methods for timezone or country/state |
|
|
23
|
+
| | GET | `/checkout/get-shipping-methods-list-view` | Public | Get server-rendered HTML list of shipping methods |
|
|
24
|
+
| | GET | `/checkout/get-country-info` | Public | Get country states & localized address field rules |
|
|
25
|
+
| **Authentication** | POST | `/user/login` | `X-WP-Nonce` Header | Authenticate user during checkout & set WP auth cookie |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Checkout Endpoints
|
|
30
|
+
|
|
31
|
+
### 1. Place Order
|
|
32
|
+
|
|
33
|
+
`POST /fluent-cart/v2/checkout/place-order`
|
|
34
|
+
|
|
35
|
+
Validates cart, registers/matches customer, creates draft order, and dispatches to selected payment gateway.
|
|
36
|
+
|
|
37
|
+
> **Rate Limit:** 5 requests per 60 seconds per IP/User.
|
|
38
|
+
|
|
39
|
+
#### Body Parameters
|
|
40
|
+
|
|
41
|
+
| Parameter | Type | Required | Description |
|
|
42
|
+
|-----------|------|----------|-------------|
|
|
43
|
+
| `billing_email` | string | Yes | Customer email address (auto-populated for logged-in users) |
|
|
44
|
+
| `billing_full_name` | string | Conditional | Full name (required if store uses full name mode) |
|
|
45
|
+
| `billing_first_name` | string | Conditional | First name (required if store uses separate name mode) |
|
|
46
|
+
| `billing_last_name` | string | Conditional | Last name (required if separate name mode & required field) |
|
|
47
|
+
| `billing_country` | string | Conditional | ISO country code (e.g. `US`, `GB`). Defaults to store country |
|
|
48
|
+
| `billing_address_1` | string | Conditional | Street address line 1 |
|
|
49
|
+
| `billing_address_2` | string | No | Street address line 2 (apt, suite, unit) |
|
|
50
|
+
| `billing_city` | string | Conditional | City name |
|
|
51
|
+
| `billing_state` | string | Conditional | State/province code (required if country has states) |
|
|
52
|
+
| `billing_postcode` | string | Conditional | Postal/ZIP code |
|
|
53
|
+
| `billing_phone` | string | No | Customer phone number |
|
|
54
|
+
| `billing_tax_id` | string | No | Tax ID / VAT registration number |
|
|
55
|
+
| `billing_address_id` | integer | No | Saved customer billing address ID |
|
|
56
|
+
| `ship_to_different` | string | No | `yes` to specify separate shipping address. Default: `no` |
|
|
57
|
+
| `shipping_full_name` | string | Conditional | Shipping recipient name (required when `ship_to_different` is `yes`) |
|
|
58
|
+
| `shipping_country` | string | Conditional | Shipping country code (required when `ship_to_different` is `yes`) |
|
|
59
|
+
| `shipping_address_1` | string | Conditional | Shipping street address |
|
|
60
|
+
| `shipping_address_2` | string | No | Shipping address line 2 |
|
|
61
|
+
| `shipping_city` | string | Conditional | Shipping city |
|
|
62
|
+
| `shipping_state` | string | Conditional | Shipping state/province code |
|
|
63
|
+
| `shipping_postcode` | string | Conditional | Shipping postal code |
|
|
64
|
+
| `shipping_phone` | string | No | Shipping phone number |
|
|
65
|
+
| `shipping_address_id` | integer | No | Saved customer shipping address ID |
|
|
66
|
+
| `fc_selected_shipping_method` | integer | Conditional | Shipping method ID (required for physical items) |
|
|
67
|
+
| `payment_method` | string | Yes | Payment gateway slug (e.g., `stripe`, `paypal`, `cod`, `square`) |
|
|
68
|
+
| `order_notes` | string | No | Customer order notes (max 200 chars) |
|
|
69
|
+
| `agree_terms` | string | Conditional | Terms agreement flag (required if store setting enabled) |
|
|
70
|
+
| `allow_create_account` | string | No | `yes` to register WP user account (when store mode is `user_choice`) |
|
|
71
|
+
| `user_tz` | string | No | Customer IANA timezone string (default: `UTC`) |
|
|
72
|
+
|
|
73
|
+
#### Responses
|
|
74
|
+
|
|
75
|
+
##### Redirect-Based Gateways (PayPal, Hosted Stripe)
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"status": "success",
|
|
80
|
+
"redirect_url": "https://checkout.stripe.com/pay/cs_...",
|
|
81
|
+
"message": "Order placed successfully"
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
##### On-Site Gateways (Stripe Elements)
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"status": "success",
|
|
90
|
+
"payment_args": {
|
|
91
|
+
"client_secret": "pi_..._secret_...",
|
|
92
|
+
"checkout_mode": "onsite"
|
|
93
|
+
},
|
|
94
|
+
"order_id": 42,
|
|
95
|
+
"message": "Order placed successfully"
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
##### Free / COD Orders
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"status": "success",
|
|
104
|
+
"redirect_url": "https://your-site.com/checkout/order-received/?order=abc123",
|
|
105
|
+
"message": "Order placed successfully"
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
#### Example
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
curl -X POST "https://example.com/wp-json/fluent-cart/v2/checkout/place-order" \
|
|
113
|
+
-H "Content-Type: application/json" \
|
|
114
|
+
-H "X-WP-Nonce: your_nonce_here" \
|
|
115
|
+
-d '{
|
|
116
|
+
"billing_email": "john@example.com",
|
|
117
|
+
"billing_full_name": "John Doe",
|
|
118
|
+
"billing_country": "US",
|
|
119
|
+
"billing_address_1": "123 Main St",
|
|
120
|
+
"billing_city": "New York",
|
|
121
|
+
"billing_state": "NY",
|
|
122
|
+
"billing_postcode": "10001",
|
|
123
|
+
"payment_method": "stripe",
|
|
124
|
+
"user_tz": "America/New_York"
|
|
125
|
+
}'
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
### 2. Get Order Info
|
|
131
|
+
|
|
132
|
+
`GET /fluent-cart/v2/checkout/get-order-info`
|
|
133
|
+
|
|
134
|
+
Retrieve payment-gateway-specific setup parameters for frontend payment form initialization.
|
|
135
|
+
|
|
136
|
+
#### Parameters
|
|
137
|
+
|
|
138
|
+
| Parameter | Type | Location | Required | Description |
|
|
139
|
+
|-----------|------|----------|----------|-------------|
|
|
140
|
+
| `method` | string | query | Yes | Gateway slug (e.g. `stripe`, `paypal`, `square`, `airwallex`) |
|
|
141
|
+
|
|
142
|
+
#### Response Example (Stripe On-Site)
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"status": "success",
|
|
147
|
+
"message": "Order info retrieved!",
|
|
148
|
+
"data": {
|
|
149
|
+
"client_secret": "seti_..._secret_...",
|
|
150
|
+
"publishable_key": "pk_live_..."
|
|
151
|
+
},
|
|
152
|
+
"payment_args": {
|
|
153
|
+
"checkout_mode": "onsite",
|
|
154
|
+
"appearance": { "theme": "stripe" }
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
### 3. Get Checkout Summary
|
|
162
|
+
|
|
163
|
+
`GET /fluent-cart/v2/checkout/get-checkout-summary-view`
|
|
164
|
+
|
|
165
|
+
Retrieve server-rendered HTML item summary and updated pricing totals when changing shipping methods or options.
|
|
166
|
+
|
|
167
|
+
#### Parameters
|
|
168
|
+
|
|
169
|
+
| Parameter | Type | Location | Required | Description |
|
|
170
|
+
|-----------|------|----------|----------|-------------|
|
|
171
|
+
| `shipping_method_id` | integer | query | No | ID of selected shipping method |
|
|
172
|
+
|
|
173
|
+
#### Response
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"items": {
|
|
178
|
+
"views": "<div class=\"fct-checkout-items\">...rendered HTML...</div>",
|
|
179
|
+
"subtotal": "$50.00",
|
|
180
|
+
"has_subscriptions": false,
|
|
181
|
+
"shipping_charge": 500,
|
|
182
|
+
"unformatted_total": 5500,
|
|
183
|
+
"total": "$55.00",
|
|
184
|
+
"shipping_charge_formated": "$5.00",
|
|
185
|
+
"shipping_method_id": "3"
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
### 4. Available Shipping Methods Endpoints
|
|
193
|
+
|
|
194
|
+
- `GET /fluent-cart/v2/checkout/get-available-shipping-methods` — Returns JSON list of methods (`timezone` or `country_code`, `state`).
|
|
195
|
+
- `GET /fluent-cart/v2/checkout/get-shipping-methods-list-view` — Returns pre-rendered HTML list (`view`) for direct insertion into checkout UI.
|
|
196
|
+
|
|
197
|
+
#### Response
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"available_shipping_methods": [
|
|
202
|
+
{
|
|
203
|
+
"id": 1,
|
|
204
|
+
"title": "Standard Shipping",
|
|
205
|
+
"charge_type": "flat_rate",
|
|
206
|
+
"charge_amount": 500,
|
|
207
|
+
"status": "active",
|
|
208
|
+
"countries": ["US", "CA"],
|
|
209
|
+
"states": []
|
|
210
|
+
}
|
|
211
|
+
],
|
|
212
|
+
"country_code": "US"
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
### 5. Get Country Info
|
|
219
|
+
|
|
220
|
+
`GET /fluent-cart/v2/checkout/get-country-info`
|
|
221
|
+
|
|
222
|
+
Retrieve localization details for a country (`data.country_code`, `data.states` array, and localized `data.address_locale` field requirements).
|
|
223
|
+
|
|
224
|
+
#### Response
|
|
225
|
+
|
|
226
|
+
```json
|
|
227
|
+
{
|
|
228
|
+
"data": {
|
|
229
|
+
"country_code": "US",
|
|
230
|
+
"states": [
|
|
231
|
+
{ "label": "California", "value": "CA" },
|
|
232
|
+
{ "label": "New York", "value": "NY" }
|
|
233
|
+
],
|
|
234
|
+
"address_locale": {
|
|
235
|
+
"state": { "label": "State", "required": true },
|
|
236
|
+
"postcode": { "label": "ZIP Code", "required": true },
|
|
237
|
+
"city": { "label": "City", "required": true }
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## User Authentication
|
|
246
|
+
|
|
247
|
+
### Customer Login
|
|
248
|
+
|
|
249
|
+
`POST /fluent-cart/v2/user/login`
|
|
250
|
+
|
|
251
|
+
Authenticates WordPress user during checkout and sets authentication cookies.
|
|
252
|
+
|
|
253
|
+
> **Header Required:** `X-WP-Nonce` header is required to prevent CSRF attacks.
|
|
254
|
+
|
|
255
|
+
#### Parameters
|
|
256
|
+
|
|
257
|
+
| Parameter | Type | Location | Required | Description |
|
|
258
|
+
|-----------|------|----------|----------|-------------|
|
|
259
|
+
| `user_login` | string | body | Yes | WordPress username or email address |
|
|
260
|
+
| `password` | string | body | Yes | Account password |
|
|
261
|
+
| `remember_me` | string | body | No | `on` to persist login session |
|
|
262
|
+
|
|
263
|
+
#### Response
|
|
264
|
+
|
|
265
|
+
```json
|
|
266
|
+
{
|
|
267
|
+
"success": true,
|
|
268
|
+
"data": {
|
|
269
|
+
"message": "Login successful",
|
|
270
|
+
"redirect_url": "https://your-site.com/customer-profile/#/profile"
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
#### Example
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
curl -X POST "https://example.com/wp-json/fluent-cart/v2/user/login" \
|
|
279
|
+
-H "Content-Type: application/json" \
|
|
280
|
+
-H "X-WP-Nonce: your_nonce_here" \
|
|
281
|
+
-d '{
|
|
282
|
+
"user_login": "john@example.com",
|
|
283
|
+
"password": "securepassword123",
|
|
284
|
+
"remember_me": "on"
|
|
285
|
+
}'
|
|
286
|
+
```
|