Narrower type for stripe.invoices.retrieveUpcoming()

types/Invoices.d.ts

@@ -40,7 +40,7 @@ declare module 'stripe' {
       /**
        * Unique identifier for the object. This property is always present unless the invoice is an upcoming invoice. See [Retrieve an upcoming invoice](https://stripe.com/docs/api/invoices/upcoming) for more details.
        */
-      id?: string;
+      id: string;
 
       /**
        * String representing the object's type. Objects of the same type share the same value.

types/InvoicesResource.d.ts

@@ -2168,10 +2168,10 @@ declare module 'stripe' {
       retrieveUpcoming(
         params?: InvoiceRetrieveUpcomingParams,
         options?: RequestOptions
-      ): Promise<Stripe.Response<Stripe.Invoice>>;
+      ): Promise<Stripe.Response<Stripe.UpcomingInvoice>>;
       retrieveUpcoming(
         options?: RequestOptions
-      ): Promise<Stripe.Response<Stripe.Invoice>>;
+      ): Promise<Stripe.Response<Stripe.UpcomingInvoice>>;
 
       /**
        * Search for invoices you've previously created using Stripe's [Search Query Language](https://stripe.com/docs/search#search-query-language).

types/UpcomingInvoices.d.ts

@@ -0,0 +1,7 @@
+// File generated from our OpenAPI spec
+
+declare module 'stripe' {
+  namespace Stripe {
+    type UpcomingInvoice = Omit<Stripe.Invoice, 'id'>;
+  }
+}

types/index.d.ts

@@ -7,6 +7,7 @@
 ///<reference path='./Errors.d.ts' />
 ///<reference path='./OAuth.d.ts' />
 ///<reference path='./Webhooks.d.ts' />
+///<reference path='./UpcomingInvoices.d.ts' />
 ///<reference path='./AccountsResource.d.ts' />
 ///<reference path='./AccountLinksResource.d.ts' />
 ///<reference path='./ApplePayDomainsResource.d.ts' />

types/test/typescriptTest.ts

@@ -123,6 +123,10 @@ stripe = new Stripe('sk_test_123', {
       return undefined;
     });
 
+  // @ts-expect-error
+  (await stripe.invoices.retrieveUpcoming()).id;
+  (await stripe.invoices.retrieve('')).id;
+
   try {
     await stripe.paymentIntents.create({amount: 100, currency: 'USD'});
   } catch (err) {