Free trials

Offer a time-based free trial before the first paid invoice. No card on file required.

PayBridge NP supports time-based trials on subscriptions. Trials are configured at the plan level and can be overridden per subscription.

How trials work

1. Set trialDays on a plan (or pass trialDays / trialEndsAt when creating a subscription).
2. The subscription starts in a trialing state - no invoice is generated during the trial window.
3. 72 hours before the trial ends, PayBridge sends a subscription.trial_will_end webhook and emails the customer a heads-up.
4. When the trial ends, PayBridge generates the first paid invoice, emails the hosted payment link to the customer, and fires subscription.trial_ended.
5. The customer pays the invoice manually - Nepal’s redirect-based payment providers (eSewa, Khalti, Fonepay) don’t support saved-card auto-charging, so we never silently charge after a trial.

Setting a trial on a plan

curl -X POST https://api.paybridgenp.com/v1/billing/plans \
  -H "Authorization: Bearer sk_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro",
    "amount": 99900,
    "intervalUnit": "month",
    "trialDays": 14
  }'

Any subscription created against this plan inherits the 14-day trial.

Per-subscription override

Pass trialDays or trialEndsAt on POST /v1/billing/subscriptions to override the plan default:

# 30-day trial regardless of plan setting
curl -X POST https://api.paybridgenp.com/v1/billing/subscriptions \
  -H "Authorization: Bearer sk_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "bc_…",
    "planId": "bp_…",
    "trialDays": 30
  }'

# Specific trial end date
curl -X POST https://api.paybridgenp.com/v1/billing/subscriptions \
  -H "Authorization: Bearer sk_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "bc_…",
    "planId": "bp_…",
    "trialEndsAt": "2026-05-15T00:00:00Z"
  }'

When both are provided, trialEndsAt wins. When neither is provided, the plan’s trialDays is used. trialDays: 0 disables the trial.

Ending a trial early

Use POST /v1/billing/subscriptions/{id}/end-trial to convert the subscription immediately. The first paid invoice is generated synchronously and returned in the response. Idempotent - repeated calls return 409 trial_not_active.

Extending a trial

POST /v1/billing/subscriptions/{id}/extend-trial with { "trialEndsAt": "…" } pushes the end date forward. Must be strictly after the current trial end, and the trial must still be active. The 72h reminder is re-armed for the new end date.

Webhooks

Event	When it fires
subscription.trial_will_end	~72h before trialEndsAt. Exactly once per trial.
subscription.trial_ended	When the first paid invoice is generated.
subscription.trial_extended	When extend-trial is called.

All three carry the full subscription context plus the relevant trial timestamps. See the webhook verification guide for event payload shapes.

Disabling the trial feature

Set TRIALS_ENABLED=false in the API environment to kill-switch all trial endpoints and the scheduler cycle. Existing trialing subscriptions continue until their trialEndsAt elapses.