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. This in concept 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 changin 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 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.

Typicially SaaS companies want to downgrade or cancel subscriptions at the end of the billing period to avoid refunds and revenue recognition issues. While upgrading a subscription is expected by customers to take effect immediately.

#1. At the end of the billing period

Great for downgrading a subscription. We recommend to use 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. With schedling the subscription edit to the end of the billing period you can keep providing the service at the old plan until the end of the billing period and only make the changes at the beginning of the next period. So what the customer already paid for will be honored and no changes will be made to the service until the next period.

#2. Immediatly

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 the chnage to take effect immediately. We recommend to edit subscriptions with immediate mode when you want to upgrade a subscription. Inside the immediate mode you can choose between partial edit, restart billing period or pro-rate prices to have 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 the following:

• If has a flat fee, it will invoice the fee immediately for the full price independent of remaining billing period.
• If has 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 has a metered entitlements, 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. The subscription in the future 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.