docs: update examples

Author: stainless-app[bot]

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);

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,

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);

src/resources/dimensional-price-groups/dimensional-price-groups.ts

@@ -24,6 +24,16 @@ export class DimensionalPriceGroups extends APIResource {
    * widgets used and we want to charge differently depending on the color of the
    * widget. We can create a price group with a dimension "color" and two prices: one
    * that charges \$10 per red widget and one that charges \$20 per blue widget.
+   *
+   * @example
+   * ```ts
+   * const dimensionalPriceGroup =
+   *   await client.dimensionalPriceGroups.create({
+   *     billable_metric_id: 'billable_metric_id',
+   *     dimensions: ['region', 'instance_type'],
+   *     name: 'name',
+   *   });
+   * ```
    */
   create(
     body: DimensionalPriceGroupCreateParams,
@@ -34,6 +44,14 @@ export class DimensionalPriceGroups extends APIResource {
 
   /**
    * Fetch dimensional price group
+   *
+   * @example
+   * ```ts
+   * const dimensionalPriceGroup =
+   *   await client.dimensionalPriceGroups.retrieve(
+   *     'dimensional_price_group_id',
+   *   );
+   * ```
    */
   retrieve(
     dimensionalPriceGroupId: string,
@@ -46,6 +64,14 @@ export class DimensionalPriceGroups extends APIResource {
    * This endpoint can be used to update the `external_dimensional_price_group_id`
    * and `metadata` of an existing dimensional price group. Other fields on a
    * dimensional price group are currently immutable.
+   *
+   * @example
+   * ```ts
+   * const dimensionalPriceGroup =
+   *   await client.dimensionalPriceGroups.update(
+   *     'dimensional_price_group_id',
+   *   );
+   * ```
    */
   update(
     dimensionalPriceGroupId: string,
@@ -57,6 +83,14 @@ export class DimensionalPriceGroups extends APIResource {
 
   /**
    * List dimensional price groups
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const dimensionalPriceGroup of client.dimensionalPriceGroups.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: DimensionalPriceGroupListParams,

src/resources/dimensional-price-groups/external-dimensional-price-group-id.ts

@@ -7,6 +7,14 @@ import * as DimensionalPriceGroupsAPI from './dimensional-price-groups';
 export class ExternalDimensionalPriceGroupID extends APIResource {
   /**
    * Fetch dimensional price group by external ID
+   *
+   * @example
+   * ```ts
+   * const dimensionalPriceGroup =
+   *   await client.dimensionalPriceGroups.externalDimensionalPriceGroupId.retrieve(
+   *     'external_dimensional_price_group_id',
+   *   );
+   * ```
    */
   retrieve(
     externalDimensionalPriceGroupId: string,
@@ -22,6 +30,14 @@ export class ExternalDimensionalPriceGroupID extends APIResource {
    * This endpoint can be used to update the `external_dimensional_price_group_id`
    * and `metadata` of an existing dimensional price group. Other fields on a
    * dimensional price group are currently immutable.
+   *
+   * @example
+   * ```ts
+   * const dimensionalPriceGroup =
+   *   await client.dimensionalPriceGroups.externalDimensionalPriceGroupId.update(
+   *     'external_dimensional_price_group_id',
+   *   );
+   * ```
    */
   update(
     externalDimensionalPriceGroupId: string,

src/resources/events/backfills.ts

@@ -52,6 +52,14 @@ export class Backfills extends APIResource {
    *
    * You may not have multiple backfills in a pending or pending_revert state with
    * overlapping timeframes.
+   *
+   * @example
+   * ```ts
+   * const backfill = await client.events.backfills.create({
+   *   timeframe_end: '2019-12-27T18:11:19.117Z',
+   *   timeframe_start: '2019-12-27T18:11:19.117Z',
+   * });
+   * ```
    */
   create(body: BackfillCreateParams, options?: Core.RequestOptions): Core.APIPromise<BackfillCreateResponse> {
     return this._client.post('/events/backfills', { body, ...options });
@@ -64,6 +72,14 @@ export class Backfills extends APIResource {
    * backfill. The response also includes
    * [`pagination_metadata`](/api-reference/pagination), which lets the caller
    * retrieve the next page of results if they exist.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const backfillListResponse of client.events.backfills.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query?: BackfillListParams,
@@ -85,13 +101,27 @@ export class Backfills extends APIResource {
    * backfill, Orb will asynchronously reflect the updated usage in invoice amounts
    * and usage graphs. Once all of the updates are complete, the backfill's status
    * will transition to `reflected`.
+   *
+   * @example
+   * ```ts
+   * const response = await client.events.backfills.close(
+   *   'backfill_id',
+   * );
+   * ```
    */
   close(backfillId: string, options?: Core.RequestOptions): Core.APIPromise<BackfillCloseResponse> {
     return this._client.post(`/events/backfills/${backfillId}/close`, options);
   }
 
   /**
    * This endpoint is used to fetch a backfill given an identifier.
+   *
+   * @example
+   * ```ts
+   * const response = await client.events.backfills.fetch(
+   *   'backfill_id',
+   * );
+   * ```
    */
   fetch(backfillId: string, options?: Core.RequestOptions): Core.APIPromise<BackfillFetchResponse> {
     return this._client.get(`/events/backfills/${backfillId}`, options);
@@ -105,6 +135,13 @@ export class Backfills extends APIResource {
    *
    * If a backfill is reverted before its closed, no usage will be updated as a
    * result of the backfill and it will immediately transition to `reverted`.
+   *
+   * @example
+   * ```ts
+   * const response = await client.events.backfills.revert(
+   *   'backfill_id',
+   * );
+   * ```
    */
   revert(backfillId: string, options?: Core.RequestOptions): Core.APIPromise<BackfillRevertResponse> {
     return this._client.post(`/events/backfills/${backfillId}/revert`, options);

src/resources/events/events.ts

@@ -72,6 +72,15 @@ export class Events extends APIResource {
    * - By default, no more than 100 events can be amended for a single customer in a
    *   100 day period. For higher volume updates, consider using the
    *   [event backfill](create-backfill) endpoint.
+   *
+   * @example
+   * ```ts
+   * const event = await client.events.update('event_id', {
+   *   event_name: 'event_name',
+   *   properties: { foo: 'bar' },
+   *   timestamp: '2020-12-09T16:09:53Z',
+   * });
+   * ```
    */
   update(
     eventId: string,
@@ -122,6 +131,11 @@ export class Events extends APIResource {
    * - By default, no more than 100 events can be deprecated for a single customer in
    *   a 100 day period. For higher volume updates, consider using the
    *   [event backfill](create-backfill) endpoint.
+   *
+   * @example
+   * ```ts
+   * const response = await client.events.deprecate('event_id');
+   * ```
    */
   deprecate(eventId: string, options?: Core.RequestOptions): Core.APIPromise<EventDeprecateResponse> {
     return this._client.put(`/events/${eventId}/deprecate`, options);
@@ -332,6 +346,20 @@ export class Events extends APIResource {
    *   "validation_failed": []
    * }
    * ```
+   *
+   * @example
+   * ```ts
+   * const response = await client.events.ingest({
+   *   events: [
+   *     {
+   *       event_name: 'event_name',
+   *       idempotency_key: 'idempotency_key',
+   *       properties: { foo: 'bar' },
+   *       timestamp: '2020-12-09T16:09:53Z',
+   *     },
+   *   ],
+   * });
+   * ```
    */
   ingest(params: EventIngestParams, options?: Core.RequestOptions): Core.APIPromise<EventIngestResponse> {
     const { backfill_id, debug, ...body } = params;
@@ -354,6 +382,13 @@ export class Events extends APIResource {
    *
    * By default, Orb will not throw a `404` if no events matched, Orb will return an
    * empty array for `data` instead.
+   *
+   * @example
+   * ```ts
+   * const response = await client.events.search({
+   *   event_ids: ['string'],
+   * });
+   * ```
    */
   search(body: EventSearchParams, options?: Core.RequestOptions): Core.APIPromise<EventSearchResponse> {
     return this._client.post('/events/search', { body, ...options });

src/resources/events/volume.ts

@@ -23,6 +23,13 @@ export class Volume extends APIResource {
    * where the start and end time are hour-aligned and in UTC. When a specific
    * timestamp is passed in for either start or end time, the response includes the
    * hours the timestamp falls in.
+   *
+   * @example
+   * ```ts
+   * const eventVolumes = await client.events.volume.list({
+   *   timeframe_start: '2019-12-27T18:11:19.117Z',
+   * });
+   * ```
    */
   list(query: VolumeListParams, options?: Core.RequestOptions): Core.APIPromise<EventVolumes> {
     return this._client.get('/events/volume', { query, ...options });

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,