Fungies.io Help Center
  • 🙌Getting Started
  • Customize your online store
    • General Settings
    • Header
    • Footer
    • Add New Page
    • Add Page Section
    • Text Section
    • Image Section
    • Video Section
    • Gallery Section
    • Points Section
    • Slider Section
    • Recent Products Section
    • Custom Style
  • Add Subscription Product
  • Add Digital Downloads
  • Add Game Keys
  • Add Mobile Game Assets
  • Variants of the product
  • 🛠️Workspace Settings
    • Connect your Stripe account
    • Sandbox Mode
    • Team Management
  • 🧮Store Settings
    • Publish your store
    • Previewing The Store
    • Edit Explore / Search Page (Built-in)
    • Edit Product Page (Built-in)
      • Customize Review Categories
    • Set up Custom Domain
      • Migrating your domain to Cloudflare
  • Tax-inclusive Pricing
  • 🤑Getting Paid
    • Test Payments
    • Checkout Choice
      • Hosted Checkout
      • Overlay Checkout
      • Embedded Checkout
    • Global Availability
    • Customer Payment Methods
      • PayPal Settings
    • Billing Details
    • Payouts
    • Editing Statement Descriptor
    • Transactions Reports
    • Example React checkout
  • 👨‍💻FOR SAAS DEVELOPERS
    • Hosted Checkout (more payment methods)
    • Editing and Pausing Subscriptions
      • Downgrading / Upgrading Subscriptions
    • Creating Plans
    • Free Trials and Custom Intervals
    • Redirecting After Purchase
    • Using Webhooks
    • Types of Webhooks
      • Payment Success
      • Payment Refunded
      • Payment Failed
      • Subscription Created
      • Subscription Interval
      • Subscription Updated
      • Subscription Cancelled
    • Getting Started with the API
    • Orders APIs
      • Managing Orders through API
      • Orders List
      • Cancel Order
      • Update Order
    • Managing Subscriptions through API
    • Managing and Creating Users through API
    • Customizing Subscription Confirmation Page
    • Using CustomFields to parse data from your Software / App
      • Parse e-mails from your Software directly to checkout URL
  • Additional charges on top of Subscriptions
  • Upgrading or Downgrading Plans with API
  • Using Fungies.js npm package
    • Next.js 15 integration guide
  • 🎮For Game Developers
    • Orders
    • Platform Fees
    • Users list
    • Integrating with Game's Back-end
    • Customizing Purchase Confirmation Page
    • Webhooks
  • 💲Selling
    • Payment history
    • Selling FREE products
    • Managing Game Keys
    • Managing Game Assets
    • Pricing
    • Fulfillment of Orders
    • Prohibited Business and Products
    • Invoices and Receipts
    • Google Merchant Center XML Feed
    • SEO Sitemap
  • ✍️User Portal
    • Portal Access & Branding
  • Core Features
    • Subscription Management
    • Account Management
    • Order History
    • Digital Key Management
    • Digital Downloads
  • 🚀Marketing
    • Integrations
      • Google Tag Manager
      • Google Merchant Center
      • Trustpilot
      • Google Analytics (via Google Tag Manager)
    • SEO
    • Discount Codes
    • Pricing Localization
    • Language Localization
    • E-mail Marketing
  • 💰Billing
    • Plans and Usage
    • Invoices
    • Payment Methods
  • 🤩For End-Users
    • How to manage your Subscription?
    • How to buy a Game Key?
    • How to buy a Mobile Game Asset?
    • Getting your product
    • Steam key activation
    • Searching for games
    • Product details page
    • Order details
    • Refunds and chargebacks
  • 🗃️Other
    • FAQ
    • Roadmap
    • Product Changelog
  • 📃Legal
    • General Terms of Use
    • SaaS Terms of Use
    • Privacy Policy
    • Cookies and Tracking
Powered by GitBook
On this page
  • Introduction
  • Prerequisites
  • Dashboard-Based Subscription Management
  • API-Based Subscription Management

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

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.

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.

PreviousAdditional charges on top of SubscriptionsNextUsing Fungies.js npm package

Last updated 1 month ago

You can Upgrade/Downgrade customer subscription within the Dashboard
Upgrading or Downgrading customer Subscriptions can be done via API