Skip to content

Handling Subscription Upgrades and Downgrades with Proration in 4Geeks Payments

🤖 Explain with AI

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.
  • Access to 4Geeks Console: Log in to manage and verify changes.

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

  1. Log in to the 4Geeks Console.
  2. Navigate to the Payments module.
  3. Select Subscriptions from the sidebar.
  4. Search for the customer by email or ID to list their active subscriptions.
  5. Note the subscription_id for the one you want to update.

Alternatively, use the API to fetch subscriptions programmatically:

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

Step 2: Update the Subscription Plan

Send a PUT request to the subscription endpoint with the new plan_id. This triggers the proration logic.

  1. Prepare your API request with the appropriate key.
  2. Include the new plan details in the request body.

Request Example (using cURL):

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"
  }'
  1. Submit the request. The system calculates proration immediately for the current billing cycle.

Tip: For upgrades, expect an immediate invoice. For downgrades, a credit applies to future invoices. Avoid mixing test and live mode IDs to prevent errors.

Step 3: Verify the Proration Invoice

  1. Check the API response for the updated subscription details, including the latest_invoice.
  2. In the 4Geeks Console, go to Invoices to view the new prorated invoice.
  3. Confirm the status (e.g., “paid” or “open”) and amount due.

Response Example (Simplified JSON):

{
  "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"
  }
}

Best Practice: Monitor webhooks for events like invoice.created or invoice.payment_succeeded to automate notifications or updates in your system.

Common Use Cases

Scenario 1: Mid-Cycle Upgrade (Immediate Charge)

A customer on a $10/month Basic Plan upgrades to the $30/month Pro Plan halfway through the month.

  • The system credits ~\(5 for unused Basic time and charges ~\)15 for remaining Pro time.
  • Result: Immediate $10 invoice. No service interruption, and the billing cycle stays the same.

This keeps customers happy by providing instant access to new features while ensuring fair billing.

Scenario 2: Mid-Cycle Downgrade (Credit Applied)

A customer downgrades from $30/month Pro to $10/month Basic midway.

  • Credits ~\(15 for unused Pro time and charges ~\)5 for remaining Basic time.
  • Result: $10 credit stored in the customer’s balance, applied to the next invoice.

Ideal for retaining customers who need flexibility without overpaying.

Troubleshooting

Issue 1: API Returns 404 Not Found

  • Cause: Incorrect subscription_id or plan_id.
  • Solution: Double-check IDs in the 4Geeks Console. Ensure test/live mode consistency.

Issue 2: Upgrade Invoice Fails (402 Payment Required)

  • Cause: Customer’s card declines the prorated charge.
  • Solution: Check latest_invoice status. Prompt the customer to update their payment method via the customer portal link.

Issue 3: No Charge Visible for Downgrade

  • Cause: Downgrades create credits, not immediate refunds.
  • Solution: Verify the customer’s balance in the API or 4Geeks Console. Credits apply automatically to future bills.

Conclusion

With 4Geeks Payments, handling subscription changes is seamless and automated, reducing administrative overhead and improving customer satisfaction. Implement these steps to manage upgrades and downgrades efficiently. For more advanced automation, explore integrating with 4Geeks AI Agents.

Additional Resources