Advanced SubscriptionsDigital Subscriptions

Free Trials

Give customers a trial period before their first paid order, with automatic handling of next order dates and digital entitlements
View as Markdown

A free trial delays a subscription’s first paid order by a configurable number of days. Free trials are configured per product in Ordergroove — each product can have at most one free trial configuration at a time. While free trials can be configured for any product, they are only fully supported for digital products, where the trial period also controls when a customer’s entitlements expire.

How Free Trials Work

Duration

A free trial configuration specifies a duration in days. This is the only setting on a free trial configuration.

Next order date

When a customer subscribes to a product with a free trial configured, the subscription’s first next order date is not set using the plan’s regular cadence. Instead, it’s set to the subscription’s creation date plus the configured number of trial days. Once that first order places, the subscription’s cadence proceeds normally from there.

Digital entitlements

If the product is a digital plan, the entitlement granted at signup expires when the free trial ends rather than following the plan’s regular entitlement duration. When the trial ends and the first paid order places, a regular entitlement is granted following the plan’s normal terms.

Changing a configuration doesn’t affect existing subscriptions

Updating or removing a product’s free trial configuration only affects subscriptions created afterward. Subscriptions that already exist keep the free trial duration (or absence of one) that was in effect when they were created.

Example

A product has a free trial configuration of 14 days.

  • Day 0 — A customer subscribes. The subscription’s next order date is set to Day 14 (creation date + 14 days) instead of the plan’s regular cadence. If the product is a digital plan, an entitlement is granted that expires on Day 14.
  • Day 14 — The trial ends. The first order places and the customer is billed. From here, the subscription follows its regular cadence. If the product is a digital plan, the trial entitlement expires and a regular entitlement is granted.
  • Mid-trial configuration change — If the merchant changes the free trial duration on Day 5, the customer from Day 0 is unaffected and still renews on Day 14. Only subscriptions created after the change use the new duration.

Managing Free Trial Configurations

Free trial configurations are managed per product via the REST RPC API:

  • Create — POST /products/{product_id}/free_trials/create/
  • Update — PATCH /products/{product_id}/free_trials/{free_trial_id}/update/
  • Delete — DELETE /products/{product_id}/free_trials/{free_trial_id}/delete/

Creating a free trial configuration for a product that already has one returns an error — remove the existing configuration first if you want to replace it.

To read a product’s free trial configuration(s), pass include_product_free_trials=true to the products list or product retrieve endpoints. This adds a product_free_trial_configurations array to each product in the response.