Subscription Plans

Learn how to create Subscription Plans to manage Subscriptions at scale.

Subscription plans are templates with set recurring costs and frequencies that can be used to create subscriptions for individual buyers.

Example use cases for Subscription Plans:

You have pricing tiers (e.g., Basic, Premium, Deluxe, Enterprise). You can use the pricing tiers to group subscriptions under them.
You have different products or services you offer that have different recurring costs and frequencies (e.g. 30 min guitar lessons, 60 min guitar lessons,)
You charge different recurring rates based on the location

Creating a Subscription Plan on the Finix Dashboard

You can create a Subscription Plan in the Finix Dashboard without any development work. Using the Finix Dashboard, you can:

Create Subscription Plans
View all existing Subscription Plans
De-Activate a Subscription Plan if you no longer want to add new subscriptions under that Subscription Plan.

Step 1: Navigate to Subscription Plans

To create a Subscription Plan in the Finix Dashboard:

Log into the Finix Dashboard.
Click Subscriptions page > Subscription Plans tab.
Click Create Subscription Plan
Fill out the form with the requested details.

Step 2. Create a Subscription Plan

When you click on Create Subscription Plan, a form will appear with the following options:

Billing Settings

This section specifies how you want to bill your buyers.

Subscription Name
Billing Frequency
Recurring Price

Trial Phase

You can enter a trial phase if your Subscription requires a set number of days before charging the buyer. For example, a 30-day trial, 3-month trial, or other combinations are possible.

Discount Phase

You can enter a discount phase if you would like to have a discounted rate for a set of amount of intervals. These take place after the Trial Phase is completed.

Review and Create Subscription Plans

After filling out the previous section, you can create the Subscription Plan.

Creating a Subscription from a Subscription Plan

You have two options to create a Subscription from a Subscription Plan.

From the Subscription Plan Details Page

Navigate to a Subscription Plan
Click on the Actions dropdown on the top right
Select Create Subscription
Enter the buyer information and complete the form.

From the Subscriptions List Page

Click Billing > Subscriptions.
Click Create Subscription
Unselect Create subscription without a plan
Select a Subscription Plan
Enter the buyer information and complete the form.

Creating a Subscription Plan via API

To create a Subscription Plan, include:

The ID of the Merchant that the Subscription Plan will be linked_to
The amount and currency of the Subscription Plan
Additional details of the Subscription Plan. For detailed API information, please see our Subscriptions Plans API Reference.

At this time, only APPROVED Merchants with one of the following processors can create Subscription Plans:

DUMMY_V1
FINIX_V1

Create Subscription Plan Request

curl https://finix.sandbox-payments-api.com/subscription_plans \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -u USksBJMwkNUz5GyxPevL2yFY:71b641c1-861d-435b-9a9c-532760731c5e \
    -X POST \
    -d '{
        "amount": 1099,
        "currency": "USD",
        "plan_name": "Bronze Plan",
        "description": "Test",
        "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
        "linked_type": "MERCHANT",
        "billing_interval": "MONTHLY",
        "billing_defaults": {
            "collection_method": "BILL_AUTOMATICALLY"
        },
        "trial_defaults": {
            "interval_type": "MONTH",
            "interval_count": "1"
        }
    }'

Create Subscription Plan Response

{
    "id": "subscription_plan_cd92Tzs8qNPbNbd2JMhN5",
    "created_at": "2024-07-13T00:28:58.42Z",
    "updated_at": "2024-07-13T00:28:58.42Z",
    "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
    "linked_type": "MERCHANT",
    "billing_interval": "MONTHLY",
    "nickname": null,
    "plan_name": "Bronze Plan",
    "description": "Test",
    "amount": 1099,
    "currency": "USD",
    "billing_defaults": {
        "collection_method": "BILL_AUTOMATICALLY",
        "send_invoice": false,
        "send_receipt": false
    },
    "trial_defaults": {
        "interval_type": "MONTH",
        "interval_count": 1
    },
    "state": "ACTIVE",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/subscription_plans/subscription_plan_cd92Tzs8qNPbNbd2JMhN5"
        }
    }
}

Creating a Subscription from a Subscription Plan via the API

To create a Subscription from a Subscription Plan, specify the subscription_plan_id in the request body of a Subscription.

Example

API Definition

post /subscriptions

Sandbox server: https://finix.sandbox-payments-api.com/subscriptions

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "buyer_details": {
      "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
      "instrument_id": "PImXAVgkKVshKWWHUk4xXbve"
    },
    "linked_to": "MUxdJCr9xTMnmt1vGUAqV9z4",
    "linked_type": "MERCHANT",
    "subscription_plan_id": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
  }'

Example

API Definition

Subscription - From Subscription Plan

{
  "id" : "subscription_cA2DeRbnuvrPQHK2HooT7",
  "created_at" : "2026-05-14T14:46:30.73Z",
  "updated_at" : "2026-05-14T14:46:30.73Z",
  "amount" : 19900,
  "application_id" : "APc9vhYcPsRuTSpKD9KpMtPe",
  "billing_interval" : "MONTHLY",
  "buyer_details" : {
    "identity_id" : "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id" : "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods" : [ {
      "type" : "EMAIL",
      "destinations" : [ "abc@test.com" ]
    }, {
      "type" : "SMS",
      "destinations" : [ "2348765431" ]
    } ],
    "shipping_address" : {
      "city" : "Middletown",
      "country" : "USA",
      "line1" : "324 Oak Avenue",
      "line2" : "Apartment 7",
      "postal_code" : "19734",
      "region" : "DE"
    }
  },
  "canceled_via" : null,
  "currency" : "USD",
  "expires_at" : "2027-08-15T22:42:05.490Z",
  "first_charge_at" : "2026-08-15T22:42:05.49Z",
  "has_usage_based_plan" : false,
  "linked_to" : "MUxdJCr9xTMnmt1vGUAqV9z4",
  "linked_type" : "MERCHANT",
  "next_billing_date" : {
    "year" : 2026,
    "month" : 8,
    "day" : 15
  },
  "nickname" : "Finflix Gold Package",
  "start_subscription_at" : "2026-08-15T22:42:05.490Z",
  "state" : "NOT_STARTED",
  "subscription_details" : {
    "collection_method" : "BILL_AUTOMATICALLY",
    "send_invoice" : false,
    "send_receipt" : false,
    "trial_details" : null,
    "discount_phase_details" : null,
    "notification_preferences" : {
      "send_confirmation" : false
    }
  },
  "subscription_link_id" : null,
  "subscription_phase" : "NONE",
  "subscription_plan_id" : "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE",
  "tags" : {
    "order_number" : "21DFASJSAKAS"
  },
  "total_billing_intervals" : 12,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/subscriptions/subscription_cA2DeRbnuvrPQHK2HooT7"
    }
  }
}

Creating a Subscription from a Subscription Plan via the API with a Start Date

You can specify a start date for a Subscription that uses a Subscription Plan.

To do so, include a start_subscription_at timestamp in the request body:

Example

API Definition

post /subscriptions

Sandbox server: https://finix.sandbox-payments-api.com/subscriptions

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "buyer_details": {
      "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
      "instrument_id": "PImXAVgkKVshKWWHUk4xXbve"
    },
    "linked_to": "MUxdJCr9xTMnmt1vGUAqV9z4",
    "linked_type": "MERCHANT",
    "start_subscription_at": "2026-08-15T22:42:05.490Z",
    "subscription_plan_id": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
  }'

Example

API Definition

Subscription - From Subscription Plan - Future Start Date