Edit

#Changing Plans

If a plan no longer suits a customer, instead of editing their current Subscription (resulting in a Custom Subscription), you can change them to an entirely different plan. Conceptually, this is equivalent to canceling their current subscription and starting a new one with the new plan, but without any interruption in service.

Example: Change a subscription to a new plan

const response = await openmeter.subscriptions.change('subscription-id', {
  name: 'New Subscription Name',
  plan: { key: 'pro' },
  timing: 'next_billing_cycle',
});

The inputs are the same as when creating a subscription, and the response will contain both the current (now canceled) and the new subscription.

#Customizing a Subscription

Subscriptions can be edited to accommodate changes in customer needs. You can add or remove any SubscriptionItem that is currently active or scheduled to be active in a later Phase. This effectively means you can change any property of a subscription. The only limitation is that you cannot change the past. You cannot change SubscriptionItems that have since deactivated, and when changing currently active items, the changes cannot be retroactive.

Example: Add a new SubscriptionItem to a subscription

const newRateCard: RateCard = {
  // ... contents
};

const updated = await openmeter.subscriptions.edit('subscription-id', {
  timing: 'next_billing_cycle',
  customizations: [
    { op: 'add_item', phaseKey: 'default', rateCard: newRateCard },
  ],
});

• timing: The timing of the edit. Use immediate for immediate activation. Use next_billing_cycle to schedule the edit for the next billing cycle, only if the subscription is aligned.
• customizations: An array of customizations to apply to the subscription. The Edit API uses a JSONPatch-inspired syntax to modify the subscription. In this case, we're adding a new SubscriptionItem to the default phase.

#Edit Timing and Modes

When you are editing a subscription, you can choose between different modes to execute the changes. This is important because certain subscription changes can impact the billing cycle, entitlement limits, and invoicing.

Typically, SaaS companies want to downgrade or cancel subscriptions at the end of the billing period to avoid refunds and revenue recognition issues, while customers expect upgrades to take effect immediately.

#1. At the end of the billing period

Great for downgrading a subscription. We recommend using this mode when you want to avoid any changes in the provided service before the end of the billing period.

For example, a customer downgrading to a lower-priced or free plan. By scheduling the subscription edit for the end of the billing period, you can keep providing the service at the old plan until the period ends, and only apply the changes at the start of the next period. This way, what the customer already paid for will be honored, and no changes will be made to the service until the next period.

#2. Immediately

Great for upgrading a subscription. When a customer wants to upgrade their subscription to a higher plan with more features or limits, it's expected that the change takes effect immediately. We recommend editing subscriptions with immediate mode when you want to upgrade a subscription. Inside immediate mode, you can choose between partial edit, restart billing period, or pro-rate prices for further control over invoicing and entitlement changes.

#2.1. Partial Edit

With partial edit, OpenMeter will only edit the rate card in the subscription you changed. The rest of the subscription, including the billing cycle, will stay the same.

The updated or added rate card will behave as follows:

• If it has a flat fee, it will invoice the fee immediately for the full price regardless of the remaining billing period.
• If it has a usage-based price, it will be billed at the end of the period, but there will be two line items on the invoice:
  • One for the time between the beginning of the period and the change's time with the old price.
  • One for the remaining time in the period for the new price.
• If it has a metered entitlement, only the entitlement limit will change and the usage period will be accounted for the entire billing period.

#2.2. Restart Billing Period

Restart billing period will restart the billing period for the subscription. This means that the billing cycle will be reset to the date of the change and all the prices and metered entitlements will restart. In the future, the subscription will follow this new billing anchor.

#2.3. Pro-Rate Prices

With pro-rate prices, OpenMeter will pro-rate the price of the new rate card for the remaining billing period. This means that the price will be adjusted proportionally for the remaining billing period.