Handling Subscription Upgrades and Downgrades (Proration) via API

Managing subscription lifecycles is a critical part of running a SaaS or membership business. When a customer upgrades or downgrades their plan in the middle of a billing cycle, 4Geeks Payments automatically handles the proration calculations. This ensures your customers are charged fairly—paying only for the time they used on each plan—without you needing to perform manual math or issue separate refunds.

This guide explains how to programmatically upgrade or downgrade a subscription using the 4Geeks Payments API and how the system calculates the resulting prorated charges or credits.

Prerequisites

Before you begin, ensure you have the following:

• A 4Geeks Payments Account: You must have an active merchant account.
• API Keys: Your sk_test_ (for sandbox) or sk_live_ (for production) keys.
• Subscription ID: The unique identifier (UUID) of the subscription you wish to modify.
• Plan ID: The unique identifier of the new plan the customer is moving to.

Start Accepting Online Payments in 5 Minutes

Get paid faster on your website, your platform or social media via our payment link. Multiple currencies. 100% secure. 5-min activation process.

Learn more

How to Update a Subscription

4Geeks Payments simplifies changes by treating upgrades and downgrades as an update to the existing subscription object. The system automatically detects the price difference and applies the necessary proration.

Step 1: Retrieve the Current Subscription

First, ensure you have the correct subscription_id for the customer. You can list all subscriptions for a specific customer to find the active one.

Endpoint: GET https://api.4geeks.io/v1/subscriptions/?customer={customer_id}

Step 2: Update the Subscription Plan

To trigger an upgrade or downgrade, send a PUT request to the specific subscription endpoint with the new plan_id.

Endpoint: PUT https://api.4geeks.io/v1/subscriptions/{subscription_id}/

Request Example:

curl -X PUT "https://api.4geeks.io/v1/subscriptions/sub_123456789" \
  -u "sk_test_YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_new_tier_id"
  }'

Tip: By default, 4Geeks Payments calculates proration immediately. If you want to change the plan without proration (e.g., waiting until the next cycle to switch), you may need to cancel the current subscription at the period end and schedule a new one, though the PUT method is preferred for continuity.

Step 3: Verify the Proration Invoice

The API response will include details of the updated subscription. For upgrades, the system typically generates an immediate invoice for the prorated difference. For downgrades, a credit is usually added to the customer's balance to be applied to future invoices.

Response Example (Simplified):

{
  "id": "sub_123456789",
  "status": "active",
  "plan": {
    "id": "plan_new_tier_id",
    "name": "Pro Plan",
    "amount": 50.00
  },
  "current_period_end": "2023-12-01T00:00:00Z",
  "latest_invoice": {
    "id": "inv_987654321",
    "amount_due": 15.50,
    "status": "paid"
  }
}

Common Use Cases

Scenario 1: Mid-Cycle Upgrade (Immediate Charge)

Context: A customer is on a $10/month Basic Plan. Halfway through the month (Day 15), they need more features and upgrade to the $30/month Pro Plan.

How 4Geeks Payments handles it:

1. Unused time credit: The system calculates the unused time on the Basic plan (approx. $5.00 credit).
2. New plan charge: The system calculates the remaining time on the Pro plan for this cycle (approx. $15.00 charge).
3. Result: The customer is immediately invoiced for the difference ($10.00). Their billing cycle date usually remains the same.

Scenario 2: Mid-Cycle Downgrade (Credit Applied)

Context: A customer is on the $30/month Pro Plan. Halfway through the month, they realize they don't need all features and downgrade to the $10/month Basic Plan.

How 4Geeks Payments handles it:

1. Unused time credit: The customer is credited for the remaining 15 days of the Pro plan (approx. $15.00).
2. New plan charge: The system charges for the remaining 15 days of the Basic plan (approx. $5.00).
3. Result: The customer has a $10.00 credit remaining. 4Geeks Payments stores this in the customer's balance, and it will be automatically deducted from their next month's invoice.

Troubleshooting

• Issue 1: The API returns a 404 Not Found error.
  • Solution: Verify that the subscription_id and plan_id are correct. Ensure you are not mixing "Test" mode IDs with "Live" mode keys. A test plan cannot be applied to a live subscription.
• Issue 2: The upgrade invoice failed payment (402 Payment Required).
  • Solution: If an upgrade requires an immediate charge (proration) and the customer's card is declined, the subscription update might fail or remain pending. Check the latest_invoice status in the response. You may need to prompt the user to update their payment method via the Customer Portal.
• Issue 3: I don't see a charge for the downgrade.
  • Solution: This is expected behavior. Downgrades typically result in a credit balance, not a refund to the card. You can verify this by checking the Customer object's balance field via the API or the 4Geeks Console.

FAQs

Next Steps:

• Explore the full API Reference for detailed field definitions.
• Learn about 4Geeks AI Agents to automate customer support regarding billing questions.