FluentCart Paddle Classic

=== FluentCart Paddle Classic === Contributors: akmelias Tags: fluentcart, paddle, subscriptions, ecommerce Requires at least: 6.0 Tested up to: 6.9 Requires PHP: 7.4 Stable tag: 1.0.0 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html

Read-only support for legacy Paddle Classic subscriptions in FluentCart.

== Description ==

FluentCart's Paddle gateway targets the Paddle Billing API. Merchants migrated from another platform (for example EDD) often still hold Paddle Classic subscriptions — a separate Paddle product with its own API host, its own credentials, and bare-numeric subscription ids that the Billing endpoints cannot address. Without this addon, any operation against such a subscription fails.

This addon makes those legacy subscriptions safe to keep in FluentCart:

• Sync from gateway — pull a Classic subscription's current state (status, next billing date, cancellation date, payment method details) on demand, and record any renewal payments not yet stored locally, without duplicating existing ones.
• Automatic nightly sync — Paddle Classic sends no webhooks to FluentCart, so a daily batch job keeps the remaining Classic subscriptions current without an admin clicking each one.
• Verify — a read-only lookup that shows what a Classic subscription id resolves to (status, amount, customer) before you save it via Edit Vendor IDs.
• Safe refusal of writes — cancel, pause, resume and update are refused with a clear message rather than failing against the wrong API. Manage those in the Paddle dashboard; FluentCart picks the change up on the next sync.

FluentCart tells the two Paddle products apart by id shape: sub_xxxxx is Paddle Billing, a plain number (1234567) is Paddle Classic. Only bare-numeric ids take the addon's code path; everything else falls through to the standard Paddle gateway.

Requires FluentCart Pro, which owns the Paddle gateway this addon decorates.

== Installation ==

1. Install and activate FluentCart and FluentCart Pro.
2. Upload the plugin to /wp-content/plugins/fluent-cart-paddle-classic or install it through the Plugins screen.
3. Activate the plugin through the Plugins screen in WordPress.
4. Add your Paddle Classic credentials to wp-config.php (see Setup below).

No settings screen — the addon hooks into the existing Paddle gateway automatically.

== Setup ==

Classic sync needs the account-level credentials of your Paddle Classic account. Add both constants to wp-config.php, above the /* That's all, stop editing! */ line:

define('FLUENTCART_PADDLE_CLASSIC_VENDOR_ID', '1234567'); define('FLUENTCART_PADDLE_CLASSIC_AUTH_CODE', 'your-vendor-auth-code');

Both come from the Paddle Classic dashboard under Developer Tools → Authentication:

• Vendor ID — a short number identifying the Classic account.
• Vendor Auth Code — a long secret string. Treat it as a password.

These are account-level credentials, not subscription ids, and they are separate from the Paddle Billing API key already configured in FluentCart's payment settings. Same merchant, different Paddle product, different keys.

They live in wp-config.php rather than a settings screen so the secret is never stored in the database or exposed through the admin UI. The auth code is never written to logs or error messages.

Until both constants are defined, Classic sync stays completely inert — no outbound requests are made, and the nightly batch does nothing.

== Usage ==

= Syncing a Classic subscription on demand =

Open the order → Subscription card → kebab menu (⋮) → Sync from gateway – Paddle. Status, next billing date and any missing renewal payments are pulled in. Renewal payments already recorded locally are not duplicated.

= Fixing a wrong or missing Classic subscription id =

For subscriptions imported or migrated from another platform, the stored gateway identifier may be wrong or missing. While it is, syncing fails. To repair:

1. Get the correct Classic subscription id from the Paddle Classic dashboard (a plain number).
2. On the order → Subscription card → kebab menu (⋮) → Edit Vendor IDs → paste it.
3. Verify — confirm the customer and amount shown match the subscription. A successful lookup only proves the id exists in the Classic account whose credentials this store holds, so read the details before saving.
4. Save Changes.
5. Sync from gateway.

Editing vendor ids changes FluentCart only — nothing is sent to Paddle. Every change is written to the subscription's activity log.

= Automatic nightly sync =

Because Classic sends no webhooks, a Classic subscription only learns about renewals and cancellations when it is synced. Once the credentials are configured, a daily batch syncs the remaining Classic subscriptions automatically; no action needed.

= What is supported for Classic subscriptions =

• Sync from gateway — yes
• Verify — yes
• Record renewal payments — yes
• Automatic nightly sync — yes
• Webhooks — no, Paddle Classic sends none to FluentCart
• Cancel / pause / resume / edit from FluentCart — no, manage these in the Paddle dashboard, then sync

= Troubleshooting =

• "Paddle Classic credentials are not configured…" — the two wp-config.php constants are missing or empty.
• "Subscription not found" — the id does not exist in this Classic account. Re-check it in the Paddle dashboard.
• "This is a legacy Paddle Classic subscription… must be managed from the Paddle dashboard" — you tried to cancel/pause/resume/edit a Classic subscription. Do it in Paddle, then sync.
• Verify or Sync returns a Paddle error message — the message is passed straight through from Paddle, usually a wrong Vendor ID / Auth Code pair.

== Frequently Asked Questions ==

= Why can't I cancel a Classic subscription from FluentCart? =

The Paddle Billing API cannot address Classic subscription ids. Cancel, pause, resume and update must be performed in the Paddle dashboard. FluentCart will pick the change up on the next sync.

= Does this affect Paddle Billing subscriptions? =

No. Only subscriptions whose vendor id is a bare-numeric Classic id take the addon's code path; everything else falls through to the standard Paddle gateway.

= How do I know if a subscription is Classic or Billing? =

Look at its Vendor Subscription ID. sub_xxxxx is Paddle Billing; a plain number like 1234567 is Paddle Classic.

= Do manual or store-billed subscriptions need this? =

No. Only automatic (gateway-billed) subscriptions carry a gateway identifier. Manual and store-billed subscriptions are unaffected.

== Changelog ==

= 1.0.0 =

• Initial release.