Managing Subscriptions

Retrieve a subscription

const subscription = await xtopay.subscriptions.retrieve("sub_abc123");

Upgrade or downgrade

Change the plan on an existing subscription. Xtopay handles proration automatically.

const updated = await xtopay.subscriptions.update("sub_abc123", {
  plan_id: "plan_pro_xyz",
  proration_behavior: "create_prorations",  // default
});

Proration behaviours:

Cancel a subscription

// Cancel at end of current billing period (recommended)
const cancelled = await xtopay.subscriptions.cancel("sub_abc123", {
  cancel_at_period_end: true,
});

// Cancel immediately
const cancelled = await xtopay.subscriptions.cancel("sub_abc123", {
  cancel_at_period_end: false,
});

When cancel_at_period_end is true, the subscription stays active until the period ends, then moves to cancelled. A subscription.cancellation_scheduled webhook fires immediately; subscription.cancelled fires at the end of the period.

Reactivate a cancelled subscription

If a subscription was cancelled at period end and the period hasn't ended yet:

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

Change payment method

await xtopay.subscriptions.update("sub_abc123", {
  payment_method_id: "pm_new_card_xyz",
});

Dunning (failed payment retries)

When a renewal charge fails, Xtopay enters dunning mode:

Configure your dunning schedule in Settings → Billing → Dunning.

Webhooks fired during dunning:

• subscription.payment_failed — on each failed attempt
• subscription.payment_action_required — customer needs to update payment method
• subscription.cancelled — if dunning exhausted