Skip to main content

​
Overview

Flexprice allows you to change subscription plans seamlessly with automatic proration calculations, billing adjustments, and invoice generation. Whether you’re upgrading to a higher tier or downgrading to a more cost-effective plan, the system handles all the complex billing logic for you.

​
Key Features

  • Automatic Proration: Calculate credits and charges for unused time
  • Immediate Billing: Generate invoices for plan changes instantly
  • Preview Changes: See the impact before making changes
  • Flexible Billing: Support for different billing cycles and periods
  • Audit Trail: Complete history of all subscription changes

​
How It Works

​
The Process

  1. Preview the Change: Use the preview endpoint to see the financial impact
  2. Execute the Change: Confirm the change to apply it immediately
  3. Automatic Processing: The system handles proration, billing, and invoice generation
  4. Subscription Update: Your subscription is updated to the new plan

​
API Endpoints

​
API Reference

​
1. Preview Subscription Plan Change

Endpoint: POST /subscriptions/{id}/change/preview Preview the financial impact of changing a subscription plan before making the actual change.

​
Request Fields

​
2. Execute Subscription Plan Change

Endpoint: POST /subscriptions/{id}/change/execute Execute the subscription plan change after previewing the impact.

​
Request Fields

Uses the same SubscriptionChangeRequest as the preview endpoint.

​
Field Explanations

​
Billing Configuration

  • billing_cadence: Whether this is a one-time charge (ONETIME) or recurring billing (RECURRING)
  • billing_cycle:
    • anniversary: Billing starts from the subscription start date
    • calendar: Billing aligns with calendar periods (e.g., monthly on the 1st)
  • billing_period: How often the customer is billed (daily, weekly, monthly, etc.)
  • billing_period_count: How many periods the subscription lasts (e.g., 12 for annual)

​
Proration Behavior

  • create_prorations: Calculate and apply credits/charges for unused time
  • none: No proration

​
What Happens During a Plan Change

When you change your subscription plan, Flexprice:
  1. Archives the old subscription and marks it as cancelled
  2. Calculates proration for unused time on the current plan
  3. Creates a new subscription with the target plan
  4. Generates an invoice with credits and charges

​
What Happens to Addons

Because this plan change cancels the old subscription, its addons are cancelled with it and are not carried to the new subscription; re-attach them after the change. The swap-in-place plan change (POST /subscriptions/{id}/change/v2/execute, with a matching /change/v2/preview) instead keeps addon associations by default: its entity_policies.addons object sets a default_behaviour of carry or drop, with per-association overrides. Dropped addons end at the change, and are credited for unused time only when the change uses proration_behavior: "create_prorations" or billing_period_behaviour: "anchor_at_effect".