Upgrading or Downgrading Plans with API

Introduction

This guide explains how to implement subscription upgrade and downgrade functionality in your SaaS application using Fungies as your Merchant of Record payment solution. We'll cover both dashboard-based management and API-based implementation, with a focus on integrating this functionality into your existing SaaS application.

Prerequisites

Before implementing subscription upgrades and downgrades, ensure you have:

1. Created a subscription product in Fungies

2. Configured multiple plans with the same interval periods (days/weeks/months)

3. Generated API keys for programmatic access

Dashboard-Based Subscription Management

Upgrading or Downgrading Subscriptions Manually

We provide a straightforward way to manage subscriptions through the Dashboard:

1. Log in to your Fungies Dashboard

2. Navigate to the Subscriptions section

3. Find the customer's subscription you want to modify

4. Click on "Manage subscription"

5. Select a different plan from the dropdown menu

6. Confirm the change

You can Upgrade/Downgrade customer subscription within the Dashboard

When a subscription is upgraded or downgraded:

• Customers receive an email with updated terms

• If upgraded, they are charged a prorated amount for the difference

• If downgraded, the amount is deducted from their next invoice

Important Considerations

• Only plans with the same interval periods can be switched between (e.g., monthly to monthly)

• Proration is handled automatically by Fungies

• Changes take effect immediately or at the next billing cycle, depending on your configuration

API-Based Subscription Management

For a seamless experience within your SaaS application, you can implement subscription upgrades and downgrades programmatically using the Fungies API.

Upgrading or Downgrading customer Subscriptions can be done via API

Update Subscription Endpoint

The key endpoint for managing subscription upgrades and downgrades is:

PATCH https://api.fungies.io/v0/subscriptions/{subscriptionIdOrNumber}/update

Required Headers

Content-Type: application/json
x-fngs-public-key: <your-public-api-key>
x-fngs-secret-key: <your-secret-api-key>

Request Body Parameters

{
  "prorationBehavior": "none",
  "items": [
    {
      "name": "Premium Plan",
      "unitPrice": 10000,
      "currency": "USD",
      "quantity": 1,
      "offerId": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Key parameters:

• prorationBehavior: Controls how proration is handled

  • "none": No proration is calculated

  • "create_prorations": Creates prorated credits or charges

  • "always_invoice": Always generates an invoice for the proration

• items: Array containing the new subscription plan details

  • name: Display name of the plan

  • unitPrice: Price in smallest currency unit (e.g., cents)

  • currency: Three-letter currency code

  • quantity: Number of units

  • offerId: Unique identifier of the plan/offer to upgrade/downgrade to

Retrieving Subscription Information

Before updating a subscription, you may need to retrieve the current subscription details:

GET https://api.fungies.io/v0/subscriptions/{subscriptionId}

This endpoint returns detailed information about the subscription, including its current plan, billing cycle, and status.

Handling Responses

A successful update will return a 200 status code with the updated subscription details. Error responses (400) will include information about what went wrong, such as invalid parameters or authentication issues.