orb-billing 5.48.0 → 5.76.0

package/src/resources/coupons/coupons.ts

@@ -17,6 +17,17 @@ export class Coupons extends APIResource {
   /**
    * This endpoint allows the creation of coupons, which can then be redeemed at
    * subscription creation or plan change.
+   *
+   * @example
+   * ```ts
+   * const coupon = await client.coupons.create({
+   *   discount: {
+   *     discount_type: 'percentage',
+   *     percentage_discount: 0,
+   *   },
+   *   redemption_code: 'HALFOFF',
+   * });
+   * ```
    */
   create(body: CouponCreateParams, options?: Core.RequestOptions): Core.APIPromise<Coupon> {
     return this._client.post('/coupons', { body, ...options });
@@ -28,6 +39,14 @@ export class Coupons extends APIResource {
    * The list of coupons is ordered starting from the most recently created coupon.
    * The response also includes `pagination_metadata`, which lets the caller retrieve
    * the next page of results if they exist.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const coupon of client.coupons.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(query?: CouponListParams, options?: Core.RequestOptions): Core.PagePromise<CouponsPage, Coupon>;
   list(options?: Core.RequestOptions): Core.PagePromise<CouponsPage, Coupon>;
@@ -45,6 +64,11 @@ export class Coupons extends APIResource {
    * This endpoint allows a coupon to be archived. Archived coupons can no longer be
    * redeemed, and will be hidden from lists of active coupons. Additionally, once a
    * coupon is archived, its redemption code can be reused for a different coupon.
+   *
+   * @example
+   * ```ts
+   * const coupon = await client.coupons.archive('coupon_id');
+   * ```
    */
   archive(couponId: string, options?: Core.RequestOptions): Core.APIPromise<Coupon> {
     return this._client.post(`/coupons/${couponId}/archive`, options);
@@ -54,6 +78,11 @@ export class Coupons extends APIResource {
    * This endpoint retrieves a coupon by its ID. To fetch coupons by their redemption
    * code, use the [List coupons](list-coupons) endpoint with the redemption_code
    * parameter.
+   *
+   * @example
+   * ```ts
+   * const coupon = await client.coupons.fetch('coupon_id');
+   * ```
    */
   fetch(couponId: string, options?: Core.RequestOptions): Core.APIPromise<Coupon> {
     return this._client.get(`/coupons/${couponId}`, options);

package/src/resources/coupons/subscriptions.ts

@@ -16,6 +16,16 @@ export class Subscriptions extends APIResource {
    * coupon as a [paginated](/api-reference/pagination) list, ordered starting from
    * the most recently created subscription. For a full discussion of the
    * subscription resource, see [Subscription](/core-concepts#subscription).
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const subscription of client.coupons.subscriptions.list(
+   *   'coupon_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     couponId: string,

package/src/resources/credit-blocks.ts

@@ -42,14 +42,17 @@ export class CreditBlocks extends APIResource {
   /**
    * This endpoint returns the credit block and its associated purchasing invoices.
    *
-   * If a credit block was purchased (as opposed to being manually added or allocated
-   * from a subscription), this endpoint returns the invoices that were created to
-   * charge the customer for the credit block. For credit blocks with payment
-   * schedules spanning multiple periods (e.g., monthly payments over 12 months),
-   * multiple invoices will be returned.
+   * If a credit block was purchased (as opposed to being manually added), this
+   * endpoint returns the invoices that were created to charge the customer for the
+   * credit block. For credit blocks with payment schedules spanning multiple periods
+   * (e.g., monthly payments over 12 months), multiple invoices will be returned.
    *
-   * If the credit block was not purchased (e.g., manual increment, allocation), an
-   * empty invoices list is returned.
+   * For credit blocks created by subscription allocation prices, this endpoint
+   * returns the subscription invoice containing the allocation line item that
+   * created the block.
+   *
+   * If the credit block was not purchased (e.g., manual increment), an empty
+   * invoices list is returned.
    *
    * **Note: This endpoint is currently experimental and its interface may change in
    * future releases. Please contact support before building production integrations
@@ -71,6 +74,15 @@ export interface CreditBlockRetrieveResponse {
 
   balance: number;
 
+  /**
+   * How this credit block was created: `allocation` (a subscription's recurring
+   * credit allocation), `top_up` (an automatic balance-threshold top-up),
+   * `commitment` (a subscription commitment true-up rolled forward as credit), or
+   * `manual` (a manual credit ledger increment, including credits voided or expired
+   * off another block).
+   */
+  credit_block_source: 'allocation' | 'top_up' | 'commitment' | 'manual';
+
   effective_date: string | null;
 
   expiry_date: string | null;
@@ -90,6 +102,18 @@ export interface CreditBlockRetrieveResponse {
   per_unit_cost_basis: string | null;
 
   status: 'active' | 'pending_payment';
+
+  /**
+   * The credit allocation that funded a block. Extends the allocation resource
+   * serialized on prices with the catalog-item attribution of the funding price.
+   */
+  credit_allocation?: CreditBlockRetrieveResponse.CreditAllocation | null;
+
+  /**
+   * The subscription commitment whose true-up rolled forward into this credit block.
+   * Present only when `credit_block_source` is `commitment`.
+   */
+  credit_commitment?: CreditBlockRetrieveResponse.CreditCommitment | null;
 }
 
 export namespace CreditBlockRetrieveResponse {
@@ -109,6 +133,63 @@ export namespace CreditBlockRetrieveResponse {
      */
     values: Array<string>;
   }
+
+  /**
+   * The credit allocation that funded a block. Extends the allocation resource
+   * serialized on prices with the catalog-item attribution of the funding price.
+   */
+  export interface CreditAllocation {
+    allows_rollover: boolean;
+
+    currency: string;
+
+    custom_expiration: Shared.CustomExpiration | null;
+
+    /**
+     * The ID of the catalog item this block was allocated from, derived from the
+     * allocation's price.
+     */
+    item_id: string;
+
+    filters?: Array<CreditAllocation.Filter>;
+
+    license_type_id?: string | null;
+  }
+
+  export namespace CreditAllocation {
+    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>;
+    }
+  }
+
+  /**
+   * The subscription commitment whose true-up rolled forward into this credit block.
+   * Present only when `credit_block_source` is `commitment`.
+   */
+  export interface CreditCommitment {
+    /**
+     * The ID of the subscription commitment this block was rolled forward from.
+     */
+    id: string;
+
+    /**
+     * The subscription the commitment belongs to.
+     */
+    subscription_id?: string | null;
+  }
 }
 
 export interface CreditBlockListInvoicesResponse {
@@ -129,6 +210,15 @@ export namespace CreditBlockListInvoicesResponse {
 
     balance: number;
 
+    /**
+     * How this credit block was created: `allocation` (a subscription's recurring
+     * credit allocation), `top_up` (an automatic balance-threshold top-up),
+     * `commitment` (a subscription commitment true-up rolled forward as credit), or
+     * `manual` (a manual credit ledger increment, including credits voided or expired
+     * off another block).
+     */
+    credit_block_source: 'allocation' | 'top_up' | 'commitment' | 'manual';
+
     effective_date: string | null;
 
     expiry_date: string | null;
@@ -148,6 +238,18 @@ export namespace CreditBlockListInvoicesResponse {
     per_unit_cost_basis: string | null;
 
     status: 'active' | 'pending_payment';
+
+    /**
+     * The credit allocation that funded a block. Extends the allocation resource
+     * serialized on prices with the catalog-item attribution of the funding price.
+     */
+    credit_allocation?: Block.CreditAllocation | null;
+
+    /**
+     * The subscription commitment whose true-up rolled forward into this credit block.
+     * Present only when `credit_block_source` is `commitment`.
+     */
+    credit_commitment?: Block.CreditCommitment | null;
   }
 
   export namespace Block {
@@ -167,6 +269,63 @@ export namespace CreditBlockListInvoicesResponse {
        */
       values: Array<string>;
     }
+
+    /**
+     * The credit allocation that funded a block. Extends the allocation resource
+     * serialized on prices with the catalog-item attribution of the funding price.
+     */
+    export interface CreditAllocation {
+      allows_rollover: boolean;
+
+      currency: string;
+
+      custom_expiration: Shared.CustomExpiration | null;
+
+      /**
+       * The ID of the catalog item this block was allocated from, derived from the
+       * allocation's price.
+       */
+      item_id: string;
+
+      filters?: Array<CreditAllocation.Filter>;
+
+      license_type_id?: string | null;
+    }
+
+    export namespace CreditAllocation {
+      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>;
+      }
+    }
+
+    /**
+     * The subscription commitment whose true-up rolled forward into this credit block.
+     * Present only when `credit_block_source` is `commitment`.
+     */
+    export interface CreditCommitment {
+      /**
+       * The ID of the subscription commitment this block was rolled forward from.
+       */
+      id: string;
+
+      /**
+       * The subscription the commitment belongs to.
+       */
+      subscription_id?: string | null;
+    }
   }
 
   export interface Invoice {

package/src/resources/credit-notes.ts

@@ -40,6 +40,19 @@ export class CreditNotes extends APIResource {
    * 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).
+   *
+   * @example
+   * ```ts
+   * const creditNote = await client.creditNotes.create({
+   *   line_items: [
+   *     {
+   *       amount: 'amount',
+   *       invoice_line_item_id: '4khy3nwzktxv7',
+   *     },
+   *   ],
+   *   reason: 'duplicate',
+   * });
+   * ```
    */
   create(body: CreditNoteCreateParams, options?: Core.RequestOptions): Core.APIPromise<Shared.CreditNote> {
     return this._client.post('/credit_notes', { body, ...options });
@@ -49,6 +62,14 @@ export class CreditNotes extends APIResource {
    * Get a paginated list of CreditNotes. Users can also filter by customer_id,
    * subscription_id, or external_customer_id. The credit notes will be returned in
    * reverse chronological order by `creation_time`.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const creditNote of client.creditNotes.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: CreditNoteListParams,
@@ -68,6 +89,13 @@ export class CreditNotes extends APIResource {
   /**
    * This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes)
    * given an identifier.
+   *
+   * @example
+   * ```ts
+   * const creditNote = await client.creditNotes.fetch(
+   *   'credit_note_id',
+   * );
+   * ```
    */
   fetch(creditNoteId: string, options?: Core.RequestOptions): Core.APIPromise<Shared.CreditNote> {
     return this._client.get(`/credit_notes/${creditNoteId}`, options);

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

@@ -3,6 +3,7 @@
 import { APIResource } from '../../../resource';
 import { isRequestOptions } from '../../../core';
 import * as Core from '../../../core';
+import * as Shared from '../../shared';
 import * as LedgerAPI from './ledger';
 import {
   AffectedBlock,
@@ -134,6 +135,15 @@ export interface CreditListResponse {
 
   balance: number;
 
+  /**
+   * How this credit block was created: `allocation` (a subscription's recurring
+   * credit allocation), `top_up` (an automatic balance-threshold top-up),
+   * `commitment` (a subscription commitment true-up rolled forward as credit), or
+   * `manual` (a manual credit ledger increment, including credits voided or expired
+   * off another block).
+   */
+  credit_block_source: 'allocation' | 'top_up' | 'commitment' | 'manual';
+
   effective_date: string | null;
 
   expiry_date: string | null;
@@ -153,6 +163,18 @@ export interface CreditListResponse {
   per_unit_cost_basis: string | null;
 
   status: 'active' | 'pending_payment';
+
+  /**
+   * The credit allocation that funded a block. Extends the allocation resource
+   * serialized on prices with the catalog-item attribution of the funding price.
+   */
+  credit_allocation?: CreditListResponse.CreditAllocation | null;
+
+  /**
+   * The subscription commitment whose true-up rolled forward into this credit block.
+   * Present only when `credit_block_source` is `commitment`.
+   */
+  credit_commitment?: CreditListResponse.CreditCommitment | null;
 }
 
 export namespace CreditListResponse {
@@ -175,6 +197,63 @@ export namespace CreditListResponse {
      */
     values: Array<string>;
   }
+
+  /**
+   * The credit allocation that funded a block. Extends the allocation resource
+   * serialized on prices with the catalog-item attribution of the funding price.
+   */
+  export interface CreditAllocation {
+    allows_rollover: boolean;
+
+    currency: string;
+
+    custom_expiration: Shared.CustomExpiration | null;
+
+    /**
+     * The ID of the catalog item this block was allocated from, derived from the
+     * allocation's price.
+     */
+    item_id: string;
+
+    filters?: Array<CreditAllocation.Filter>;
+
+    license_type_id?: string | null;
+  }
+
+  export namespace CreditAllocation {
+    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>;
+    }
+  }
+
+  /**
+   * The subscription commitment whose true-up rolled forward into this credit block.
+   * Present only when `credit_block_source` is `commitment`.
+   */
+  export interface CreditCommitment {
+    /**
+     * The ID of the subscription commitment this block was rolled forward from.
+     */
+    id: string;
+
+    /**
+     * The subscription the commitment belongs to.
+     */
+    subscription_id?: string | null;
+  }
 }
 
 export interface CreditListByExternalIDResponse {
@@ -182,6 +261,15 @@ export interface CreditListByExternalIDResponse {
 
   balance: number;
 
+  /**
+   * How this credit block was created: `allocation` (a subscription's recurring
+   * credit allocation), `top_up` (an automatic balance-threshold top-up),
+   * `commitment` (a subscription commitment true-up rolled forward as credit), or
+   * `manual` (a manual credit ledger increment, including credits voided or expired
+   * off another block).
+   */
+  credit_block_source: 'allocation' | 'top_up' | 'commitment' | 'manual';
+
   effective_date: string | null;
 
   expiry_date: string | null;
@@ -201,6 +289,18 @@ export interface CreditListByExternalIDResponse {
   per_unit_cost_basis: string | null;
 
   status: 'active' | 'pending_payment';
+
+  /**
+   * The credit allocation that funded a block. Extends the allocation resource
+   * serialized on prices with the catalog-item attribution of the funding price.
+   */
+  credit_allocation?: CreditListByExternalIDResponse.CreditAllocation | null;
+
+  /**
+   * The subscription commitment whose true-up rolled forward into this credit block.
+   * Present only when `credit_block_source` is `commitment`.
+   */
+  credit_commitment?: CreditListByExternalIDResponse.CreditCommitment | null;
 }
 
 export namespace CreditListByExternalIDResponse {
@@ -223,6 +323,63 @@ export namespace CreditListByExternalIDResponse {
      */
     values: Array<string>;
   }
+
+  /**
+   * The credit allocation that funded a block. Extends the allocation resource
+   * serialized on prices with the catalog-item attribution of the funding price.
+   */
+  export interface CreditAllocation {
+    allows_rollover: boolean;
+
+    currency: string;
+
+    custom_expiration: Shared.CustomExpiration | null;
+
+    /**
+     * The ID of the catalog item this block was allocated from, derived from the
+     * allocation's price.
+     */
+    item_id: string;
+
+    filters?: Array<CreditAllocation.Filter>;
+
+    license_type_id?: string | null;
+  }
+
+  export namespace CreditAllocation {
+    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>;
+    }
+  }
+
+  /**
+   * The subscription commitment whose true-up rolled forward into this credit block.
+   * Present only when `credit_block_source` is `commitment`.
+   */
+  export interface CreditCommitment {
+    /**
+     * The ID of the subscription commitment this block was rolled forward from.
+     */
+    id: string;
+
+    /**
+     * The subscription the commitment belongs to.
+     */
+    subscription_id?: string | null;
+  }
 }
 
 export interface CreditListParams extends PageParams {

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

@@ -155,8 +155,9 @@ export class Ledger extends APIResource {
    * }
    * ```
    *
-   * Note that by default, Orb will always first increment any _negative_ balance in
-   * existing blocks before adding the remaining amount to the desired credit block.
+   * Note that an `increment` entry always creates a new credit block (defined by the
+   * optional `effective_date` and `expiry_date`); it never modifies an existing
+   * block.
    *
    * ### Invoicing for credits
    *
@@ -177,11 +178,17 @@ export class Ledger extends APIResource {
    * ## Deducting Credits
    *
    * Orb allows you to deduct credits from a customer by creating an entry of type
-   * `decrement`. Orb matches the algorithm for automatic deductions for determining
-   * which credit blocks to decrement from. In the case that the deduction leads to
-   * multiple ledger entries, the response from this endpoint will be the final
-   * deduction. Orb also optionally allows specifying a description to assist with
-   * auditing.
+   * `decrement`. A `decrement` entry records credits as usage and immediately
+   * recognizes revenue at the block's `per_unit_cost_basis`.
+   *
+   * For most credit removals, use `void` (no revenue impact) or `expiration_change`
+   * (revenue recognized on expiration) instead. Only use `decrement` when credits
+   * were genuinely consumed outside of normal event ingestion.
+   *
+   * Orb matches the algorithm for automatic deductions for determining which credit
+   * blocks to decrement from. In the case that the deduction leads to multiple
+   * ledger entries, the response from this endpoint will be the final deduction. Orb
+   * also optionally allows specifying a description to assist with auditing.
    *
    * The following snippet illustrates a sample request body to decrement credits.
    *
@@ -282,8 +289,9 @@ export class Ledger extends APIResource {
    * }
    * ```
    *
-   * Note that by default, Orb will always first increment any _negative_ balance in
-   * existing blocks before adding the remaining amount to the desired credit block.
+   * Note that an `increment` entry always creates a new credit block (defined by the
+   * optional `effective_date` and `expiry_date`); it never modifies an existing
+   * block.
    *
    * ### Invoicing for credits
    *
@@ -304,11 +312,17 @@ export class Ledger extends APIResource {
    * ## Deducting Credits
    *
    * Orb allows you to deduct credits from a customer by creating an entry of type
-   * `decrement`. Orb matches the algorithm for automatic deductions for determining
-   * which credit blocks to decrement from. In the case that the deduction leads to
-   * multiple ledger entries, the response from this endpoint will be the final
-   * deduction. Orb also optionally allows specifying a description to assist with
-   * auditing.
+   * `decrement`. A `decrement` entry records credits as usage and immediately
+   * recognizes revenue at the block's `per_unit_cost_basis`.
+   *
+   * For most credit removals, use `void` (no revenue impact) or `expiration_change`
+   * (revenue recognized on expiration) instead. Only use `decrement` when credits
+   * were genuinely consumed outside of normal event ingestion.
+   *
+   * Orb matches the algorithm for automatic deductions for determining which credit
+   * blocks to decrement from. In the case that the deduction leads to multiple
+   * ledger entries, the response from this endpoint will be the final deduction. Orb
+   * also optionally allows specifying a description to assist with auditing.
    *
    * The following snippet illustrates a sample request body to decrement credits.
    *
@@ -1040,9 +1054,9 @@ export declare namespace LedgerCreateEntryParams {
     entry_type: 'expiration_change';
 
     /**
-     * A future date (specified in YYYY-MM-DD format) used for expiration change,
-     * denoting when credits transferred (as part of a partial block expiration) should
-     * expire.
+     * A date (specified in YYYY-MM-DD format) used for expiration change, denoting
+     * when credits transferred (as part of a partial block expiration) should expire.
+     * This date must be on or after the effective date of the credit block.
      */
     target_expiry_date: string;
 
@@ -1344,9 +1358,9 @@ export declare namespace LedgerCreateEntryByExternalIDParams {
     entry_type: 'expiration_change';
 
     /**
-     * A future date (specified in YYYY-MM-DD format) used for expiration change,
-     * denoting when credits transferred (as part of a partial block expiration) should
-     * expire.
+     * A date (specified in YYYY-MM-DD format) used for expiration change, denoting
+     * when credits transferred (as part of a partial block expiration) should expire.
+     * This date must be on or after the effective date of the credit block.
      */
     target_expiry_date: string;