orb-billing 5.48.0 → 5.76.0

package/src/resources/invoice-line-items.ts

@@ -25,6 +25,18 @@ export class InvoiceLineItems extends APIResource {
    * - If both `item_id` and `name` are provided: The item is looked up by ID for
    *   association, but the provided `name` is used for the line item (not the item's
    *   name).
+   *
+   * @example
+   * ```ts
+   * const invoiceLineItem =
+   *   await client.invoiceLineItems.create({
+   *     amount: '12.00',
+   *     end_date: '2023-09-22',
+   *     invoice_id: '4khy3nwzktxv7',
+   *     quantity: 1,
+   *     start_date: '2023-09-22',
+   *   });
+   * ```
    */
   create(
     body: InvoiceLineItemCreateParams,
@@ -55,6 +67,7 @@ export interface InvoiceLineItemCreateResponse {
     | Shared.MonetaryUsageDiscountAdjustment
     | Shared.MonetaryAmountDiscountAdjustment
     | Shared.MonetaryPercentageDiscountAdjustment
+    | InvoiceLineItemCreateResponse.MonetaryTieredPercentageDiscountAdjustment
     | Shared.MonetaryMinimumAdjustment
     | Shared.MonetaryMaximumAdjustment
   >;
@@ -144,6 +157,97 @@ export interface InvoiceLineItemCreateResponse {
   usage_customer_ids: Array<string> | null;
 }
 
+export namespace InvoiceLineItemCreateResponse {
+  export interface MonetaryTieredPercentageDiscountAdjustment {
+    id: string;
+
+    adjustment_type: 'tiered_percentage_discount';
+
+    /**
+     * The value applied by an adjustment.
+     */
+    amount: string;
+
+    /**
+     * @deprecated The price IDs that this adjustment applies to.
+     */
+    applies_to_price_ids: Array<string>;
+
+    /**
+     * The filters that determine which prices to apply this adjustment to.
+     */
+    filters: Array<MonetaryTieredPercentageDiscountAdjustment.Filter>;
+
+    /**
+     * True for adjustments that apply to an entire invoice, false for adjustments that
+     * apply to only one price.
+     */
+    is_invoice_level: boolean;
+
+    /**
+     * The reason for the adjustment.
+     */
+    reason: string | null;
+
+    /**
+     * The adjustment id this adjustment replaces. This adjustment will take the place
+     * of the replaced adjustment in plan version migrations.
+     */
+    replaces_adjustment_id: string | null;
+
+    /**
+     * The ordered, contiguous bands of cumulative eligible spend, each discounted at
+     * its own percentage (progressive fill-a-tier), applied to the prices this
+     * adjustment covers in a given billing period.
+     */
+    tiers: Array<MonetaryTieredPercentageDiscountAdjustment.Tier>;
+  }
+
+  export namespace MonetaryTieredPercentageDiscountAdjustment {
+    export interface Filter {
+      /**
+       * The property of the price to filter on.
+       */
+      field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+      /**
+       * Should prices that match the filter be included or excluded.
+       */
+      operator: 'includes' | 'excludes';
+
+      /**
+       * The IDs or values that match this filter.
+       */
+      values: Array<string>;
+    }
+
+    /**
+     * One band of a tiered percentage discount. Bounds are denominated in the
+     * discount's currency. `lower_bound` is the exclusive start of the band and
+     * `upper_bound` is the inclusive end; `upper_bound` is null only for the
+     * open-ended final tier.
+     */
+    export interface Tier {
+      /**
+       * Exclusive lower bound of cumulative spend for this tier.
+       */
+      lower_bound: number;
+
+      /**
+       * The percentage (between 0 and 1) discounted from spend that falls within this
+       * tier.
+       */
+      percentage: number;
+
+      /**
+       * Inclusive upper bound of cumulative spend for this tier; null for the final
+       * open-ended tier.
+       */
+      upper_bound?: number | null;
+    }
+  }
+}
+
 export interface InvoiceLineItemCreateParams {
   /**
    * The total amount in the invoice's currency to add to the line item.

package/src/resources/invoices.ts

@@ -16,6 +16,25 @@ import { Page, type PageParams } from '../pagination';
 export class Invoices extends APIResource {
   /**
    * This endpoint is used to create a one-off invoice for a customer.
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.invoices.create({
+   *   currency: 'USD',
+   *   invoice_date: '2019-12-27T18:11:19.117Z',
+   *   line_items: [
+   *     {
+   *       end_date: '2023-09-22',
+   *       item_id: '4khy3nwzktxv7',
+   *       model_type: 'unit',
+   *       name: 'Line Item Name',
+   *       quantity: 1,
+   *       start_date: '2023-09-22',
+   *       unit_config: { unit_amount: 'unit_amount' },
+   *     },
+   *   ],
+   * });
+   * ```
    */
   create(body: InvoiceCreateParams, options?: Core.RequestOptions): Core.APIPromise<Shared.Invoice> {
     return this._client.post('/invoices', { body, ...options });
@@ -30,6 +49,11 @@ export class Invoices extends APIResource {
    * `invoice_date`, and `auto_collection` can only be modified if the invoice is in
    * a `draft` state. `invoice_date` can only be modified for non-subscription
    * invoices.
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.invoices.update('invoice_id');
+   * ```
    */
   update(
     invoiceId: string,
@@ -53,6 +77,18 @@ export class Invoices extends APIResource {
    * When fetching any `draft` invoices, this returns the last-computed invoice
    * values for each draft invoice, which may not always be up-to-date since Orb
    * regularly refreshes invoices asynchronously.
+   *
+   * If you don't need line item details, minimums, maximums, or discounts, prefer
+   * the [list invoices summary](/api-reference/invoice/list-invoices-summary)
+   * endpoint for better performance.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const invoice of client.invoices.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: InvoiceListParams,
@@ -75,6 +111,14 @@ export class Invoices extends APIResource {
    * This endpoint only allows deletion of one-off line items (not subscription-based
    * line items). The invoice must be in a draft status for this operation to
    * succeed.
+   *
+   * @example
+   * ```ts
+   * await client.invoices.deleteLineItem(
+   *   'invoice_id',
+   *   'line_item_id',
+   * );
+   * ```
    */
   deleteLineItem(
     invoiceId: string,
@@ -90,6 +134,11 @@ export class Invoices extends APIResource {
   /**
    * This endpoint is used to fetch an [`Invoice`](/core-concepts#invoice) given an
    * identifier.
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.invoices.fetch('invoice_id');
+   * ```
    */
   fetch(invoiceId: string, options?: Core.RequestOptions): Core.APIPromise<Shared.Invoice> {
     return this._client.get(`/invoices/${invoiceId}`, options);
@@ -99,6 +148,13 @@ export class Invoices extends APIResource {
    * This endpoint can be used to fetch the upcoming
    * [invoice](/core-concepts#invoice) for the current billing period given a
    * subscription.
+   *
+   * @example
+   * ```ts
+   * const response = await client.invoices.fetchUpcoming({
+   *   subscription_id: 'subscription_id',
+   * });
+   * ```
    */
   fetchUpcoming(
     query: InvoiceFetchUpcomingParams,
@@ -114,6 +170,11 @@ export class Invoices extends APIResource {
    * possibly trigger side effects, some of which could be customer-visible (e.g.
    * sending emails, auto-collecting payment, syncing the invoice to external
    * providers, etc).
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.invoices.issue('invoice_id');
+   * ```
    */
   issue(
     invoiceId: string,
@@ -142,6 +203,13 @@ export class Invoices extends APIResource {
    *
    * This is a lighter-weight alternative to the issue invoice endpoint, returning an
    * invoice summary without any line item details.
+   *
+   * @example
+   * ```ts
+   * const response = await client.invoices.issueSummary(
+   *   'invoice_id',
+   * );
+   * ```
    */
   issueSummary(
     invoiceId: string,
@@ -180,6 +248,14 @@ export class Invoices extends APIResource {
    * When fetching any `draft` invoices, this returns the last-computed invoice
    * values for each draft invoice, which may not always be up-to-date since Orb
    * regularly refreshes invoices asynchronously.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const invoiceListSummaryResponse of client.invoices.listSummary()) {
+   *   // ...
+   * }
+   * ```
    */
   listSummary(
     query?: InvoiceListSummaryParams,
@@ -204,6 +280,14 @@ export class Invoices extends APIResource {
   /**
    * This endpoint allows an invoice's status to be set to the `paid` status. This
    * can only be done to invoices that are in the `issued` or `synced` status.
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.invoices.markPaid(
+   *   'invoice_id',
+   *   { payment_received_date: '2023-09-22' },
+   * );
+   * ```
    */
   markPaid(
     invoiceId: string,
@@ -218,6 +302,13 @@ export class Invoices extends APIResource {
    * customer's default payment method. Optionally, a shared payment token (SPT) can
    * be provided to pay using agent-granted credentials instead. This action can only
    * be taken on invoices with status "issued".
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.invoices.pay('invoice_id', {
+   *   shared_payment_token_id: 'shared_payment_token_id',
+   * });
+   * ```
    */
   pay(
     invoiceId: string,
@@ -239,6 +330,11 @@ export class Invoices extends APIResource {
    * If the invoice was used to purchase a credit block, but the invoice is not yet
    * paid, the credit block will be voided. If the invoice was created due to a
    * top-up, the top-up will be disabled.
+   *
+   * @example
+   * ```ts
+   * const invoice = await client.invoices.void('invoice_id');
+   * ```
    */
   void(invoiceId: string, options?: Core.RequestOptions): Core.APIPromise<Shared.Invoice> {
     return this._client.post(`/invoices/${invoiceId}/void`, options);
@@ -337,11 +433,13 @@ export interface InvoiceFetchUpcomingResponse {
    * | Estonia                | `eu_vat`     | European VAT Number                                                                                     |
    * | Ethiopia               | `et_tin`     | Ethiopia Tax Identification Number                                                                      |
    * | European Union         | `eu_oss_vat` | European One Stop Shop VAT Number for non-Union scheme                                                  |
+   * | Faroe Islands          | `fo_vat`     | Faroe Islands VAT Number                                                                                |
    * | Finland                | `eu_vat`     | European VAT Number                                                                                     |
    * | France                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Georgia                | `ge_vat`     | Georgian VAT                                                                                            |
    * | Germany                | `de_stn`     | German Tax Number (Steuernummer)                                                                        |
    * | Germany                | `eu_vat`     | European VAT Number                                                                                     |
+   * | Gibraltar              | `gi_tin`     | Gibraltar Tax Identification Number                                                                     |
    * | Greece                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Guinea                 | `gn_nif`     | Guinea Tax Identification Number (Número de Identificação Fiscal)                                       |
    * | Hong Kong              | `hk_br`      | Hong Kong BR Number                                                                                     |
@@ -353,6 +451,7 @@ export interface InvoiceFetchUpcomingResponse {
    * | Ireland                | `eu_vat`     | European VAT Number                                                                                     |
    * | Israel                 | `il_vat`     | Israel VAT                                                                                              |
    * | Italy                  | `eu_vat`     | European VAT Number                                                                                     |
+   * | Italy                  | `it_cf`      | Italian Codice Fiscale Number                                                                           |
    * | Japan                  | `jp_cn`      | Japanese Corporate Number (_Hōjin Bangō_)                                                               |
    * | Japan                  | `jp_rn`      | Japanese Registered Foreign Businesses' Registration Number (_Tōroku Kokugai Jigyōsha no Tōroku Bangō_) |
    * | Japan                  | `jp_trn`     | Japanese Tax Registration Number (_Tōroku Bangō_)                                                       |
@@ -383,6 +482,7 @@ export interface InvoiceFetchUpcomingResponse {
    * | Norway                 | `no_vat`     | Norwegian VAT Number                                                                                    |
    * | Norway                 | `no_voec`    | Norwegian VAT on e-commerce Number                                                                      |
    * | Oman                   | `om_vat`     | Omani VAT Number                                                                                        |
+   * | Paraguay               | `py_ruc`     | Paraguayan RUC Number                                                                                   |
    * | Peru                   | `pe_ruc`     | Peruvian RUC Number                                                                                     |
    * | Philippines            | `ph_tin`     | Philippines Tax Identification Number                                                                   |
    * | Poland                 | `eu_vat`     | European VAT Number                                                                                     |
@@ -404,6 +504,7 @@ export interface InvoiceFetchUpcomingResponse {
    * | South Korea            | `kr_brn`     | Korean BRN                                                                                              |
    * | Spain                  | `es_cif`     | Spanish NIF Number (previously Spanish CIF Number)                                                      |
    * | Spain                  | `eu_vat`     | European VAT Number                                                                                     |
+   * | Sri Lanka              | `lk_vat`     | Sri Lanka VAT Number                                                                                    |
    * | Suriname               | `sr_fin`     | Suriname FIN Number                                                                                     |
    * | Sweden                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Switzerland            | `ch_uid`     | Switzerland UID Number                                                                                  |
@@ -451,8 +552,8 @@ export interface InvoiceFetchUpcomingResponse {
   eligible_to_issue_at: string | null;
 
   /**
-   * A URL for the customer-facing invoice portal. This URL expires 30 days after the
-   * invoice's due date, or 60 days after being re-generated through the UI.
+   * A URL for the customer-facing invoice portal. This URL expires 60 days after the
+   * link is generated, or 30 days after the invoice's due date — whichever is later.
    */
   hosted_invoice_url: string | null;
 
@@ -705,6 +806,7 @@ export namespace InvoiceFetchUpcomingResponse {
       | Shared.MonetaryUsageDiscountAdjustment
       | Shared.MonetaryAmountDiscountAdjustment
       | Shared.MonetaryPercentageDiscountAdjustment
+      | LineItem.MonetaryTieredPercentageDiscountAdjustment
       | Shared.MonetaryMinimumAdjustment
       | Shared.MonetaryMaximumAdjustment
     >;
@@ -794,6 +896,97 @@ export namespace InvoiceFetchUpcomingResponse {
     usage_customer_ids: Array<string> | null;
   }
 
+  export namespace LineItem {
+    export interface MonetaryTieredPercentageDiscountAdjustment {
+      id: string;
+
+      adjustment_type: 'tiered_percentage_discount';
+
+      /**
+       * The value applied by an adjustment.
+       */
+      amount: string;
+
+      /**
+       * @deprecated The price IDs that this adjustment applies to.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * The filters that determine which prices to apply this adjustment to.
+       */
+      filters: Array<MonetaryTieredPercentageDiscountAdjustment.Filter>;
+
+      /**
+       * True for adjustments that apply to an entire invoice, false for adjustments that
+       * apply to only one price.
+       */
+      is_invoice_level: boolean;
+
+      /**
+       * The reason for the adjustment.
+       */
+      reason: string | null;
+
+      /**
+       * The adjustment id this adjustment replaces. This adjustment will take the place
+       * of the replaced adjustment in plan version migrations.
+       */
+      replaces_adjustment_id: string | null;
+
+      /**
+       * The ordered, contiguous bands of cumulative eligible spend, each discounted at
+       * its own percentage (progressive fill-a-tier), applied to the prices this
+       * adjustment covers in a given billing period.
+       */
+      tiers: Array<MonetaryTieredPercentageDiscountAdjustment.Tier>;
+    }
+
+    export namespace MonetaryTieredPercentageDiscountAdjustment {
+      export interface Filter {
+        /**
+         * The property of the price to filter on.
+         */
+        field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+        /**
+         * Should prices that match the filter be included or excluded.
+         */
+        operator: 'includes' | 'excludes';
+
+        /**
+         * The IDs or values that match this filter.
+         */
+        values: Array<string>;
+      }
+
+      /**
+       * One band of a tiered percentage discount. Bounds are denominated in the
+       * discount's currency. `lower_bound` is the exclusive start of the band and
+       * `upper_bound` is the inclusive end; `upper_bound` is null only for the
+       * open-ended final tier.
+       */
+      export interface Tier {
+        /**
+         * Exclusive lower bound of cumulative spend for this tier.
+         */
+        lower_bound: number;
+
+        /**
+         * The percentage (between 0 and 1) discounted from spend that falls within this
+         * tier.
+         */
+        percentage: number;
+
+        /**
+         * Inclusive upper bound of cumulative spend for this tier; null for the final
+         * open-ended tier.
+         */
+        upper_bound?: number | null;
+      }
+    }
+  }
+
   export interface PaymentAttempt {
     /**
      * The ID of the payment attempt.
@@ -813,7 +1006,7 @@ export namespace InvoiceFetchUpcomingResponse {
     /**
      * The payment provider that attempted to collect the payment.
      */
-    payment_provider: 'stripe' | null;
+    payment_provider: 'stripe' | 'adyen' | null;
 
     /**
      * The ID of the payment attempt in the payment provider.
@@ -926,11 +1119,13 @@ export interface InvoiceIssueSummaryResponse {
    * | Estonia                | `eu_vat`     | European VAT Number                                                                                     |
    * | Ethiopia               | `et_tin`     | Ethiopia Tax Identification Number                                                                      |
    * | European Union         | `eu_oss_vat` | European One Stop Shop VAT Number for non-Union scheme                                                  |
+   * | Faroe Islands          | `fo_vat`     | Faroe Islands VAT Number                                                                                |
    * | Finland                | `eu_vat`     | European VAT Number                                                                                     |
    * | France                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Georgia                | `ge_vat`     | Georgian VAT                                                                                            |
    * | Germany                | `de_stn`     | German Tax Number (Steuernummer)                                                                        |
    * | Germany                | `eu_vat`     | European VAT Number                                                                                     |
+   * | Gibraltar              | `gi_tin`     | Gibraltar Tax Identification Number                                                                     |
    * | Greece                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Guinea                 | `gn_nif`     | Guinea Tax Identification Number (Número de Identificação Fiscal)                                       |
    * | Hong Kong              | `hk_br`      | Hong Kong BR Number                                                                                     |
@@ -942,6 +1137,7 @@ export interface InvoiceIssueSummaryResponse {
    * | Ireland                | `eu_vat`     | European VAT Number                                                                                     |
    * | Israel                 | `il_vat`     | Israel VAT                                                                                              |
    * | Italy                  | `eu_vat`     | European VAT Number                                                                                     |
+   * | Italy                  | `it_cf`      | Italian Codice Fiscale Number                                                                           |
    * | Japan                  | `jp_cn`      | Japanese Corporate Number (_Hōjin Bangō_)                                                               |
    * | Japan                  | `jp_rn`      | Japanese Registered Foreign Businesses' Registration Number (_Tōroku Kokugai Jigyōsha no Tōroku Bangō_) |
    * | Japan                  | `jp_trn`     | Japanese Tax Registration Number (_Tōroku Bangō_)                                                       |
@@ -972,6 +1168,7 @@ export interface InvoiceIssueSummaryResponse {
    * | Norway                 | `no_vat`     | Norwegian VAT Number                                                                                    |
    * | Norway                 | `no_voec`    | Norwegian VAT on e-commerce Number                                                                      |
    * | Oman                   | `om_vat`     | Omani VAT Number                                                                                        |
+   * | Paraguay               | `py_ruc`     | Paraguayan RUC Number                                                                                   |
    * | Peru                   | `pe_ruc`     | Peruvian RUC Number                                                                                     |
    * | Philippines            | `ph_tin`     | Philippines Tax Identification Number                                                                   |
    * | Poland                 | `eu_vat`     | European VAT Number                                                                                     |
@@ -993,6 +1190,7 @@ export interface InvoiceIssueSummaryResponse {
    * | South Korea            | `kr_brn`     | Korean BRN                                                                                              |
    * | Spain                  | `es_cif`     | Spanish NIF Number (previously Spanish CIF Number)                                                      |
    * | Spain                  | `eu_vat`     | European VAT Number                                                                                     |
+   * | Sri Lanka              | `lk_vat`     | Sri Lanka VAT Number                                                                                    |
    * | Suriname               | `sr_fin`     | Suriname FIN Number                                                                                     |
    * | Sweden                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Switzerland            | `ch_uid`     | Switzerland UID Number                                                                                  |
@@ -1031,8 +1229,8 @@ export interface InvoiceIssueSummaryResponse {
   eligible_to_issue_at: string | null;
 
   /**
-   * A URL for the customer-facing invoice portal. This URL expires 30 days after the
-   * invoice's due date, or 60 days after being re-generated through the UI.
+   * A URL for the customer-facing invoice portal. This URL expires 60 days after the
+   * link is generated, or 30 days after the invoice's due date — whichever is later.
    */
   hosted_invoice_url: string | null;
 
@@ -1265,7 +1463,7 @@ export namespace InvoiceIssueSummaryResponse {
     /**
      * The payment provider that attempted to collect the payment.
      */
-    payment_provider: 'stripe' | null;
+    payment_provider: 'stripe' | 'adyen' | null;
 
     /**
      * The ID of the payment attempt in the payment provider.
@@ -1378,11 +1576,13 @@ export interface InvoiceListSummaryResponse {
    * | Estonia                | `eu_vat`     | European VAT Number                                                                                     |
    * | Ethiopia               | `et_tin`     | Ethiopia Tax Identification Number                                                                      |
    * | European Union         | `eu_oss_vat` | European One Stop Shop VAT Number for non-Union scheme                                                  |
+   * | Faroe Islands          | `fo_vat`     | Faroe Islands VAT Number                                                                                |
    * | Finland                | `eu_vat`     | European VAT Number                                                                                     |
    * | France                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Georgia                | `ge_vat`     | Georgian VAT                                                                                            |
    * | Germany                | `de_stn`     | German Tax Number (Steuernummer)                                                                        |
    * | Germany                | `eu_vat`     | European VAT Number                                                                                     |
+   * | Gibraltar              | `gi_tin`     | Gibraltar Tax Identification Number                                                                     |
    * | Greece                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Guinea                 | `gn_nif`     | Guinea Tax Identification Number (Número de Identificação Fiscal)                                       |
    * | Hong Kong              | `hk_br`      | Hong Kong BR Number                                                                                     |
@@ -1394,6 +1594,7 @@ export interface InvoiceListSummaryResponse {
    * | Ireland                | `eu_vat`     | European VAT Number                                                                                     |
    * | Israel                 | `il_vat`     | Israel VAT                                                                                              |
    * | Italy                  | `eu_vat`     | European VAT Number                                                                                     |
+   * | Italy                  | `it_cf`      | Italian Codice Fiscale Number                                                                           |
    * | Japan                  | `jp_cn`      | Japanese Corporate Number (_Hōjin Bangō_)                                                               |
    * | Japan                  | `jp_rn`      | Japanese Registered Foreign Businesses' Registration Number (_Tōroku Kokugai Jigyōsha no Tōroku Bangō_) |
    * | Japan                  | `jp_trn`     | Japanese Tax Registration Number (_Tōroku Bangō_)                                                       |
@@ -1424,6 +1625,7 @@ export interface InvoiceListSummaryResponse {
    * | Norway                 | `no_vat`     | Norwegian VAT Number                                                                                    |
    * | Norway                 | `no_voec`    | Norwegian VAT on e-commerce Number                                                                      |
    * | Oman                   | `om_vat`     | Omani VAT Number                                                                                        |
+   * | Paraguay               | `py_ruc`     | Paraguayan RUC Number                                                                                   |
    * | Peru                   | `pe_ruc`     | Peruvian RUC Number                                                                                     |
    * | Philippines            | `ph_tin`     | Philippines Tax Identification Number                                                                   |
    * | Poland                 | `eu_vat`     | European VAT Number                                                                                     |
@@ -1445,6 +1647,7 @@ export interface InvoiceListSummaryResponse {
    * | South Korea            | `kr_brn`     | Korean BRN                                                                                              |
    * | Spain                  | `es_cif`     | Spanish NIF Number (previously Spanish CIF Number)                                                      |
    * | Spain                  | `eu_vat`     | European VAT Number                                                                                     |
+   * | Sri Lanka              | `lk_vat`     | Sri Lanka VAT Number                                                                                    |
    * | Suriname               | `sr_fin`     | Suriname FIN Number                                                                                     |
    * | Sweden                 | `eu_vat`     | European VAT Number                                                                                     |
    * | Switzerland            | `ch_uid`     | Switzerland UID Number                                                                                  |
@@ -1483,8 +1686,8 @@ export interface InvoiceListSummaryResponse {
   eligible_to_issue_at: string | null;
 
   /**
-   * A URL for the customer-facing invoice portal. This URL expires 30 days after the
-   * invoice's due date, or 60 days after being re-generated through the UI.
+   * A URL for the customer-facing invoice portal. This URL expires 60 days after the
+   * link is generated, or 30 days after the invoice's due date — whichever is later.
    */
   hosted_invoice_url: string | null;
 
@@ -1717,7 +1920,7 @@ export namespace InvoiceListSummaryResponse {
     /**
      * The payment provider that attempted to collect the payment.
      */
-    payment_provider: 'stripe' | null;
+    payment_provider: 'stripe' | 'adyen' | null;
 
     /**
      * The ID of the payment attempt in the payment provider.
@@ -1745,8 +1948,9 @@ export interface InvoiceCreateParams {
   currency: string;
 
   /**
-   * Optional invoice date to set. Must be in the past, if not set, `invoice_date` is
-   * set to the current time in the customer's timezone.
+   * An ISO 8601 date or timestamp, interpreted in the customer's timezone. Must be
+   * in the past. If a date is set without a time, `invoice_date` is set to midnight
+   * on the chosen date in the customer's timezone.
    */
   invoice_date: string;
 

package/src/resources/items.ts

@@ -12,6 +12,13 @@ import { Page, type PageParams } from '../pagination';
 export class Items extends APIResource {
   /**
    * This endpoint is used to create an [Item](/core-concepts#item).
+   *
+   * @example
+   * ```ts
+   * const item = await client.items.create({
+   *   name: 'API requests',
+   * });
+   * ```
    */
   create(body: ItemCreateParams, options?: Core.RequestOptions): Core.APIPromise<Item> {
     return this._client.post('/items', { body, ...options });
@@ -19,6 +26,11 @@ export class Items extends APIResource {
 
   /**
    * This endpoint can be used to update properties on the Item.
+   *
+   * @example
+   * ```ts
+   * const item = await client.items.update('item_id');
+   * ```
    */
   update(itemId: string, body: ItemUpdateParams, options?: Core.RequestOptions): Core.APIPromise<Item> {
     return this._client.put(`/items/${itemId}`, { body, ...options });
@@ -27,6 +39,14 @@ export class Items extends APIResource {
   /**
    * This endpoint returns a list of all Items, ordered in descending order by
    * creation time.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const item of client.items.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(query?: ItemListParams, options?: Core.RequestOptions): Core.PagePromise<ItemsPage, Item>;
   list(options?: Core.RequestOptions): Core.PagePromise<ItemsPage, Item>;
@@ -42,6 +62,11 @@ export class Items extends APIResource {
 
   /**
    * Archive item
+   *
+   * @example
+   * ```ts
+   * const item = await client.items.archive('item_id');
+   * ```
    */
   archive(itemId: string, options?: Core.RequestOptions): Core.APIPromise<Item> {
     return this._client.post(`/items/${itemId}/archive`, options);
@@ -49,6 +74,11 @@ export class Items extends APIResource {
 
   /**
    * This endpoint returns an item identified by its item_id.
+   *
+   * @example
+   * ```ts
+   * const item = await client.items.fetch('item_id');
+   * ```
    */
   fetch(itemId: string, options?: Core.RequestOptions): Core.APIPromise<Item> {
     return this._client.get(`/items/${itemId}`, options);