Defining Subscription Plan Details

Overview

Subscription plans are the foundation of your subscription service. They define how customers will be billed, what they’ll pay, and how you’ll receive the funds. Properly configuring your plans ensures smooth recurring billing and accurate settlement.

Plan Fields Reference

Required Fields

Field	Type	Description
Name	string	The short description of the plan
Code	string	The unique identifier of the plan (no spaces)
Interval	enum	The frequency of billing (Monthly / Yearly)
Amount	object	The base amount to be billed every interval

Optional Fields

Field	Type	Description
Description	string	An explanation of the details of the plan
Duration	number	The number of intervals the subscription will run until expiration. For example, if the frequency is monthly and the duration is 12, the subscription will expire after a year
Settlement Type	enum	How you receive funds: bank account (USD/EUR), USDC, or EUROe

Creating a Plan via API

// API Reference: /api-reference/api-reference/merchant-subscription/create-plan

const response = await fetch(
  'https://api-sandbox.coinflow.cash/api/merchant/subscription/plans',
  {
    method: 'POST',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Premium Monthly Plan',
      code: 'premium-monthly',
      description: 'Access to all premium features with monthly billing',
      interval: 'Monthly',
      duration: null,
      amount: {
        currency: 'USD',
        cents: 2999
      }
    })
  }
);

const plan = await response.json();

Best Practices

Plan Naming

Keep names short and descriptive
Include billing frequency for clarity
Use customer-friendly language

Plan Codes

Use lowercase with hyphens (e.g., premium-monthly)
Make it URL-safe
Keep it memorable for developers

Pricing

Use psychological pricing (.99 endings)
Consider offering both monthly and yearly options
Yearly plans typically offer 15-20% discount

Settlement Types

Choose based on your business needs:

Bank account: settle directly to your bank for straightforward accounting and reconciliation.
USDC / EUROe: optional, for merchants who need to hold USD- or EUR-pegged balances.

Advanced: Settling to a Smart Contract

When settling payments to a smart contract, include the optional Transaction field on the plan. This object specifies the on-chain destination and routing for funds.

Field	Type	Description
Transaction	object	Required only when settling payments to a smart contract.