Trials & Pauses

Free trials

Starting a trial

Set trial_period_days when creating a subscription:

const subscription = await xtopay.subscriptions.create({
  customer_id: "cus_abc123",
  plan_id: "plan_pro_xyz",
  trial_period_days: 14,
});
// subscription.status === "trialing"
// subscription.trial_ends_at === "2026-06-07T..."

No charge is made during the trial. At trial end, Xtopay automatically charges for the first billing period and moves the subscription to active.

Requiring a payment method upfront

To reduce trial abuse, collect payment details but don't charge until the trial ends:

const subscription = await xtopay.subscriptions.create({
  customer_id: "cus_abc123",
  plan_id: "plan_pro_xyz",
  trial_period_days: 14,
  payment_method_id: "pm_card_abc",  // collected at sign-up
  trial_end_behavior: "charge",      // default: charge at trial end
});

Ending a trial early

await xtopay.subscriptions.update("sub_abc123", {
  trial_end: "now",  // end trial immediately and bill
});

Trial webhooks

Event	Fired when
`subscription.trial_started`	Subscription created in trialing state
`subscription.trial_ending_soon`	3 days before trial ends
`subscription.trial_ended`	Trial period is over

Use subscription.trial_ending_soon to prompt customers to add a payment method if you didn't collect one upfront.

Pausing subscriptions

Pausing suspends billing without cancelling. Useful for customers who want to take a break.

Pause a subscription

await xtopay.subscriptions.pause("sub_abc123", {
  resumes_at: "2026-09-01T00:00:00Z",  // optional — auto-resume date
});
// subscription.status === "paused"

If resumes_at is set, Xtopay automatically resumes the subscription on that date. If not set, the subscription stays paused until you resume it manually.

Resume a paused subscription

await xtopay.subscriptions.resume("sub_abc123");

On resume, the next billing date is recalculated from the resume date. The customer is not back-charged for the pause period.

Pause webhooks

Event	Fired when
`subscription.paused`	Subscription enters paused state
`subscription.resumed`	Subscription becomes active again

On this page