Skip to main content
Free trials allow customers to try your subscription products before committing to payment. Polar handles trial periods automatically with flexible configuration options.

​
Overview

Free trials:
  • Defer payment until the trial period ends
  • Automatically convert to paid subscriptions
  • Can be configured per product or per checkout
  • Support trial redemption tracking to prevent abuse
Trials are only available for recurring (subscription) products, not one-time purchases.

​
Product Trial Configuration

Configure default trial periods on your products:
Product with 14-day trial
{
  "name": "Pro Plan",
  "billing_type": "recurring",
  "trial_interval": "day",
  "trial_interval_count": 14
}

​
Trial Intervals

Supported trial intervals:
  • day: Trial period in days
  • week: Trial period in weeks
  • month: Trial period in months
  • year: Trial period in years
Examples
// 7-day trial
{
  "trial_interval": "day",
  "trial_interval_count": 7
}

// 1-month trial
{
  "trial_interval": "month",
  "trial_interval_count": 1
}

​
Checkout Trial Override

Override the product’s default trial period at checkout: 
const checkout = await polar.checkouts.create({
  productPriceId: 'price_xxx',
  trialEnd: new Date('2024-12-31')  // Custom trial end date
});
The checkout trial override takes precedence over the product’s default trial configuration.

​
How Trials Work

1

Subscription Created

When a customer checks out with a trial:
  • Subscription status: trialing
  • trial_start: Set to current timestamp
  • trial_end: Calculated based on trial interval
  • current_period_end: Set to trial end
2

During Trial

  • No charges are made
  • Customer has full access to benefits
  • Subscription shows as “trialing”
  • current_period_end = trial_end
3

Trial Ends

When the trial period expires:
  • First invoice is created and charged
  • Status changes from trialing to active
  • Normal billing cycle begins
  • Benefits continue without interruption

​
Subscription Status During Trial

Trialing Subscription
{
  "status": "trialing",
  "trial_start": "2024-01-01T00:00:00Z",
  "trial_end": "2024-01-15T00:00:00Z",
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-01-15T00:00:00Z",
  "started_at": "2024-01-01T00:00:00Z"
}

​
Managing Active Trials

You can modify trial periods for active subscriptions:

​
Extend Trial

Extend an active trial to a new end date: 
await polar.subscriptions.update({
  id: 'sub_xxx',
  trialEnd: new Date('2024-02-01')  // New trial end
});
The new trial end must be after the current period end to prevent customer access loss.

​
End Trial Immediately

Convert a trialing subscription to paid immediately: 
await polar.subscriptions.update({
  id: 'sub_xxx',
  trialEnd: 'now'  // End trial now
});
This will:
  1. End the trial period
  2. Create and charge the first invoice
  3. Change status from trialing to active

​
Add Trial to Active Subscription

You can add a trial period to an already-active subscription: 
await polar.subscriptions.update({
  id: 'sub_xxx',  // Currently active
  trialEnd: new Date('2024-12-31')
});
Important: The trial end must be after the current period end. This extends the subscription without billing, giving the customer free time.

​
Trial Redemption Tracking

Polar tracks trial redemptions to prevent abuse:

​
How It Works

  1. Customer Identification: Tracked by:
    • Email address (case-insensitive)
    • Payment method fingerprint
    • Customer ID
  2. Product-Level Tracking: Redemptions are tracked per product
  3. Automatic Prevention: Polar checks if customer has already redeemed a trial for this product 
// Check if customer has already used trial
const alreadyRedeemed = await checkTrialRedeemed({
  product: product,
  customerEmail: '[email protected]',
  paymentMethodFingerprint: 'pm_fingerprint_xxx'
});
Trial redemption tracking helps prevent users from creating multiple accounts to abuse trial periods.

​
Trial Preview

Get a preview of what the first charge will be after a trial: 
const preview = await polar.subscriptions.preview({
  id: 'sub_xxx'  // Trialing subscription
});

console.log(preview.amount);  // First charge amount
console.log(preview.items);   // Line items
Previews are available for both trialing and active subscriptions.

​
Discounts with Trials

When combining trials with discounts:
  • During Trial: No charges, so no discount applied
  • After Trial: Discount applies to the first charge and subsequent charges (based on discount duration)
Trial + Discount
{
  "productPriceId": "price_xxx",
  "trialEnd": "2024-01-15T00:00:00Z",
  "discountCode": "WELCOME25"  // Applied after trial
}

​
Trial Best Practices

Standard Trial Lengths

Common trial periods: 7, 14, or 30 days depending on product complexity

Require Payment Method

Collect payment details upfront for seamless conversion

Communicate Clearly

Show trial end date and what happens when trial expires

Onboarding Focus

Use trial period to deliver value and ensure successful onboarding

​
Trial Limitations

Update Restrictions: You cannot update certain subscription properties during the trial period. Wait until the trial ends or end it early using trialEnd: 'now'.

​
Webhooks

Trial-related webhook events:
  • subscription.created: Includes trial dates if applicable
  • subscription.updated: Triggered when trial dates change
  • order.created: First charge after trial ends
subscription.created with Trial
{
  "type": "subscription.created",
  "data": {
    "id": "sub_xxx",
    "status": "trialing",
    "trial_start": "2024-01-01T00:00:00Z",
    "trial_end": "2024-01-15T00:00:00Z"
  }
}

​
API Reference

See the full API documentation:

Build docs developers (and LLMs) love

Get started for freeTalk to us