Updating a Subscription Plan on an Existing Subscription

Learn how to update Subscription Plans for an existing subscription.

Overview

Finix supports the ability to upgrade or downgrade a customer’s subscription between different plans — for example, moving from the Basic plan to the Enterprise plan, or vice versa.

This can be done at any time using the Subscriptions API. Plan changes are applied immediately, and billing is automatically adjusted based on the timing and direction of the change.

How Plan Changes Work

When a subscription’s plan is changed:

• The new plan takes effect immediately. As soon as the change is made, the customer is moved to the new plan.
• The new plan picks up where the old one left off. The subscription continues from the same point in time; for example, if you’re 60 days in, the new plan also starts at day 60.
• Billing is prorated based on the change. Finix automatically adjusts billing depending on whether the new plan is more or less expensive than the previous one:
  • If upgrading to a more expensive plan (e.g., from Basic to Enterprise): A prorated charge is immediately applied for the remainder of the billing period at the new plan’s rate.
  • If downgrading to a less expensive plan (e.g., from Enterprise to Basic): A prorated credit is issued for the unused portion of the previous plan.
• The billing cycle remains unchanged. This means that the subscription continues to follow its original billing schedule.
• If the current subscription is still in an initial phase (such as TRIAL or DISCOUNT), and the new plan has a longer initial phase, the remaining initial phase will be extended to match the new plan’s phase duration.
• If the current subscription is in an initial phase but the new plan does not include an initial phase, the trial ends immediately and the subscription transitions into the next phase of the new plan (typically the EVERGREEN phase).

Examples

If a customer on the Basic plan upgrades to the Enterprise plan on June 10, the Enterprise plan takes effect immediately on June 10. A prorated charge for the remaining days of the billing period will occur right away.

If a customer downgrades from the Enterprise plan to the Basic plan on the same date, the Basic plan takes effect immediately, and a credit is applied for the remaining, unused portion of the Enterprise plan.

Using the Finix API

This feature is currently only available using our API.

To update an existing Subscription to a new Subscription Plan, you can simply use a PUT to replace the previous subscription_plan_id with a new subscription_plan_id.

curl "https://finix.sandbox-payments-api.com/subscriptions/subscription_cdhqdXjTQfg62wHzJ41g5" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '
  {
    "subscription_plan_id": "subscription_plan_cdgZcXBNDwWcqC4CwgGRS"
  }'

When this request is run, we will return a new response that will override the previous settings for the subscription.

Below is a set of the impacted fields:

{
  "id" : "subscription_cdhqdXjTQfg62wHzJ41g5",
  "created_at" : "2024-06-05T22:42:05.49Z",
  "updated_at" : "2024-06-05T22:42:05.49Z",
  "first_charge_at" : "2024-07-05T22:41:46.00Z",
  "next_billing_date" : {
      "year" : 2024,
      "month" : 7,
      "day" : 22
  },
  "amount" : 10000,  <- potentially impacted field, will need to be updated
  "buyer_details" : {
    "identity_id" : "IDeDVrf2ahuKc9Eg5TeZugvz",
      "instrument_id" : "PIeDVrf2ahuKc9Eg5TeZugvb",
      "requested_delivery_methods" : []
  },
  "currency" : "USD",
  "linked_to" : "MUeDVrf2ahuKc9Eg5TeZugvs",
  "linked_type" : "MERCHANT",
  "nickname" : "My Gym Membership",
  "billing_interval" : "MONTHLY",
  "subscription_details" : {
    "collection_method" : "BILL_AUTOMATICALLY",
    "send_invoice" : false,
    "send_receipt" : false,
    "trial_details" : {
      "interval_type" : "DAY",                                        <- potentially impacted field, will need to be updated
      "interval_count" : 30,                                          <- potentially impacted field, will need to be updated
      "trial_started_at": "2024-06-05T22:41:46.00Z",                  <- potentially impacted field, will need to be updated
      "trial_expected_start_at": "2024-06-05T22:41:46.00Z",           <- potentially impacted field, will need to be updated
      "trial_expected_end_at" : "2024-07-05T22:41:46.00Z"             <- potentially impacted field, will need to be updated
    },
    "discount_phase_details": {
      "amount": 1000,                                                 <- potentially impacted field, will need to be updated
      "billing_interval_count": 3                                     <- potentially impacted field, will need to be updated
    }
  },
  "subscription_phase" : "TRIAL",                                     <- potentially impacted field, will need to be updated
  "state" : "ACTIVE",
  "subscription_plan_id" : "subscription_plan_cdgZcXBNDwWcqC4CwgGRS", <- new plan id is here
  "start_subscription_at" : "2024-06-05T22:42:05.49Z",
  "total_billing_intervals": null,
  "expires_at": null,
  "canceled_via": null,
  "tags": {},
  "_links" : {
    "self" : {
      "href" : "http://localhost/subscriptions/subscription_5MRiVJdsK8iJNT9mKQ6WEk"
    }
  }
}

Common Subscription Plan Change Scenarios