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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.fungies.io/upgrading-or-downgrading-plans-with-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.