FluentCart extension architecture

Establish the correct integration boundary before writing business logic. Do not transpose WooCommerce CRUD, cart, session, order, or subscription assumptions onto FluentCart.

Read data-and-lifecycle-map.md when the change touches more than one entity or persists commerce state.

Bootstrap safely

• Declare FluentCart as an integration dependency in the addon's own admin UX.
• Register classes and hooks no earlier than plugins_loaded.
• Use fluentcart_loaded when FluentCart's application object is required.
• Use fluent_cart/init for components that need FluentCart's init-time routes, modules, CPT, taxonomies, or migrated schema.
• Attach listeners for fluent_cart/register_storage_drivers and fluent_cart/register_payment_methods by fluentcart_loaded at the latest. Those registration actions run on init before fluent_cart/init in 1.6.0, so adding their listeners inside fluent_cart/init misses the event.
• Feature-detect Pro with FLUENTCART_PRO_PLUGIN_VERSION or the exact Pro class. Do not infer Pro from a saved option.
• Recheck the minimum core/Pro version pair before using a newly added method.

add_action('fluent_cart/init', static function ($app): void {
    if (!defined('FLUENTCART_VERSION')) {
        return;
    }

    // Register this addon's FluentCart hooks here.
});

The two lifecycle names are intentionally inconsistent: fluentcart_loaded has no underscore after fluent; fluent_cart/init does.

Select the right persistence layer

Data	Canonical layer
Product title/content/status	WordPress post APIs or ProductResource
Product detail, variants, attributes, stock	FluentCart Resource/service APIs
Orders, items, transactions, subscriptions	FluentCart models/resources and lifecycle services
Categories and brands	WordPress taxonomy APIs using FluentCart taxonomy names
Plugin settings	StoreSettings, ModuleSettings, or fluent_cart_* option helpers
Addon-owned state	Addon-owned table/options with explicit foreign identifiers

Use Resource APIs for coordinated writes. Models are suitable for scoped reads and documented model operations, but a raw model save can bypass validation, secondary rows, counters, stock movements, event dispatch, remote gateway work, or cache invalidation.

Never write fct_* rows with ad hoc SQL in normal request code. Restrict direct SQL to migrations, bounded reports, or repairs that explicitly reproduce all required invariants.

Preserve core invariants

• Treat monetary inputs and totals as integer minor units. In 1.6.0, Helper::toCent('12.34') yields 1234. Use FluentCart formatting helpers only at display boundaries.
• Keep store mode attached to every integration. Never mix test and live transactions, provider objects, cache keys, or reports.
• Treat an order's status, payment_status, and shipping_status as separate state dimensions.
• Treat Customer as a commerce identity distinct from WP_User.
• Treat cart_hash, order UUID, transaction UUID, and subscription UUID as lookup tokens, not authorization by themselves.
• Design callbacks and outbound effects for replay. Webhooks, checkout retries, Action Scheduler, and internal queues can execute more than once.
• Preserve filter inputs and return the documented type. Scope every dynamic hook to the intended product, order, gateway, or integration key.

Extension workflow

1. Record the installed Free, Pro, and companion-plugin versions.
2. Identify the owning entity and the service that normally mutates it.
3. Trace the controller/service to the final event rather than choosing a hook by name alone.
4. Confirm callback arguments and timing from source at the installed version.
5. Add dependency guards and Free/Pro feature detection.
6. Enforce authorization, object ownership, validation, and monetary units at the addon's boundary.
7. Test live/test separation, anonymous/authenticated paths, retries, concurrent submission, and an interrupted background job.

Documentation accuracy rule

Treat the installed source and registered runtime routes as authoritative. FluentCart's current developer pages contain some stale v1 URLs, generic cart endpoints, fixed rate-limit claims, and a gateway example that omits metadata required by GatewayManager in 1.6.0. Verify any copied example before shipping.

Cross-references

• Use fluentcart-products-inventory for catalog and stock changes.
• Use fluentcart-orders-transactions for order events and status transitions.
• Use fluentcart-rest-headless for HTTP clients and custom endpoints.

References

• Official developer documentation: https://dev.fluentcart.com/
• Official database documentation: https://dev.fluentcart.com/database/
• Verified Free source paths:
  • fluent-cart/fluent-cart.php
  • fluent-cart/boot/app.php
  • fluent-cart/boot/globals.php
  • fluent-cart/api/FluentCartGeneralApi.php
  • fluent-cart/api/Resource/
  • fluent-cart/app/Models/
  • fluent-cart/database/Migrations/
• Verified Pro source path:
  • fluent-cart-pro/fluent-cart-pro.php