orb-billing 4.74.0 → 5.1.0

package/src/resources/credit-notes.ts

@@ -3,14 +3,41 @@
 import { APIResource } from '../resource';
 import { isRequestOptions } from '../core';
 import * as Core from '../core';
-import { Page, type PageParams } from '../pagination';
+import * as Shared from './shared';
+import { CreditNotesPage } from './shared';
+import { type PageParams } from '../pagination';
 
 export class CreditNotes extends APIResource {
   /**
    * This endpoint is used to create a single
    * [`Credit Note`](/invoicing/credit-notes).
-   */
-  create(body: CreditNoteCreateParams, options?: Core.RequestOptions): Core.APIPromise<CreditNote> {
+   *
+   * The credit note service period configuration supports two explicit modes:
+   *
+   * 1. Global service periods: Specify start_date and end_date at the credit note
+   *    level. These dates will be applied to all line items uniformly.
+   *
+   * 2. Individual service periods: Specify start_date and end_date for each line
+   *    item. When using this mode, ALL line items must have individual periods
+   *    specified.
+   *
+   * 3. Default behavior: If no service periods are specified (neither global nor
+   *    individual), the original invoice line item service periods will be used.
+   *
+   * Note: Mixing global and individual service periods in the same request is not
+   * allowed to prevent confusion.
+   *
+   * Service period dates are normalized to the start of the day in the customer's
+   * timezone to ensure consistent handling across different timezones.
+   *
+   * Date Format: Use start_date and end_date with format "YYYY-MM-DD" (e.g.,
+   * "2023-09-22") to match other Orb APIs like /v1/invoice_line_items.
+   *
+   * Note: Both start_date and end_date are inclusive - the service period will cover
+   * both the start date and end date completely (from start of start_date to end of
+   * end_date).
+   */
+  create(body: CreditNoteCreateParams, options?: Core.RequestOptions): Core.APIPromise<Shared.CreditNote> {
     return this._client.post('/credit_notes', { body, ...options });
   }
 
@@ -22,12 +49,12 @@ export class CreditNotes extends APIResource {
   list(
     query?: CreditNoteListParams,
     options?: Core.RequestOptions,
-  ): Core.PagePromise<CreditNotesPage, CreditNote>;
-  list(options?: Core.RequestOptions): Core.PagePromise<CreditNotesPage, CreditNote>;
+  ): Core.PagePromise<CreditNotesPage, Shared.CreditNote>;
+  list(options?: Core.RequestOptions): Core.PagePromise<CreditNotesPage, Shared.CreditNote>;
   list(
     query: CreditNoteListParams | Core.RequestOptions = {},
     options?: Core.RequestOptions,
-  ): Core.PagePromise<CreditNotesPage, CreditNote> {
+  ): Core.PagePromise<CreditNotesPage, Shared.CreditNote> {
     if (isRequestOptions(query)) {
       return this.list({}, query);
     }
@@ -38,243 +65,69 @@ export class CreditNotes extends APIResource {
    * This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes)
    * given an identifier.
    */
-  fetch(creditNoteId: string, options?: Core.RequestOptions): Core.APIPromise<CreditNote> {
+  fetch(creditNoteId: string, options?: Core.RequestOptions): Core.APIPromise<Shared.CreditNote> {
     return this._client.get(`/credit_notes/${creditNoteId}`, options);
   }
 }
 
-export class CreditNotesPage extends Page<CreditNote> {}
-
-/**
- * The [Credit Note](/invoicing/credit-notes) resource represents a credit that has
- * been applied to a particular invoice.
- */
-export interface CreditNote {
-  /**
-   * The Orb id of this credit note.
-   */
-  id: string;
-
-  /**
-   * The creation time of the resource in Orb.
-   */
-  created_at: string;
-
-  /**
-   * The unique identifier for credit notes.
-   */
-  credit_note_number: string;
-
-  /**
-   * A URL to a PDF of the credit note.
-   */
-  credit_note_pdf: string | null;
-
-  customer: CreditNote.Customer;
-
-  /**
-   * The id of the invoice resource that this credit note is applied to.
-   */
-  invoice_id: string;
-
-  /**
-   * All of the line items associated with this credit note.
-   */
-  line_items: Array<CreditNote.LineItem>;
-
-  /**
-   * The maximum amount applied on the original invoice
-   */
-  maximum_amount_adjustment: CreditNote.MaximumAmountAdjustment | null;
-
-  /**
-   * An optional memo supplied on the credit note.
-   */
-  memo: string | null;
-
-  /**
-   * Any credited amount from the applied minimum on the invoice.
-   */
-  minimum_amount_refunded: string | null;
-
-  reason: 'Duplicate' | 'Fraudulent' | 'Order change' | 'Product unsatisfactory' | null;
+export interface CreditNoteCreateParams {
+  line_items: Array<CreditNoteCreateParams.LineItem>;
 
   /**
-   * The total prior to any creditable invoice-level discounts or minimums.
+   * An optional reason for the credit note.
    */
-  subtotal: string;
+  reason: 'duplicate' | 'fraudulent' | 'order_change' | 'product_unsatisfactory';
 
   /**
-   * The total including creditable invoice-level discounts or minimums, and tax.
+   * A date string to specify the global credit note service period end date in the
+   * customer's timezone. This will be applied to all line items that don't have
+   * their own individual service periods specified. If not provided, line items will
+   * use their original invoice line item service periods. This date is inclusive.
    */
-  total: string;
-
-  type: 'refund' | 'adjustment';
+  end_date?: string | null;
 
   /**
-   * The time at which the credit note was voided in Orb, if applicable.
+   * An optional memo to attach to the credit note.
    */
-  voided_at: string | null;
+  memo?: string | null;
 
   /**
-   * Any discounts applied on the original invoice.
+   * A date string to specify the global credit note service period start date in the
+   * customer's timezone. This will be applied to all line items that don't have
+   * their own individual service periods specified. If not provided, line items will
+   * use their original invoice line item service periods. This date is inclusive.
    */
-  discounts?: Array<CreditNote.Discount>;
+  start_date?: string | null;
 }
 
-export namespace CreditNote {
-  export interface Customer {
-    id: string;
-
-    external_customer_id: string | null;
-  }
-
+export namespace CreditNoteCreateParams {
   export interface LineItem {
     /**
-     * The Orb id of this resource.
-     */
-    id: string;
-
-    /**
-     * The amount of the line item, including any line item minimums and discounts.
+     * The total amount in the invoice's currency to credit this line item.
      */
     amount: string;
 
     /**
-     * The id of the item associated with this line item.
-     */
-    item_id: string;
-
-    /**
-     * The name of the corresponding invoice line item.
-     */
-    name: string;
-
-    /**
-     * An optional quantity credited.
-     */
-    quantity: number | null;
-
-    /**
-     * The amount of the line item, excluding any line item minimums and discounts.
-     */
-    subtotal: string;
-
-    /**
-     * Any tax amounts applied onto the line item.
-     */
-    tax_amounts: Array<LineItem.TaxAmount>;
-
-    /**
-     * Any line item discounts from the invoice's line item.
+     * The ID of the line item to credit.
      */
-    discounts?: Array<LineItem.Discount>;
-  }
-
-  export namespace LineItem {
-    export interface TaxAmount {
-      /**
-       * The amount of additional tax incurred by this tax rate.
-       */
-      amount: string;
-
-      /**
-       * The human-readable description of the applied tax rate.
-       */
-      tax_rate_description: string;
-
-      /**
-       * The tax rate percentage, out of 100.
-       */
-      tax_rate_percentage: string | null;
-    }
-
-    export interface Discount {
-      id: string;
-
-      amount_applied: string;
-
-      applies_to_price_ids: Array<string>;
-
-      discount_type: 'percentage' | 'amount';
-
-      percentage_discount: number;
-
-      amount_discount?: string | null;
-
-      reason?: string | null;
-    }
-  }
-
-  /**
-   * The maximum amount applied on the original invoice
-   */
-  export interface MaximumAmountAdjustment {
-    amount_applied: string;
-
-    discount_type: 'percentage';
-
-    percentage_discount: number;
-
-    applies_to_prices?: Array<MaximumAmountAdjustment.AppliesToPrice> | null;
-
-    reason?: string | null;
-  }
-
-  export namespace MaximumAmountAdjustment {
-    export interface AppliesToPrice {
-      id: string;
-
-      name: string;
-    }
-  }
-
-  export interface Discount {
-    amount_applied: string;
-
-    discount_type: 'percentage';
-
-    percentage_discount: number;
-
-    applies_to_prices?: Array<Discount.AppliesToPrice> | null;
-
-    reason?: string | null;
-  }
-
-  export namespace Discount {
-    export interface AppliesToPrice {
-      id: string;
-
-      name: string;
-    }
-  }
-}
-
-export interface CreditNoteCreateParams {
-  line_items: Array<CreditNoteCreateParams.LineItem>;
-
-  /**
-   * An optional reason for the credit note.
-   */
-  reason: 'duplicate' | 'fraudulent' | 'order_change' | 'product_unsatisfactory';
-
-  /**
-   * An optional memo to attach to the credit note.
-   */
-  memo?: string | null;
-}
+    invoice_line_item_id: string;
 
-export namespace CreditNoteCreateParams {
-  export interface LineItem {
     /**
-     * The total amount in the invoice's currency to credit this line item.
+     * A date string to specify this line item's credit note service period end date in
+     * the customer's timezone. If provided, this will be used for this specific line
+     * item. If not provided, will use the global end_date if available, otherwise
+     * defaults to the original invoice line item's end date. This date is inclusive.
      */
-    amount: string;
+    end_date?: string | null;
 
     /**
-     * The ID of the line item to credit.
+     * A date string to specify this line item's credit note service period start date
+     * in the customer's timezone. If provided, this will be used for this specific
+     * line item. If not provided, will use the global start_date if available,
+     * otherwise defaults to the original invoice line item's start date. This date is
+     * inclusive.
      */
-    invoice_line_item_id: string;
+    start_date?: string | null;
   }
 }
 
@@ -288,13 +141,11 @@ export interface CreditNoteListParams extends PageParams {
   'created_at[lte]'?: string | null;
 }
 
-CreditNotes.CreditNotesPage = CreditNotesPage;
-
 export declare namespace CreditNotes {
   export {
-    type CreditNote as CreditNote,
-    CreditNotesPage as CreditNotesPage,
     type CreditNoteCreateParams as CreditNoteCreateParams,
     type CreditNoteListParams as CreditNoteListParams,
   };
 }
+
+export { CreditNotesPage };

package/src/resources/customers/balance-transactions.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../../resource';
 import { isRequestOptions } from '../../core';
 import * as Core from '../../core';
+import * as Shared from '../shared';
 import { Page, type PageParams } from '../../pagination';
 
 export class BalanceTransactions extends APIResource {
@@ -95,7 +96,7 @@ export interface BalanceTransactionCreateResponse {
    */
   created_at: string;
 
-  credit_note: BalanceTransactionCreateResponse.CreditNote | null;
+  credit_note: Shared.CreditNoteTiny | null;
 
   /**
    * An optional description provided for manual customer balance adjustments.
@@ -108,7 +109,7 @@ export interface BalanceTransactionCreateResponse {
    */
   ending_balance: string;
 
-  invoice: BalanceTransactionCreateResponse.Invoice | null;
+  invoice: Shared.InvoiceTiny | null;
 
   /**
    * The original value of the customer's balance prior to the transaction, in the
@@ -119,22 +120,6 @@ export interface BalanceTransactionCreateResponse {
   type: 'increment' | 'decrement';
 }
 
-export namespace BalanceTransactionCreateResponse {
-  export interface CreditNote {
-    /**
-     * The id of the Credit note
-     */
-    id: string;
-  }
-
-  export interface Invoice {
-    /**
-     * The Invoice id
-     */
-    id: string;
-  }
-}
-
 export interface BalanceTransactionListResponse {
   /**
    * A unique id for this transaction.
@@ -162,7 +147,7 @@ export interface BalanceTransactionListResponse {
    */
   created_at: string;
 
-  credit_note: BalanceTransactionListResponse.CreditNote | null;
+  credit_note: Shared.CreditNoteTiny | null;
 
   /**
    * An optional description provided for manual customer balance adjustments.
@@ -175,7 +160,7 @@ export interface BalanceTransactionListResponse {
    */
   ending_balance: string;
 
-  invoice: BalanceTransactionListResponse.Invoice | null;
+  invoice: Shared.InvoiceTiny | null;
 
   /**
    * The original value of the customer's balance prior to the transaction, in the
@@ -186,22 +171,6 @@ export interface BalanceTransactionListResponse {
   type: 'increment' | 'decrement';
 }
 
-export namespace BalanceTransactionListResponse {
-  export interface CreditNote {
-    /**
-     * The id of the Credit note
-     */
-    id: string;
-  }
-
-  export interface Invoice {
-    /**
-     * The Invoice id
-     */
-    id: string;
-  }
-}
-
 export interface BalanceTransactionCreateParams {
   amount: string;
 

package/src/resources/customers/costs.ts

@@ -3,7 +3,7 @@
 import { APIResource } from '../../resource';
 import { isRequestOptions } from '../../core';
 import * as Core from '../../core';
-import * as PricesAPI from '../prices/prices';
+import * as Shared from '../shared';
 
 export class Costs extends APIResource {
   /**
@@ -60,17 +60,17 @@ export class Costs extends APIResource {
    *
    * A customer that uses a few API calls a day but has a minimum commitment might
    * exhibit the following pattern for their subtotal and total in the first few days
-   * of the month. Here, we assume that each API call is $2.50, the customer's plan
-   * has a monthly minimum of $50 for this price, and that the subscription's billing
-   * period bounds are aligned to the first of the month:
+   * of the month. Here, we assume that each API call is \$2.50, the customer's plan
+   * has a monthly minimum of \$50 for this price, and that the subscription's
+   * billing period bounds are aligned to the first of the month:
    *
    * | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
    * | --------------- | ------------- | ---------------- | -------- | ------------------------ |
-   * | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
-   * | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
-   * | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
-   * | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
-   * | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+   * | 2023-02-01      | 2023-02-02    | 9                | \$22.50  | \$50.00                  |
+   * | 2023-02-01      | 2023-02-03    | 19               | \$47.50  | \$50.00                  |
+   * | 2023-02-01      | 2023-02-04    | 20               | \$50.00  | \$50.00                  |
+   * | 2023-02-01      | 2023-02-05    | 28               | \$70.00  | \$70.00                  |
+   * | 2023-02-01      | 2023-02-06    | 36               | \$90.00  | \$90.00                  |
    *
    * ### Periodic values
    *
@@ -196,17 +196,17 @@ export class Costs extends APIResource {
    *
    * A customer that uses a few API calls a day but has a minimum commitment might
    * exhibit the following pattern for their subtotal and total in the first few days
-   * of the month. Here, we assume that each API call is $2.50, the customer's plan
-   * has a monthly minimum of $50 for this price, and that the subscription's billing
-   * period bounds are aligned to the first of the month:
+   * of the month. Here, we assume that each API call is \$2.50, the customer's plan
+   * has a monthly minimum of \$50 for this price, and that the subscription's
+   * billing period bounds are aligned to the first of the month:
    *
    * | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
    * | --------------- | ------------- | ---------------- | -------- | ------------------------ |
-   * | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
-   * | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
-   * | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
-   * | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
-   * | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+   * | 2023-02-01      | 2023-02-02    | 9                | \$22.50  | \$50.00                  |
+   * | 2023-02-01      | 2023-02-03    | 19               | \$47.50  | \$50.00                  |
+   * | 2023-02-01      | 2023-02-04    | 20               | \$50.00  | \$50.00                  |
+   * | 2023-02-01      | 2023-02-05    | 28               | \$70.00  | \$70.00                  |
+   * | 2023-02-01      | 2023-02-06    | 36               | \$90.00  | \$90.00                  |
    *
    * ### Periodic values
    *
@@ -286,109 +286,11 @@ export class Costs extends APIResource {
 }
 
 export interface CostListResponse {
-  data: Array<CostListResponse.Data>;
-}
-
-export namespace CostListResponse {
-  export interface Data {
-    per_price_costs: Array<Data.PerPriceCost>;
-
-    /**
-     * Total costs for the timeframe, excluding any minimums and discounts.
-     */
-    subtotal: string;
-
-    timeframe_end: string;
-
-    timeframe_start: string;
-
-    /**
-     * Total costs for the timeframe, including any minimums and discounts.
-     */
-    total: string;
-  }
-
-  export namespace Data {
-    export interface PerPriceCost {
-      /**
-       * The price object
-       */
-      price: PricesAPI.Price;
-
-      /**
-       * The price the cost is associated with
-       */
-      price_id: string;
-
-      /**
-       * Price's contributions for the timeframe, excluding any minimums and discounts.
-       */
-      subtotal: string;
-
-      /**
-       * Price's contributions for the timeframe, including minimums and discounts.
-       */
-      total: string;
-
-      /**
-       * The price's quantity for the timeframe
-       */
-      quantity?: number | null;
-    }
-  }
+  data: Array<Shared.AggregatedCost>;
 }
 
 export interface CostListByExternalIDResponse {
-  data: Array<CostListByExternalIDResponse.Data>;
-}
-
-export namespace CostListByExternalIDResponse {
-  export interface Data {
-    per_price_costs: Array<Data.PerPriceCost>;
-
-    /**
-     * Total costs for the timeframe, excluding any minimums and discounts.
-     */
-    subtotal: string;
-
-    timeframe_end: string;
-
-    timeframe_start: string;
-
-    /**
-     * Total costs for the timeframe, including any minimums and discounts.
-     */
-    total: string;
-  }
-
-  export namespace Data {
-    export interface PerPriceCost {
-      /**
-       * The price object
-       */
-      price: PricesAPI.Price;
-
-      /**
-       * The price the cost is associated with
-       */
-      price_id: string;
-
-      /**
-       * Price's contributions for the timeframe, excluding any minimums and discounts.
-       */
-      subtotal: string;
-
-      /**
-       * Price's contributions for the timeframe, including minimums and discounts.
-       */
-      total: string;
-
-      /**
-       * The price's quantity for the timeframe
-       */
-      quantity?: number | null;
-    }
-  }
+  data: Array<Shared.AggregatedCost>;
 }
 
 export interface CostListParams {

package/src/resources/customers/credits/credits.ts

@@ -5,6 +5,12 @@ import { isRequestOptions } from '../../../core';
 import * as Core from '../../../core';
 import * as LedgerAPI from './ledger';
 import {
+  AffectedBlock,
+  AmendmentLedgerEntry,
+  CreditBlockExpiryLedgerEntry,
+  DecrementLedgerEntry,
+  ExpirationChangeLedgerEntry,
+  IncrementLedgerEntry,
   Ledger,
   LedgerCreateEntryByExternalIDParams,
   LedgerCreateEntryByExternalIDResponse,
@@ -16,6 +22,8 @@ import {
   LedgerListParams,
   LedgerListResponse,
   LedgerListResponsesPage,
+  VoidInitiatedLedgerEntry,
+  VoidLedgerEntry,
 } from './ledger';
 import * as TopUpsAPI from './top-ups';
 import {
@@ -23,6 +31,7 @@ import {
   TopUpCreateByExternalIDResponse,
   TopUpCreateParams,
   TopUpCreateResponse,
+  TopUpInvoiceSettings,
   TopUpListByExternalIDParams,
   TopUpListByExternalIDResponse,
   TopUpListByExternalIDResponsesPage,
@@ -186,6 +195,14 @@ export declare namespace Credits {
 
   export {
     Ledger as Ledger,
+    type AffectedBlock as AffectedBlock,
+    type AmendmentLedgerEntry as AmendmentLedgerEntry,
+    type CreditBlockExpiryLedgerEntry as CreditBlockExpiryLedgerEntry,
+    type DecrementLedgerEntry as DecrementLedgerEntry,
+    type ExpirationChangeLedgerEntry as ExpirationChangeLedgerEntry,
+    type IncrementLedgerEntry as IncrementLedgerEntry,
+    type VoidInitiatedLedgerEntry as VoidInitiatedLedgerEntry,
+    type VoidLedgerEntry as VoidLedgerEntry,
     type LedgerListResponse as LedgerListResponse,
     type LedgerCreateEntryResponse as LedgerCreateEntryResponse,
     type LedgerCreateEntryByExternalIDResponse as LedgerCreateEntryByExternalIDResponse,
@@ -200,6 +217,7 @@ export declare namespace Credits {
 
   export {
     TopUps as TopUps,
+    type TopUpInvoiceSettings as TopUpInvoiceSettings,
     type TopUpCreateResponse as TopUpCreateResponse,
     type TopUpListResponse as TopUpListResponse,
     type TopUpCreateByExternalIDResponse as TopUpCreateByExternalIDResponse,

package/src/resources/customers/credits/index.ts

@@ -13,6 +13,14 @@ export {
   LedgerListResponsesPage,
   LedgerListByExternalIDResponsesPage,
   Ledger,
+  type AffectedBlock,
+  type AmendmentLedgerEntry,
+  type CreditBlockExpiryLedgerEntry,
+  type DecrementLedgerEntry,
+  type ExpirationChangeLedgerEntry,
+  type IncrementLedgerEntry,
+  type VoidInitiatedLedgerEntry,
+  type VoidLedgerEntry,
   type LedgerListResponse,
   type LedgerCreateEntryResponse,
   type LedgerCreateEntryByExternalIDResponse,
@@ -26,6 +34,7 @@ export {
   TopUpListResponsesPage,
   TopUpListByExternalIDResponsesPage,
   TopUps,
+  type TopUpInvoiceSettings,
   type TopUpCreateResponse,
   type TopUpListResponse,
   type TopUpCreateByExternalIDResponse,