FluentCart integrations and background jobs

Choose between an integration feed, a direct lifecycle listener, and an addon-owned job based on configurability and durability. Every external side effect must tolerate delayed delivery, duplicate delivery, and partial failure.

Read integration-queue-map.md before adding a provider or diagnosing the queue.

Use the feed framework for configurable providers

Extend BaseIntegrationManager when store administrators need global/product feeds, event selection, conditional routing, provider credentials, smartcodes, priority, and background execution. Register the manager after FluentCart has loaded and implement:

• a stable, addon-owned integrationKey;
• getIntegrationDefaults() and getSettingsFields();
• validateFeedData() with server-side normalization and secret handling;
• processAction() for one resolved order/event/feed;
• isConfigured()/API settings that never expose credentials to public output.

BaseIntegrationManager registers dynamic fluent_cart/integration/run/{integrationKey} execution. Do not dispatch that hook with browser-supplied feed/order data.

Choose lifecycle triggers precisely

IntegrationEventListener maps order_paid_done, cancellation/full refund, subscription activation/reactivation/cancellation/renewal/EOT/validity expiry, and shipped/delivered events. Revoke behavior is feed-configurable for the defined revoke hooks.

Use order_paid_done for canonical initial paid-order provisioning. Use subscription_renewed for all settled renewals. Do not hook or manually fire the internal fluent_cart/order_paid_async_private_handle action; its name marks an implementation detail and its payload/ordering may change.

Understand the two queue layers

FluentCart stores integration work and state in fct_scheduled_actions. Action Scheduler is then used as the dispatch/runner transport for parts of that work. An Action Scheduler row is therefore not always the complete business job. Inspect both stores, the order log, and provider response when debugging.

Core uses Action Scheduler group fluent-cart. Addons should use a unique group such as my-addon-fluentcart so cleanup, cancellation, support tools, and tests do not collide with core jobs.

If an addon needs durable custom work, own its schema/payload contract or use Action Scheduler directly. Do not insert arbitrary rows into fct_scheduled_actions and assume core will route them.

Make handlers replay-safe

1. Build a stable operation key from provider, feed, event, and durable object.
2. Re-read the current order/subscription before acting.
3. Atomically claim or record the operation in addon-owned state.
4. Use provider idempotency keys where available.
5. Store sanitized outcome/reference and distinguish retryable from terminal failure.
6. Throw or return failure in the way the selected runner actually observes; never mark complete in a finally block after a failed call.

The in-request pushed-feed cache only suppresses repeats in one PHP request. It is not durable deduplication.

The receipt fallback also exposes a nopriv fluent_cart_run_order_actions AJAX handler keyed by order_hash. It can trigger pending post-payment work for the resolved order. Treat the hash as a bearer trigger, never trust that request as a new authorization/settlement signal, and ensure every effect independently verifies current paid state and idempotency.

Audit queue lifecycle

Monitor pending age, running age, retry count, dead/failed volume, action/group, object existence, and Action Scheduler health. The 1.6.0 integration runner has early-return paths after setting a row to running or before completion; support tools should detect stale states rather than assuming every missing callback is a provider outage.

Do not assume plugin deactivation removed every scheduled action. Inventory Action Scheduler and WordPress-Cron recurrence after activation, deactivation, and reactivation, and unschedule only addon-owned hooks/groups.

Test matrix

Test global/product feeds, variation restriction, priority, disabled provider, all supported event and revoke hooks, initial versus renewal order, async and real-time mode, public receipt-trigger replay, duplicate event, worker crash before/after provider success, missing/deleted feed, missing order, exception, rate limit, credential rotation, retry exhaustion, stale running recovery, Action Scheduler unavailable, WP-Cron disabled, multisite, deactivation/reactivation, and redacted logs.

Cross-references

• Use fluentcart-orders-transactions for event payload and settlement timing.
• Use fluentcart-subscriptions-renewals for recurring triggers.
• Use the wc-action-scheduler-jobs skill for Action Scheduler mechanics.

References

• Official modules overview: https://dev.fluentcart.com/modules/
• Verified Free source paths:
  • fluent-cart/app/Modules/Integrations/BaseIntegrationManager.php
  • fluent-cart/app/Modules/Integrations/GlobalIntegrationSettings.php
  • fluent-cart/app/Modules/Integrations/GlobalNotificationHandler.php
  • fluent-cart/app/Listeners/IntegrationEventListener.php
  • fluent-cart/app/Models/ScheduledAction.php
  • fluent-cart/app/Hooks/Scheduler/
  • fluent-cart/app/Events/
• Verified Pro integrations:
  • fluent-cart-pro/app/Modules/Integrations/