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.updated (with the new trial_end in previous_attributes). Useful for sales-led extensions.

Trial end

Paylera does not emit a pre-end “trial will end” event — track trial_end yourself if you want to remind customers ahead of time. When the trial actually ends, subscription.trial_ended fires (the subscription moves to active or past_due).

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.created	Subscription created; trialing when a trial applies (there is no separate “trial started” event).
subscription.trial_ended	Trial ended; the subscription moved to active or past_due.
subscription.commitment_emitted	A commitment shortfall landed as a top-up line on the period’s invoice.
subscription.commitment_satisfied	The period met the commitment floor without a top-up.

Paylera does not emit pre-end reminder events (no “trial will end” or “commitment ending”); track trial_end / the commitment window yourself to drive outreach.