Claude Skill

fluentcart-migration

Plans, runs, extends, and audits migrations into FluentCart with the FluentCart Migrator companion plugin or Free-core WooCommerce migrator. Covers EDD 3 products, tax rates, coupons, customers, orders, transactions, subscriptions, downloads and licenses; source-to-target ID maps

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

Install

skills CLI npx skills add https://github.com/Lonsdale201/wp-agent-skills/tree/main/fluentcart/fluentcart-migration
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 migration

Run commerce migrations as staged, resumable data transformations with a reconciliation report. Never test a destructive migration/reset first on the only production copy.

Read migration-runbook.md before executing or extending a migration.

Identify the correct migrator

The FluentCart Migrator 1.0.0 companion implements EDD 3.x migration. Its UI lists WooCommerce and SureCart as coming soon; do not interpret those cards as implemented adapters.

FluentCart Free 1.6.0 separately contains a WooCommerceMigrator module/CLI for WooCommerce data. It is not the companion plugin's EDD pipeline and does not imply complete order/subscription/gateway parity. Audit its exact source scope before using it.

Establish a cutover contract

Inventory source versions, table prefixes, currency and decimals, tax mode, timezone, gateways, order statuses/types, customers, products/variations, downloads, coupons, refunds, subscriptions, license data, and external webhook/update URLs. Decide what is supported, transformed, retained only in legacy storage, or explicitly excluded.

Back up database and files, clone to staging, freeze or record source writes, and choose a repeatable delta strategy. A migration that takes hours without a write-freeze or delta pass is not a complete cutover.

Use the EDD pipeline in dependency order

Run and verify:

  1. compatibility, source stats, store/currency/tax preflight;
  2. products, variations, categories and downloads;
  3. tax rates and coupon references;
  4. payments/orders, customers, transactions, refunds, subscriptions/licenses;
  5. fix/recount substeps and failed-item replay;
  6. license verification and end-to-end checkout/download/renewal smoke tests.

The REST UI uses /fct-migrator/v1 with manage_options and time-boxes payment work in 100-row pages for about 25 seconds before resuming. For large stores, use the provided WP-CLI command, controlled process limits, and persistent logs.

Make custom adapters idempotent

Maintain explicit source-type/source-ID to target-ID maps. Use a stable unique source marker to update/reuse an already migrated entity. Never deduplicate a customer by email or an order by a generated UUID without a documented conflict policy.

Transform monetary values into FluentCart integer minor units with currency- specific precision. Preserve original currency, gross/net/tax/discount/refund allocations and exchange assumptions. Test zero- and three-decimal currencies; do not multiply every source amount by 100 unconditionally.

Reset request-static migration/model caches between batches. Keep each batch bounded and safe to resume after termination. Do not mark a step complete when some rows failed without surfacing a replayable error manifest.

Preserve external continuity

Migrated subscriptions may still be owned by their original gateway and remote subscription IDs. Do not recreate charges or change billing owner during data copy. Preserve webhook/payment lookup compatibility until all in-flight events resolve.

The companion retains EDD license/download/renewal compatibility behavior. Keep it active if legacy client URLs still target it, and audit those public credential endpoints before cutover. EDD Software Licensing data requires FluentCart Pro with its Licensing module.

Verify before cleanup

Compare counts and monetary aggregates by currency/status/date, then sample record graphs: product->variation->download, order->items->transaction->refund, customer ownership, subscription->renewals, coupon usage, license->activations. Run recount only after record relationships are correct.

Reset calls MigratorService::wipeMigratedData(), which refreshes FluentCart's custom tables and deletes every fluent-products post, not merely rows proven to come from EDD. The REST /reset path and dedicated WP-CLI reset subcommand require FLUENT_CART_DEV_MODE, but the 1.0.0 wp fluent_cart_migrator migrate_from_edd --reset flag reaches the wipe after confirmation without that dev-mode guard. Never run either form on production; require a tested full backup and isolated staging environment.

Test matrix

Test empty and large stores, rerun/resume at every boundary, crash mid-page, duplicate source rows, email collisions, product/variation map loss, missing files, multiple currencies, zero-decimal amounts, inclusive/exclusive tax, coupon product restrictions, partial/full refunds, failed/pending orders, recurring and reactivated subscriptions, license status/activations, old EDD client URLs, gateway webhook fallback, source writes during cutover, verification mismatch, rollback, and cleanup after the retention window.

Cross-references

  • Use fluentcart-extension-architecture for the target data model.
  • Use fluentcart-orders-transactions for monetary/order invariants.
  • Use fluentcart-subscriptions-renewals and fluentcart-licensing-pro for recurring/license continuity.

References

  • Verified companion source paths:
    • fluent-cart-migrator/Classes/MigratorService.php
    • fluent-cart-migrator/Classes/Commands.php
    • fluent-cart-migrator/Classes/Admin/RestApi.php
    • fluent-cart-migrator/Classes/EDD3/
    • fluent-cart-migrator/assets/js/components/
  • Verified Free source paths:
    • fluent-cart/app/Modules/WooCommerceMigrator/
Files (wp-agent-skills)
  • agents
    • openai.yaml 315 B
      Loading…
  • references
    • migration-runbook.md 3.5 KB
      Loading…
  • SKILL.md 6.1 KB
    ---
    name: fluentcart-migration
    description: >-
      Plans, runs, extends, and audits migrations into FluentCart with the
      FluentCart Migrator companion plugin or Free-core WooCommerce migrator.
      Covers EDD 3 products, tax rates, coupons, customers, orders, transactions,
      subscriptions, downloads and licenses; source-to-target ID maps, resumable
      batches, WP-CLI, recount/verification, legacy endpoint compatibility,
      rollback, and destructive reset controls. Use for EDD/WooCommerce imports,
      custom source adapters, large-store cutovers, or migration integrity reviews.
    metadata:
      wp-skills-author: "Soczó Kristóf"
      wp-skills-contact: "mailto:lonsdale201@hotmail.com"
      wp-skills-plugin: "fluent-cart-migrator"
      wp-skills-plugin-version-tested: "1.0.0"
      wp-skills-wp-version-tested: "7.0.2"
      wp-skills-php-min: "7.4"
      wp-skills-last-updated: "2026-08-06"
    ---
    
    # FluentCart migration
    
    Run commerce migrations as staged, resumable data transformations with a
    reconciliation report. Never test a destructive migration/reset first on the
    only production copy.
    
    Read [migration-runbook.md](references/migration-runbook.md) before executing or
    extending a migration.
    
    ## Identify the correct migrator
    
    The FluentCart Migrator 1.0.0 companion implements EDD 3.x migration. Its UI
    lists WooCommerce and SureCart as coming soon; do not interpret those cards as
    implemented adapters.
    
    FluentCart Free 1.6.0 separately contains a WooCommerceMigrator module/CLI for
    WooCommerce data. It is not the companion plugin's EDD pipeline and does not
    imply complete order/subscription/gateway parity. Audit its exact source scope
    before using it.
    
    ## Establish a cutover contract
    
    Inventory source versions, table prefixes, currency and decimals, tax mode,
    timezone, gateways, order statuses/types, customers, products/variations,
    downloads, coupons, refunds, subscriptions, license data, and external
    webhook/update URLs. Decide what is supported, transformed, retained only in
    legacy storage, or explicitly excluded.
    
    Back up database and files, clone to staging, freeze or record source writes,
    and choose a repeatable delta strategy. A migration that takes hours without a
    write-freeze or delta pass is not a complete cutover.
    
    ## Use the EDD pipeline in dependency order
    
    Run and verify:
    
    1. compatibility, source stats, store/currency/tax preflight;
    2. products, variations, categories and downloads;
    3. tax rates and coupon references;
    4. payments/orders, customers, transactions, refunds, subscriptions/licenses;
    5. fix/recount substeps and failed-item replay;
    6. license verification and end-to-end checkout/download/renewal smoke tests.
    
    The REST UI uses /fct-migrator/v1 with manage_options and time-boxes payment
    work in 100-row pages for about 25 seconds before resuming. For large stores,
    use the provided WP-CLI command, controlled process limits, and persistent logs.
    
    ## Make custom adapters idempotent
    
    Maintain explicit source-type/source-ID to target-ID maps. Use a stable unique
    source marker to update/reuse an already migrated entity. Never deduplicate a
    customer by email or an order by a generated UUID without a documented conflict
    policy.
    
    Transform monetary values into FluentCart integer minor units with currency-
    specific precision. Preserve original currency, gross/net/tax/discount/refund
    allocations and exchange assumptions. Test zero- and three-decimal currencies;
    do not multiply every source amount by 100 unconditionally.
    
    Reset request-static migration/model caches between batches. Keep each batch
    bounded and safe to resume after termination. Do not mark a step complete when
    some rows failed without surfacing a replayable error manifest.
    
    ## Preserve external continuity
    
    Migrated subscriptions may still be owned by their original gateway and remote
    subscription IDs. Do not recreate charges or change billing owner during data
    copy. Preserve webhook/payment lookup compatibility until all in-flight events
    resolve.
    
    The companion retains EDD license/download/renewal compatibility behavior.
    Keep it active if legacy client URLs still target it, and audit those public
    credential endpoints before cutover. EDD Software Licensing data requires
    FluentCart Pro with its Licensing module.
    
    ## Verify before cleanup
    
    Compare counts and monetary aggregates by currency/status/date, then sample
    record graphs: product->variation->download, order->items->transaction->refund,
    customer ownership, subscription->renewals, coupon usage, license->activations.
    Run recount only after record relationships are correct.
    
    Reset calls MigratorService::wipeMigratedData(), which refreshes FluentCart's
    custom tables and deletes every fluent-products post, not merely rows proven to
    come from EDD. The REST /reset path and dedicated WP-CLI reset subcommand require
    FLUENT_CART_DEV_MODE, but the 1.0.0
    `wp fluent_cart_migrator migrate_from_edd --reset` flag reaches the wipe after
    confirmation without that dev-mode guard. Never run either form on production;
    require a tested full backup and isolated staging environment.
    
    ## Test matrix
    
    Test empty and large stores, rerun/resume at every boundary, crash mid-page,
    duplicate source rows, email collisions, product/variation map loss, missing
    files, multiple currencies, zero-decimal amounts, inclusive/exclusive tax,
    coupon product restrictions, partial/full refunds, failed/pending orders,
    recurring and reactivated subscriptions, license status/activations, old EDD
    client URLs, gateway webhook fallback, source writes during cutover, verification
    mismatch, rollback, and cleanup after the retention window.
    
    ## Cross-references
    
    - Use fluentcart-extension-architecture for the target data model.
    - Use fluentcart-orders-transactions for monetary/order invariants.
    - Use fluentcart-subscriptions-renewals and fluentcart-licensing-pro for
      recurring/license continuity.
    
    ## References
    
    - Verified companion source paths:
      - fluent-cart-migrator/Classes/MigratorService.php
      - fluent-cart-migrator/Classes/Commands.php
      - fluent-cart-migrator/Classes/Admin/RestApi.php
      - fluent-cart-migrator/Classes/EDD3/
      - fluent-cart-migrator/assets/js/components/
    - Verified Free source paths:
      - fluent-cart/app/Modules/WooCommerceMigrator/
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.