Trials & commitments

Trials and commitments are the two policies most likely to confuse customers — get them right at signup and you’ll spend less time in support.

Trials

A trial is a period during which the subscription is trialing and no invoices are issued. At the end of the trial, the subscription transitions to active and the first invoice is generated.

Setting a trial

Three places to set the trial length, in priority order:

1. On the create call: "trial_days": 14.
2. On the plan: "trial_days": 14.
3. None — no trial, the first invoice issues immediately.

Set to 0 to explicitly disable a plan’s default trial.

Payment method during trial

By default, a payment method is not required to start a trial. The subscription just transitions to active at trial end and tries to collect; if no method is on file, it goes straight to past_due.

To require a payment method up front:

{ "require_payment_method": true }

This makes default_payment_method_id mandatory at create time.

Trial extension

POST /v1/subscriptions/{id}/extend-trial
{ "trial_end": "2026-06-15T00:00:00Z" }

Only allowed while the subscription is trialing. Emits subscription.trial_extended. Useful for sales-led extensions.

Trial-end notice

subscription.trial_will_end fires three days before trial end. Use it to remind customers, upsell, or pre-confirm payment methods.

Commitments

A commitment is a minimum subscription term — typically 12 months for annual contracts. While committed, the customer cannot cancel for a refund of the remaining term; if they cancel, the subscription transitions to canceled at the commitment end, not immediately.

Setting a commitment

POST /v1/subscriptions
{
  "plan_code": "pro-monthly-usd",
  "commitment": {
    "months": 12,
    "billing": "monthly",
    "early_cancel": "forbid"
  }
}

commitment.billing	What you bill
monthly	The plan’s normal monthly invoice. Cancellation locked.
upfront	One invoice for the full commitment, paid up front.
quarterly	One invoice per quarter, four total.

commitment.early_cancel	Behaviour
forbid (default)	Cancellation request rejected with subscription.commitment_active.
allow_at_end	Cancellation accepted but takes effect at commitment end.
allow_with_fee	Allowed; a configured early-termination fee invoice issues.

Commitment renewal

When the commitment ends:

• auto_renew: true (default) — the commitment rolls forward by its original length. Customer keeps the same plan and price.
• auto_renew: false — the subscription transitions to month-to-month (no commitment) at the same plan.

Set on creation; change with PATCH /v1/subscriptions/{id}.

Mid-commitment plan changes

Allowed by default, but the new plan must be at least as expensive as the current one (an upgrade). Downgrades during commitment require override_commitment: true and an operator action — the dashboard surfaces a confirmation flow.

Webhook events

Event	When it fires
subscription.trial_started	Entered trialing.
subscription.trial_will_end	T-3 days before trial end.
subscription.trial_ended	Trial transitioned to active.
subscription.trial_extended	Trial end pushed out.
subscription.commitment_started	Commitment block began.
subscription.commitment_renewed	Commitment auto-renewed.
subscription.commitment_ending	T-30 days before commitment end.
subscription.commitment_ended	Commitment block expired.

Use commitment_ending to drive renewal outreach.