Subscription Management

Some CFC features are gated behind subscription tiers. When a user attempts to access a premium feature, CFC emits a SUBSCRIPTION_UPGRADE_REQUEST message. The SDK handles this automatically — you just provide a callback.

Setup

import { CfcClient, Environment, IntegrationMode } from "@melio-eng/cfc-sdk";

const client = new CfcClient({
	container: document.getElementById("cfc-container")!,
	environment: Environment.STAGING,
	token: authToken,
	tenant: "my-tenant",
	mode: IntegrationMode.FULL_PAGE,

	onUpgradeRequest: (featureName, returnUrl) => {
		console.log(`Upgrade required for: ${featureName}`);
		console.log(`Return URL: ${returnUrl}`);
		showUpgradeFlow(featureName, returnUrl);
	},
});

client.init();

The Upgrade Flow

1. User clicks a premium feature in CFC
2. CFC sends SUBSCRIPTION_UPGRADE_REQUEST { featureName, returnUrl }
3. Host shows upgrade UI (modal or redirect)
4. User completes or cancels the upgrade
5. Host sends SUBSCRIPTION_UPGRADE_FINISHED { wasUpgraded }
6. CFC unlocks the feature (if upgraded) or shows a fallback

Modal Approach

Show the upgrade flow in a modal overlay while keeping CFC in the background:

const client = new CfcClient({
	// ...
	onUpgradeRequest: (featureName, returnUrl) => {
		const modal = createUpgradeModal(featureName);

		modal.onComplete = (didUpgrade: boolean) => {
			client.sendSubscriptionUpgradeFinished(didUpgrade);
			modal.close();
		};

		modal.onCancel = () => {
			client.sendSubscriptionUpgradeFinished(false);
			modal.close();
		};

		modal.show();
	},
});

Advantages

• CFC remains loaded in the background
• No re-authentication needed
• Faster return to CFC after upgrade

Redirect Approach

Navigate the entire page to the upgrade flow, then return to CFC afterward:

const client = new CfcClient({
	// ...
	onUpgradeRequest: (featureName, returnUrl) => {
		sessionStorage.setItem("cfc_return_url", returnUrl);
		sessionStorage.setItem("cfc_feature", featureName);
		window.location.href = `/upgrade?feature=${featureName}`;
	},
});

On the upgrade completion page:

import { CfcClient } from "@melio-eng/cfc-sdk";

const returnUrl = sessionStorage.getItem("cfc_return_url");
const wasUpgraded = getUpgradeResult();

const client = new CfcClient({
	container: document.getElementById("cfc-container")!,
	environment: Environment.STAGING,
	token: await getToken(),
	tenant: "my-tenant",
	target: returnUrl ?? "/view-payments",
	mode: IntegrationMode.FULL_PAGE,
});

client.init();

// Wait for CFC to load, then notify about upgrade result
client.on("LOADED", () => {
	client.sendSubscriptionUpgradeFinished(wasUpgraded);
});

sessionStorage.removeItem("cfc_return_url");
sessionStorage.removeItem("cfc_feature");

Advantages

• Full-page upgrade experience
• Can use existing subscription management pages
• Works well when upgrade requires external payment provider

Sending the Result

Always send SUBSCRIPTION_UPGRADE_FINISHED after the upgrade flow, regardless of the outcome:

// User completed the upgrade
client.sendSubscriptionUpgradeFinished(true);

// User cancelled or upgrade failed
client.sendSubscriptionUpgradeFinished(false);

This allows CFC to update its UI accordingly — unlocking the feature if wasUpgraded is true, or showing a fallback message if false.