Subscription

An OpenMeter subscription defines a customer's access and pricing, linking them to a pricing model based on either a pre-defined plan or a custom configuration. Subscriptions are the foundation of your billing relationship in OpenMeter.

Subscriptions act as the bridge between your Customers, their chosen Plans (or custom pricing), and the Meters tracking their resource consumption. This provides a low-effort, automated way to translate raw usage data into billable amounts. While you can manually configure billing and pricing for each customer, subscriptions offer a streamlined and scalable solution. With subscriptions, you can easily manage customer access, tailor pricing models to specific customer needs, and gain insights into usage patterns to optimize your pricing strategy.

Subscriptions can be based on pre-defined plans, offering consistent pricing and entitlements, or configured with tailored settings for specific customers requiring unique access and rates. This configuration is defined at subscription creation time.

#Getting Started

You can start a subscription using by assining a plan to a customer or by creating a custom subscription. For the exmples below, we'll use the OpenMeter TypeScript SDK.

Example: Create a subscription from a plan

const subscription = await openmeter.subscriptions.create({
  customerId: 'customer-id',
  timing: 'immediate'
  plan: { key: 'pro' },
});

• customerId: The ID of the customer to which the subscription will be assigned.
• timing: The timing of the subscription. Can be immediate for immediate activation or a Date object for a future activation.
• plan: The plan to be assigned to the subscription. The latest published version if the plan will be used.

Example: Create a custom subscription

const customPlan: CustomPlanInput = {
  name: "Custom Subscription",
  currency: "USD",
  phases: [
    // ...phases and rate cards
  ],
}
 
const subscription = await openmeter.subscriptions.create({
  customerId: 'customer-id',
  timing: 'immediate'
  customPlan: customPlan,
});

• customPlan: A custom plan object that defines the pricing and entitlements for the subscription. Its syntactically similar to a PlanCreate object with the key field removed.

#Subscription Contents

OpenMeter subscriptions have the same structure as plans, but some templating fields are changed to concrete values.

#Subscription Alignment

OpenMeter allows for all SubsctiptionItems to be billed separately, enabling a wide range of advanced pricing scenarios. Though this behavior is desirable for advanced use cases, it can lead to complex billing structures. To simplify billing, OpenMeter can align all SubscriptionItems to the same billing cycle. This ensures that all items are billed at the same time, making it easier to manage and understand your billing. By default, all Subscriptions are created aligned. You can opt out of this behavior to bill separately.

#Editing Subscriptions

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.

#Grandfathering

As you make changes to your pricing and publish new versions of your plans, by all existing subscriptions will stay on the old version. Once you're ready to move existing customers to the new version, you can use the migrate API to move them to the new version.

Example: Migrate a subscription to a new plan version

const response = await openmeter.subscriptions.migrate('subscription-id', {
  targetVersion: 3,
}

• targetVersion: The version of the plan to migrate the subscription to, can be any version later than the current one. If the version is not specified, the latest published version will be used.

#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.