FluentCart REST and headless clients

Inventory the routes registered by the installed version before designing a client. FluentCart 1.6.0 registers its main REST API under /fluent-cart/v2, but not every browser checkout operation is a REST resource.

Read route-auth-map.md before exposing data or building a headless/mobile client.

Do not derive routes from generic examples

The official developer pages currently contain examples that alternate v1 and v2 and describe generic cart endpoints not registered by the tested 1.6.0 runtime. The main API is v2, while an isolated v1 editor-autosave route also exists; never rewrite a route's version globally. Use rest_get_server()->get_routes(), the installed route files, and controller code as the contract for a pinned version.

In 1.6.0, checkout/cart mutations also use authenticated or public WordPress AJAX dispatchers such as fluent_cart_checkout_routes and fluent_cart_place_order. There is no source/runtime-confirmed generic /fluent-cart/v2/cart/add, /cart/update, or /cart/remove family. A headless client must either reproduce the supported checkout transport precisely or add an addon-owned REST facade that delegates to the same server services.

Apply authentication and ownership separately

• Admin routes use FluentCart router policies/capabilities.
• Customer routes require an authenticated WordPress user, then controllers scope records to the resolved FluentCart customer.
• Public checkout/product/payment endpoints still require object-level checks, opaque identifiers, state validation, and abuse controls.
• A cart hash is a bearer pointer for cart continuity, not customer identity.

For same-origin JavaScript, use WordPress cookie authentication with a wp_rest nonce. For external trusted clients, WordPress Application Passwords provide Basic Auth over HTTPS. OAuth/JWT requires a separately installed and audited authentication provider; it is not supplied by FluentCart core.

Never rely on CustomerFrontendPolicy alone as order ownership: it establishes login, while the controller/query must constrain the requested object.

Build addon endpoints safely

Register an addon-owned namespace with register_rest_route(). Always provide a permission_callback, argument schema/validation/sanitization, bounded pagination, explicit response fields, and stable WP_Error codes/statuses. Delegate business changes to FluentCart resources/services instead of direct table writes.

Do not call a FluentCart controller merely to inherit authorization: policies are attached by FluentCart's router registration. Recreate the required capability/ownership check in the addon route.

Add per-principal or per-resource throttling to sensitive public endpoints. The installed source does not establish a single fixed global rate limit for all FluentCart REST routes, so do not repeat documentation claims about one.

Design headless checkout as a state machine

1. Fetch current product/variation data and minor-unit prices.
2. Create/resume only the intended cart; keep its hash confidential.
3. Patch address, coupon and shipping data through supported server logic.
4. Render current server totals and validation errors.
5. Place the order once, honoring lock/rate-limit responses.
6. Complete the gateway's redirect/client-confirmation contract.
7. Treat provider webhook/order state as settlement authority.

Never mark an order paid from a client success page. Make retries and network replays idempotent.

Cache and response discipline

Models/helpers have request-static caches. In REST unit tests, CLI loops, or long-running workers simulating multiple users, call the available resetCache() methods before crossing identity/store boundaries. Do not leak ORM models, secrets, gateway metadata, cart hashes, license keys, or unrestricted order meta through a convenience serializer.

Test matrix

Test anonymous/customer/admin/application-password requests; expired/missing nonce; another customer's UUID; guessed cart hash; invalid enum/amount; excess page size; duplicate place order; concurrent cart requests; checkout AJAX or facade parity; free and paid orders; gateway redirect; webhook-before-return; rate-limit response; long-running cache isolation; and route inventory after a FluentCart upgrade.

Cross-references

• Use fluentcart-customers-portal for identity and ownership.
• Use fluentcart-cart-checkout for checkout locking and revalidation.
• Use fluentcart-payment-gateways for provider completion/webhooks.

References

• Official REST overview: https://dev.fluentcart.com/api/
• Verified Free source paths:
  • fluent-cart/app/Http/Routes/api.php
  • fluent-cart/app/Http/Routes/frontend_routes.php
  • fluent-cart/app/Http/Routes/routes.php
  • fluent-cart/app/Http/Routes/WebRoutes.php
  • fluent-cart/app/Http/Controllers/
  • fluent-cart/app/Http/Policies/
  • fluent-cart/app/Services/Permission/
  • fluent-cart/boot/app.php