Paid trial subscriptions on Stripe

README.md

Paid trial subscriptions on Stripe

This is an example of how to set up a Stripe Billing subscription with a short paid trialing period which automatically transitions into a regular price unless it is canceled. This was requested in https://twitter.com/abinaya_rl/status/1458275686930546693

Ability to start a trial period with $1 for 7 days and then after the trial charge the users 10$/monthly.

This behavior is currently possible using subscription schedules and an introductory price with a 1 week duration.

Requirements

You need the Stripe CLI tool and jq installed.

Create product catalog entries

This creates a single product with two prices: a $1/week "trialing" price, and a $10/month "standard" price.

PRODUCT_ID=$(stripe products create \
  --name="Paid trial service" | \
  jq --raw-output '.id')

TRIAL_PRICE_ID=$(stripe prices create \
    -d product=$PRODUCT_ID \
    -d unit_amount=100 \
    -d currency=usd \
    -d "recurring[interval]"=week | \
      jq --raw-output '.id')
    
STANDARD_PRICE_ID=$(stripe prices create \
    -d product=$PRODUCT_ID \
    -d unit_amount=1000 \
    -d currency=usd \
    -d "recurring[interval]"=month | \
      jq --raw-output '.id')

If you want to have the trialing price show up differently on the subscription invoice, then create two products with different names and attach one price per product.

Create a customer

Create a customer and attach a valid payment method (a real integration would follow this guide to create the customer and get a payment method).

CUSTOMER_ID=$(stripe customers create \
  -d source="tok_visa" \
  -d description="Customer `echo $RANDOM`" \
  -d email="`whoami`@example.com" | \
     jq --raw-output '.id')

Subscribe the customer to the prices using a Subscription Schedule

Subscription schedules allow you to orchestrate changes to subscription objects in the future. We will create the subscription using a schedule and tell it to switch prices after a single billing cycle. The schedule will create a subscription object in your Stripe account and also clean itself up after the phase transition is complete.

stripe subscription_schedules create \
  -d customer=$CUSTOMER_ID \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]"=$TRIAL_PRICE_ID \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][iterations]"=1 \
  -d "phases[1][items][0][price]"=$STANDARD_PRICE_ID \
  -d "phases[1][items][0][quantity]"=1 \
  -d "phases[1][iterations]"=1

Result

The subscription schedule object contains two phases indicating that the subscription will transition from one price to the next automatically:

{
  "id": "sub_sched_1JxLBgILVkppVx3AdJpqy2DS",
  "object": "subscription_schedule",
  "canceled_at": null,
  "completed_at": null,
  "created": 1637282564,
  "current_phase": {
    "end_date": 1637887364,
    "start_date": 1637282564
  },
  "customer": "cus_KcaL1gC994TjoD",
  "default_settings": {
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false
    },
    "billing_cycle_anchor": "automatic",
    "billing_thresholds": null,
    "collection_method": "charge_automatically",
    "default_payment_method": null,
    "default_source": null,
    "invoice_settings": null,
    "transfer_data": null
  },
  "end_behavior": "release",
  "livemode": false,
  "metadata": {
  },
  "phases": [
    {
      "add_invoice_items": [

      ],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "default_payment_method": null,
      "default_tax_rates": [

      ],
      "end_date": 1637887364,
      "invoice_settings": null,
      "items": [
        {
          "billing_thresholds": null,
          "plan": "price_1JxLB1ILVkppVx3ASS5JCOg4",
          "price": "price_1JxLB1ILVkppVx3ASS5JCOg4",
          "quantity": 1,
          "tax_rates": [

          ]
        }
      ],
      "proration_behavior": "create_prorations",
      "start_date": 1637282564,
      "transfer_data": null,
      "trial_end": null
    },
    {
      "add_invoice_items": [

      ],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "default_payment_method": null,
      "default_tax_rates": [

      ],
      "end_date": 1640479364,
      "invoice_settings": null,
      "items": [
        {
          "billing_thresholds": null,
          "plan": "price_1JxLB6ILVkppVx3AJ1msJOOT",
          "price": "price_1JxLB6ILVkppVx3AJ1msJOOT",
          "quantity": 1,
          "tax_rates": [

          ]
        }
      ],
      "proration_behavior": "create_prorations",
      "start_date": 1637887364,
      "transfer_data": null,
      "trial_end": null
    }
  ],
  "prebilling": null,
  "released_at": null,
  "released_subscription": null,
  "renewal_interval": null,
  "status": "active",
  "subscription": "sub_1JxLBgILVkppVx3ADX1puISO"
}

The change is also visible in the Dashboard:

The first invoice is for $1 and has a week long service period:

The second invoice is for $10 and has a month long service period:

Cancel the subscription during the trial to prevent the $10 charge from occurring.