Creating & managing plans in Billforward

Plans are the component that define pricing.

When creating a plan, you can decide details like billing period, the currency used, the volume discounting, etc. In a nutshell, plans are a representation of what an organisation is selling.

A plan lives at organisation level. This means a plan is not specific to a certain customer or subscription. It can be reused as many times as you wish, and there are no restrictions on how many plans an organisation can have. Having said that, no one stops you from using a plan only for a specific customer ?

Plan API

There are two main endpoints that are responsible for managing your plans:

GET /plans: https://app-sandbox.billforward.net/#/api/method/plans/GET?path=~2Fplans~2F%7Bpath:%20.%2B%7D

PUT /plans: https://app-sandbox.billforward.net/#/api/method/plans/PUT?path=~2Fplans

The first one is responsible for retrieving the plans, the second creates and updates a set of plans.

Billforward sees plans as mere templates. A plan doesn’t have a lifecycle, and can be exported and reimported very easily, even across organisations. Potentially, you can get the output from the get GET endpoint, modify just what you need, and re-import the plan via the PUT endpoint seamlessly, either as a new plan or as a change of the old one. Using this same process you can even export a plan from a different organisation and import it to yours. This same flow works also across environments (ie. you can export a plan from your Sandbox to your Production organisation).

How’s a plan structured?

The most important areas are pricing and path.

What is a plan path?

A plan path is the handle of a plan. It’s used in Billforward to retrieve a plan, and is univoque. All plans have a path. Two plans cannot share at any point the same path.

A plan path, is simply put, a path. It’s very similar to what you might have experienced browsing the folders on your computer, or similar to a web address. A path in Billforward has the following shape:

/my-random-path/a-bit-more-of-path/my-custom-plan.USD

We can immediately identify three separate parts in the path:

• /my-random-path/a-bit-more-of-path: this first part is what sometimes we refer as “the product”. This bit is purely a way to allow you to sort your plans. It doesn’t carry any functional meaning other than what you apply to it. You can see it as a set of folders you have put your plan into.
• my-custom-plan: this part is your actual plan. This is an internal name the plan is given. This is not what your customer will see (that’s the “Display name”). This field represents the internal name of a Plan in BIllforward. To continue with the file system analogy, this is the file name.
• .USD: this final part, represents the currency the plan uses. In a file system context, this would be the extension.

Pricing

The pricing in Billforward is very flexible., but before diving into the details, a disinguo needs to be made. There are two main components to the pricing in Billforward:

• The pricing strategy
• And the pricing type

The pricing type, answers the question “when does this particular price get billed?”. The pricing strategy answers “how much will I be charged?”.

When you define a plan in Billforward you can define an unlimited amount of pricing components. You can imagine a pricing component as an individual line on an invoice, or a different object you are selling. You can have an unlimited amount of pricing components on each plan, which means you can sell an infinite amount of different items in one go. For instance we can have the following plan:

Each of the above lines (Cookies, cakes and candies) is a pricing component, and each one of them can live on the same plan. Once you create a subscription out of a plan, you can set the amount of each item for which the customer should be billed.

Pricing types

BIllforward allows 4 different pricing types:

• Setup
• In advance (sometimes called simply “Subscription”)
• In arrears
• Usage

A plan can have a mixture of the above. A pricing component can be assigned one type at the time.

Setup components are billed only once, on the first billing period. They are ignored from the second period onward. This particular type of components is very handy when there is a particular price that needs to be billed only once when a given subscription starts, for instance this could be an installation price.

In advance components are pretty self explanatory. The customer is billed for a fixed amount of items every billing period. This amount is supposed to be the same for the subscription duration. This amount can be changed only if an explicit upgrade or downgrade is requested via the API. If no explicit request is passed, the same amount set during subscription creation is applied.

In arrears are basically identical to in advance pricing components. They also have a fixed amount that is billed at each billing period. Then only difference is the billing period of reference. When an invoice is raised, each pricing component is shown separately, and each one has its own billing period of reference. In case of the in advance component, the billing period is the one just about to start. In case of in arrears, the billing period is always the one that just ended. Other than this subtle difference, they behave the same exact way as in advance components.

Finally we have usage. These particular billing components have their own peculiar behaviour. They are relatively similar to in advance components as they are billed once every billing period and their period of reference is alway the one starting. The main difference though is in the quantity that is sold. Usage components require the user or system to update the amount of items sold on each period. This is very useful when the amount is not known in advance, for instance in a metered data consumption at an ISP. In this particular use case, the amount is unknown until the user has actually used it. Usage allows to set a different amount each billing cycle (ie. every month). An invoice will not be raised unless the amount is explicitly given at the begin of a new billing period.

Pricing strategies

Billforward offers 3 different pricing strategies:

• Fixed
• Tiered
• Volume

Each billing component can have a different pricing strategy.

Fixed is very self explanatory. You can charge a fixed amount every billing period, regardless of the number of items you are selling. You can’t go simpler in terms of billing ? This is super useful when combined with the setup pricing type.

Tiered pricing on the other hand allows you to set tiers for the amount a customer buys. Let’s give an example:

In the above pricing temple we are selling cookies. Based on the amount a user buys, a different price is going to be calculated. In case of tiered pricing, each unit is priced according to the position it takes in the pricing chart, for instance, if the user buys:

• 0 cookies, 0$ will be billed
• 5 cookies, 15$ will be billed
• This is because each individual cookie costs 3$
• 15 cookies, 40$ will be billed. This is because:
• The first 10 cookies cost 3$ each, which makes them cost 30$ total
• The following cookies (the 11th to 15th) cost 2$ each, making it 10$
• 30$ from the first tier plus 10$ from the second, 40$ total ?

Volume pricing also works in tiers, but slightly differently. Let’s assume we define the same tiers as in the above example, but with volume pricing enabled on the pricing component. The following amounts would be calculated:

• 0 cookies, 0$
• 5 cookies, 15$
• 15 cookies, 30$
• 25 cookies, 25$

The way this is calculated is the final price per unit is the one touched by top tier touched by the set amount. This value is applied to all the units sold. This is the main difference with tiered pricing, where each item is priced by the corresponding tier.

Create a plan in the UI

You can create a plan by using the Billforward UI. Everything you see here can be also be done via the Billforward API.

Everything starts from the plan page:

From here you can press the top right button to access the create plan page.

From here you can set the base plan information and the pricing. Let’s add path, billing period and currency first.

In the above picture we have set the most basic information of a plan. We can see we have a path (/my-test-plans/my-first-amazing-plan.USD ), a name, a currency and a billing period (our plan will recur monthly).

The next step is to add a pricing. Pricing can be set in the section below the basic data:

In the above example we have created 3 pricing components. You can have as many as you want in your plan. For each component you are expected to specify a name and a pricing type. You can select the type by clicking the drop down menu in each line:

Each of the components can have a different type. In the example we gave we have set the first one to be a setup component and everything else is an in advance one (each one marked by a different icon).

At this point we can click the “show details” button on each of the components and set the pricing. In the above example we have configured one of our pricing components to have 4 tiers, similarly to what we described in our pricing example in a paragraph above.

At this point we can press the save button on the bottom of the page.

At this point, if you have done everything correctly, you should be shown the above plan page. Congratulations! ? you have created your first plan! ?