Trials define a period of time when a customer does not have to pay for service.

When providing a trial we should consider:

  • Duration
    • Skipping Trials
  • Conversion & Entitlements
    • Non-converting Trials
  • Trial completion
Rate-Plan API documentation 
Subscription API documentation 


When a rate-plan is defined a trial and trialPeriod can be set. This defines the default trial duration for a subscription using this rate-plan. When a subscription is created using a rate-plan with a trial defined the subscription type is set to Trial, the start of the trial is defined by the currentPeriodStart and end of the trial by the currentPeriodEnd, the type of the subscription will remain as Trial until the trial period has ended

For example:
The monthly rate-plan has a 30 day trial period and a cost of $5.00/month. The subscription is started on the 1st of March at 08:00.

Any invoices generated during the trial will have an actual cost of $0.00.

On the 31st of March at 08:00 the subscriptions trial will end.

When using the trial defined on the rate-plan the subscription will automatically convert to a paid for subscription at the end of the trial period with the same rate-plan. It is possible to have a non-converting trial or move to another plan, see Conversion & Entitlements.

Skipping Trials

To skip the trial period a subscription can be created and the type can be specified explicitly as Subscription.

For example:
To skip the 30 day trial in their previous example, when creating the subscription set the type explicitly to Subscription

    "type" : "Subscription",

Conversion & Entitlements

In some situations the entitlements that a trial confers are different from those of an active paid subscription.

To model this scenario the situation most commonly employed is to have a non-recurring rate-plan with zero cost pricing components. When the subscription is created a migration from the zero cost rate-plan to a priced rate-plan is performed.

The zero cost rate-plan would have a matching or reduced set of pricing components.

Schedule Rate-Plan Change API documentation 
For example:
A customer may have a trial of five free widgets but after the trial they have 10 widgets and 5 cogs.

A trial plan with only 5 widgets is created and a migration scheduled for the currentPeriodEnd of the trial subscription is setup.

Non-converting Trials

Some trials may not automatically convert into a subscription. A simple way to provide this functionality is to use a non-recurring subscription with zero cost pricing plans.

Trial completion

A schedule defines when and how often the subscriptions billing cycle lasts for. The schedule is defined using a duration and billing period dates.