Claude Skill

fluentcart-rest-headless

Implements and audits FluentCart REST, AJAX, headless, mobile, and external client integrations. Covers the source-verified /fluent-cart/v2 routes, FluentCart router policies, WordPress cookie/nonces and application passwords, customer ownership, public checkout endpoints, cart-h

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download lonsdale201-wp-agent-skills-fluentcart_fluentcart-rest-headless-52f6020.zip · 4 KB

Install

skills CLI npx skills add https://github.com/Lonsdale201/wp-agent-skills/tree/main/fluentcart/fluentcart-rest-headless
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install lonsdale201-wp-agent-skills@llmmart
Git git clone https://github.com/Lonsdale201/wp-agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole lonsdale201/wp-agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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
Files (wp-agent-skills)
  • agents
    • openai.yaml 319 B
      Loading…
  • references
    • route-auth-map.md 2.7 KB
      Loading…
  • SKILL.md 5.7 KB
    ---
    name: fluentcart-rest-headless
    description: >-
      Implements and audits FluentCart REST, AJAX, headless, mobile, and external
      client integrations. Covers the source-verified /fluent-cart/v2 routes,
      FluentCart router policies, WordPress cookie/nonces and application
      passwords, customer ownership, public checkout endpoints, cart-hash trust,
      custom register_rest_route endpoints, schema validation, pagination, rate
      limits, cache resets, and documentation drift. Use for REST clients, SPA or
      mobile storefronts, customer portals, webhooks, custom resources, or exposed
      FluentCart data.
    metadata:
      wp-skills-author: "Soczó Kristóf"
      wp-skills-contact: "mailto:lonsdale201@hotmail.com"
      wp-skills-plugin: "fluent-cart"
      wp-skills-plugin-version-tested: "1.6.0"
      wp-skills-wp-version-tested: "7.0.2"
      wp-skills-php-min: "7.4"
      wp-skills-last-updated: "2026-08-06"
    ---
    
    # 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](references/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
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.