Free Trials

Overview

You can offer a free trial period by setting the trial_end field when creating a subscription. The trial_end must be a date in the future and determines when the first payment will be collected.

How trials work

When a subscription is created with a trial_end:

• The subscription is activated immediately (assuming payment methods are provided).
• No payment is attempted until the trial_end date is reached.
• The first bill is created with a due date matching the trial_end value.
• Once the trial period ends, billing continues at the normal interval defined in cycle_details.

Creating a subscription with a trial

Include the trial_end field in your /subscriptions request. The value must be a future date in ISO 8601 format.

/subscriptions request with trial:

{
  "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240",
  "product": {
    "name": "Gold Plan",
    "description": "Monthly gold membership"
  },
  "price": {
    "usage_type": "fixed",
    "amount": 1999,
    "currency": "GBP",
    "cycle_details": {
      "interval": "month",
      "interval_count": 1,
      "limit": 12
    }
  },
  "payment_methods": [
    {
      "type": "card",
      "payment_method_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
      "is_primary": true
    }
  ],
  "trial_end": "2025-12-01T09:00:00Z"
}

In this example, the subscription is created as active but the first payment will not be attempted until 1st December 2025. After that, billing continues monthly as defined in cycle_details.

📘

Note

Payment methods are still required to start a trial. If the subscription is created without payment methods, it will be incomplete and must be activated via the /subscriptions/{subscription_id}/activate endpoint before the trial begins.