Stripe.SubscriptionSchedule.Phase type is missing trial property

[alexiz10]

trafficstars

Describe the bug

The Stripe.SubscriptionSchedule.Phase type in TypeScript is missing the trial property. I am currently using SubscriptionSchedules to sign up my users for a free 30-day trial of my product, then, I move them to the free tier. If a user wants to make changes to their subscription before the trial runs out, I have to know this since they can only make certain changes to the trial. To create the first phase, I am using trial: true and end_date: _in 30 days_, since this phase should only be a trial. When checking currentPhase.trial, TypeScript complains that trial isn't part of Phase. But when I log out my phases to the console, the first phase has trial: true and the rest of the phases just don't have trial, so this should be an optional property. Currently, I have to extend the Phase type into my own custom type and add trial.

To Reproduce

1. Create a Subscription Schedule where the first phase is a trial phase

await stripe.subscriptionSchedules.create({
  customer: CUSTOMER_ID,
  start_date: Math.floor(Date.now() / 1000),
  phases: [
    {
      items: [{ price: PRO_MONTHLY_PRICE, quantity: 1 }],
      trial: true,
      end_date: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60,
    },
    {
      items: [{ price: FREE_TIER_PRICE, quantity: 1 }],
    },
  ],
});

2. Retrieve your Subscription Schedule

const schedule = await stripe.subscriptionSchedules.retrieve(NEW_SCHEDULE_ID);

3. Log the phases out to the console and verify that the first phase indeed does have a trial property set to true.

console.log(schedule.phases);

4. Make an attempt to access the trial property in the first phase

const isTrial = schedule.phases[0].trial;

Expected behavior

When attempting to access the trial property in a Phase, I should not see an error saying that the trial property does not exist in my phase.

Code snippets

OS

macOS

Node version

Node v20.12.1

Library version

stripe v17.7.0

API version

2025-02-24.acacia

Additional context

No response

[seanzhang-stripe]

Hi @alexiz10 Although you can set trial to a phase when creating a subscription schedule, the resulting subscription schedule object doesn't have a trial property in their phases.

Can you share with me the subscription schedule ID so that I can take a further look?

[alexiz10]

Hey @seanzhang-stripe , sure, here is a test subscription schedule I have: sub_sched_1R1DCpF2rxYbdwMevL3gjX6q

When I fetch this subscription schedule, this is basically the response I am getting: (notice the trial property in the first phase.

{
  "id": "sub_sched_1R1DCpF2rxYbdwMevL3gjX6q",
  ...
  "phases": [
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "end_date": 1744231547,
      "invoice_settings": null,
      "items": [
        {
          ...
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1741639547,
      "transfer_data": null,
      "trial": true,
      "trial_end": 1744231547
    },
    {
      "add_invoice_items": [],
      "application_fee_percent": null,
      "billing_cycle_anchor": null,
      "billing_thresholds": null,
      "collection_method": null,
      "coupon": null,
      "currency": "usd",
      "default_payment_method": null,
      "default_tax_rates": [],
      "description": null,
      "discounts": [],
      "end_date": 1746823547,
      "invoice_settings": null,
      "items": [
        {
          ...
        }
      ],
      "metadata": {},
      "on_behalf_of": null,
      "proration_behavior": "create_prorations",
      "start_date": 1744231547,
      "transfer_data": null,
      "trial_end": null
    }
  ],
  "released_at": null,
  "released_subscription": null,
  "renewal_interval": null,
  "status": "active",
  "subscription": "sub_1R1DCpF2rxYbdwMeLNCX52mo",
  "test_clock": null
}

[seanzhang-stripe]

Hi @alexiz10 I'm able to reproduce the same in my own test integration. I've already reported this to the relevant team and I'll let you know when there's an update to share.