> For the complete documentation index, see [llms.txt](https://help.fungies.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.fungies.io/upgrading-or-downgrading-plans-with-api.md).

# 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

<figure><img src="/files/sSH2NgjhZ4n4btUNCPMZ" alt=""><figcaption><p>You can Upgrade/Downgrade customer subscription within the Dashboard</p></figcaption></figure>

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.

<figure><img src="/files/NtCfFVEwTDviZdUTtEIy" alt=""><figcaption><p>Upgrading or Downgrading customer Subscriptions can be done via API</p></figcaption></figure>

#### 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

```json
{
  "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.