Skip to main content
A plan is a collection of pricing information that describes how you want to bill your customers for your product. Often times, a plan corresponds to what you’ve listed on your pricing page, but it can also be used to model enterprise agreements.
Why versioned pricing matters: Orb treats pricing configurations as versioned objects. Product and Finance teams can test new pricing models using Simulations against real usage data before deploying. When you migrate customers to new pricing, Orb’s diff engine ensures consistency across thousands of subscriptions atomically. If needed, pricing changes can be rolled back because billing is always a deterministic query.

​
Creating your first plan

Let’s package the “API Requests” price from the catalog guide into a plan:
  1. Navigate to the “Plans” tab in the “Pricing & Packaging” menu.
  2. Click ”+ New plan” in the top right.
  3. Click “Add price” and choose the option to “Select an existing price from Pricebook”. Select the “API Requests” price you created.
  4. Repeat to add the “Platform access fee” price, along with any other catalog prices that belong in the plan.
  5. Click “Next”, name your plan “Basic”, and click “Publish”.
You should see the newly published plan in the plans tab of the Orb dashboard. Because the plan references pricebook prices rather than owning private copies, your catalog stays the single source of truth. The same “API Requests” price can appear in your Basic and Pro plans as one shared definition, and anyone on your team can see exactly which plans use it.
Although the plan references a specific catalog price, Orb allows adding overrides for a customer when creating a subscription. This allows you to offer discounts or special terms to specific customers while still maintaining a single plan definition and keeping your product catalog simple.

​
Reuse the price in a second plan

Most catalogs don’t stop at one plan, and this is where the centralized catalog pays off. Create a “Pro” plan the same way: click ”+ New plan”, click “Add price”, select the same “API Requests” price from the pricebook, then name the plan “Pro” and publish. Open the “API Requests” product in “Pricing & Packaging” and you can see both Basic and Pro using the price. Both plans bill from one shared definition rather than two private copies that drift apart, and before you touch a price, you always know exactly which plans it affects. This quickstart starts from the plan, but you can also work from the pricebook side, attaching a price to several plans in one step. See Building your product catalog and pricebook for all three entry points for getting catalog prices into plans.

​
Creating your plan via API

Each entry in the prices array either references an existing catalog price by price_id or defines a new price inline under a price key. Using the two price IDs from the catalog guide:
In the response, the plan’s prices carry the same IDs you passed in: the plan references your shared catalog prices rather than creating private copies. Reusing a price in another plan is the same call with the same price_id; create the “Pro” plan this way and both plans’ responses carry the identical price ID. The plan’s currency must match the currency of every referenced price, and you can mix price_id references with inline price definitions in a single request.

​
Additional pricing models

Unit pricing and fixed fees are just two of the models Orb supports out of the box. For a complete tour of the pricing models available in the platform, see the price configuration guide. For more depth on how plans themselves are structured, including phases and trials, see configuring plans. For per-region rates or other grouped pricing on a single metric, see the dimensional pricing guide. Let’s start using the Basic plan to set up subscriptions for our customers!