{"slug":"fluentcart-orders-transactions","title":"fluentcart-orders-transactions","summary":"Implements and audits FluentCart order, order-item, transaction, status, payment-settlement, refund, renewal-order, and lifecycle-hook behavior. Use when reading or mutating fct_orders or fct_order_transactions, selecting order_created, order_paid, order_paid_done, order_payment_","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-16T14:51:45.939115Z","repo":{"url":"https://github.com/Lonsdale201/wp-agent-skills","stars":22,"forks":2,"license":"MIT","updatedAt":"2026-09-26T23:03:36Z"},"bodyHtml":"<hr>\n<h2>name: fluentcart-orders-transactions\ndescription: &gt;-\nImplements and audits FluentCart order, order-item, transaction, status,\npayment-settlement, refund, renewal-order, and lifecycle-hook behavior. Use\nwhen reading or mutating fct_orders or fct_order_transactions, selecting\norder_created, order_paid, order_paid_done, order_payment_failed,\norder_refunded, or dynamic status hooks, marking an order paid, reconciling a\nwebhook, refunding money, or preventing duplicate fulfillment and incorrect\nstatus transitions.\nmetadata:\nwp-skills-author: \"Soczó Kristóf\"\nwp-skills-contact: \"mailto:lonsdale201@hotmail.com\"\nwp-skills-plugin: \"fluent-cart\"\nwp-skills-plugin-version-tested: \"1.6.0\"\nwp-skills-wp-version-tested: \"7.0.2\"\nwp-skills-php-min: \"7.4\"\nwp-skills-last-updated: \"2026-08-06\"</h2>\n<h1>FluentCart orders and transactions</h1>\n<p>Drive order state from verified transactions and FluentCart lifecycle services.\nDo not equate order creation, successful payment, fulfillment, and subscription\nrenewal.</p>\n<p>Read <a href=\"references/order-event-map.md\">order-event-map.md</a> before attaching an\nirreversible side effect or updating any status.</p>\n<h2>Keep state dimensions separate</h2>\n<p>An order independently carries:</p>\n<ul>\n<li>status: commercial/fulfillment progression;</li>\n<li>payment_status: money progression;</li>\n<li>shipping_status: physical delivery progression;</li>\n<li>type: payment, subscription, renewal, and related variants;</li>\n<li>mode: test or live.</li>\n</ul>\n<p>Use Status, StatusHelper, OrderResource, Orders, PaymentInstance, and Refund as\nappropriate. A direct update to payment_status does not create/reconcile a\ntransaction, recount totals, complete the cart, reserve/release stock, activate\na subscription, or dispatch the normal events.</p>\n<h2>Choose the event by guarantee</h2>\n<table>\n<thead>\n<tr>\n<th>Requirement</th>\n<th>Use</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Durable order aggregate created/updated for checkout</td>\n<td>fluent_cart/order_created</td>\n</tr>\n<tr>\n<td>Initial order transitioned to paid</td>\n<td>fluent_cart/order_paid</td>\n</tr>\n<tr>\n<td>Deferred normal post-payment processing point</td>\n<td>fluent_cart/order_paid_done</td>\n</tr>\n<tr>\n<td>Payment attempt became failed</td>\n<td>fluent_cart/order_payment_failed</td>\n</tr>\n<tr>\n<td>Refund recorded and totals/status synchronized</td>\n<td>fluent_cart/order_refunded</td>\n</tr>\n<tr>\n<td>Any subscription renewal settled</td>\n<td>fluent_cart/subscription_renewed</td>\n</tr>\n<tr>\n<td>Store-managed renewal invoice transitioned to paid</td>\n<td>fluent_cart/renewal_paid</td>\n</tr>\n<tr>\n<td>One status dimension changed</td>\n<td>fluent_cart/_status_changed</td>\n</tr>\n</tbody>\n</table>\n<p>order_created does not mean paid. order_paid is synchronous and its internal\nlistener recounts order/customer state and may create a WP user.\norder_paid_done is emitted later by Action Scheduler after a valid paid order is\nreloaded. Use it for third-party fulfillment/integration work that belongs after\nthe standard deferred path.</p>\n<p>Never hook business logic to\nfluent_cart/order_paid_async_private_handle. Core labels it private. The legacy\nmisspelled ansyc variant exists only to drain old queued jobs.</p>\n<h2>Make event callbacks replay-safe</h2>\n<pre><code>add_action('fluent_cart/order_paid_done', static function (array $data): void {\n    $order = $data['order'] ?? null;\n    if (!$order || $order-&gt;mode !== 'live') {\n        return;\n    }\n\n    // Atomically claim an addon-owned idempotency record keyed by order ID\n    // and operation before sending or granting anything.\n});\n</code></pre>\n<p>StatusHelper atomically claims the pending-to-paid transition to reduce webhook\nand browser-confirmation races. That does not make downstream callbacks\nexactly-once. Store an addon-owned operation key and make retries converge.</p>\n<h2>Handle transactions and refunds</h2>\n<ul>\n<li>Use transaction IDs/UUIDs in the correct namespace; do not use an invoice\nnumber as a provider idempotency key.</li>\n<li>Verify provider object, signature, currency, amount, mode, order/customer\nreference, and prior processed state.</li>\n<li>Reconcile through StatusHelper instead of announcing paid from a browser\nredirect.</li>\n<li>Use Refund::processRefund() for a local/admin initiated refund and the\ngateway's processRefund implementation for the provider operation.</li>\n<li>Use Refund::createOrRecordRefund() for webhook reconciliation; it deduplicates\nby provider refund ID and can match a pending local refund.</li>\n<li>Keep all amounts integer minor units and enforce both order and transaction\nrefundable ceilings.</li>\n<li>Test partial, full, repeated, and out-of-order refund notifications.</li>\n</ul>\n<h2>Query and authorize</h2>\n<ul>\n<li>Scope customer-facing queries by the resolved customer, not UUID alone.</li>\n<li>Treat Order.uuid as an opaque lookup value but not a guaranteed database\nunique key; legacy rows and the current schema use a non-unique index.</li>\n<li>Eager-load only the relationships needed by the job.</li>\n<li>Bound report/admin queries and preserve mode/currency distinctions.</li>\n<li>Redact provider payloads, customer PII, and payment tokens from logs.</li>\n</ul>\n<h2>Cross-references</h2>\n<ul>\n<li>Use fluentcart-payment-gateways for provider confirmation and webhooks.</li>\n<li>Use fluentcart-subscriptions-renewals for renewal semantics.</li>\n<li>Use fluentcart-integrations-jobs for outbound feeds and queues.</li>\n</ul>\n<h2>References</h2>\n<ul>\n<li>Official order hooks: <a href=\"https://dev.fluentcart.com/hooks/actions/orders/\">https://dev.fluentcart.com/hooks/actions/orders/</a></li>\n<li>Verified Free source paths:\n<ul>\n<li>fluent-cart/app/Models/Order.php</li>\n<li>fluent-cart/app/Models/OrderItem.php</li>\n<li>fluent-cart/app/Models/OrderTransaction.php</li>\n<li>fluent-cart/api/Resource/OrderResource.php</li>\n<li>fluent-cart/app/Helpers/Status.php</li>\n<li>fluent-cart/app/Helpers/StatusHelper.php</li>\n<li>fluent-cart/app/Events/Order/</li>\n<li>fluent-cart/app/Services/Payments/Refund.php</li>\n<li>fluent-cart/app/Hooks/actions.php</li>\n</ul>\n</li>\n</ul>\n","files":[{"path":"agents/openai.yaml","sizeBytes":325,"isText":true},{"path":"references/order-event-map.md","sizeBytes":2513,"isText":true},{"path":"SKILL.md","sizeBytes":5487,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-16T14:55:24.309695Z","sha256":"1A0F66988D233F77A49DE767865879230A3310955BB58F805D364169F868C15E","sizeBytes":4004},"review":null,"source":{"repositoryUrl":"https://github.com/Lonsdale201/wp-agent-skills","path":"fluentcart/fluentcart-orders-transactions","license":"MIT","commit":"c51b571a259f0c4b5f5c0a3bc50ed580c6851f98","subtreeSha":"E878B04A82EBFF6E2E296C37F04AACC149DD10D3FF550D9B9E778658947A4A80","lastSyncedAt":"2026-09-29T23:33:03.303675Z"},"reviewedAt":"2026-09-16T15:10:48.42771Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/Lonsdale201/wp-agent-skills/tree/main/fluentcart/fluentcart-orders-transactions"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install lonsdale201-wp-agent-skills@llmmart"},{"target":"git","command":"git clone https://github.com/Lonsdale201/wp-agent-skills.git"}]}