Skip to main content

Trial periods

Subscriptions can include a trial period during which no payment is required. When the trial ends, the first billing cycle starts and the payer is charged (or sent a payment link) according to collection_method.

How trials work​

  • trial_period_days — Set at creation; the subscription starts in trialing status. For the given number of days from creation, no payment is collected.
  • trial_end — Optional ISO timestamp to set an explicit trial end. You can also set trial_end: "now" to effectively start without a trial.
  • When the trial ends:
    • If collection_method is send_payment_link: a payment link for the first period is created and (if configured) the payer is emailed.
    • If collection_method is auto_charge: the payer must have approved the allowance before or when the trial ends; otherwise the subscription may move to paused until they approve.
  • subscription.trial_will_end — OrcaRail sends this webhook about 3 days before trial_end so you can remind the payer to add a payment method or approve auto-charge.

Creating a subscription with a trial​

Use trial_period_days (or trial_end) when creating the subscription:

POST /api/v1/subscriptions
{
  "description": "Pro Plan",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

Response will include:

  • status: "trialing"
  • trial_start: set to creation time
  • trial_end: set to creation + 14 days
  • current_period_start / current_period_end: first billing period after the trial

Updating trial end​

You can update trial_end on an existing subscription (e.g. to extend or shorten the trial):

PATCH /api/v1/subscriptions/:id
{
  "trial_end": "2025-04-15T00:00:00Z"
}

Use "now" to end the trial immediately and trigger the first billing cycle.

Status flow with trials​

  • trialing — No charge yet; trial_end is in the future.
  • After trial_end: subscription moves to active once the first period is paid (or to paused if there is no payment method / allowance).

Webhooks​

  • subscription.created — Sent when the subscription is created (may be trialing).
  • subscription.trial_will_end — Sent roughly 3 days before trial_end; use it to email the payer or prompt approval for auto-charge.
  • subscription.payment_link.created — When the first payment link is created after trial (for send_payment_link).
  • subscription.payment_link.paid — When the first cycle is paid after trial.

Best practices​

  1. Remind before trial ends — Handle subscription.trial_will_end to send an email or in-app message.
  2. Auto-charge and trials — For auto_charge, direct the payer to approve the allowance before trial_end so the first charge can succeed; otherwise the subscription may go paused or past_due.
  3. Clear messaging — On the pay page or subscribe page, show trial length and the first charge date/amount so the payer knows what to expect.

Next steps​