From 18f944bdaebf7d6fce395bf0b7bf820230f0f317 Mon Sep 17 00:00:00 2001
From: Stainless Bot <dev@stainlessapi.com>
Date: Thu, 23 Nov 2023 17:07:27 +0000
Subject: [PATCH] docs(api): update metadata docstrings

---
 src/resources/customers/credits/ledger.ts | 208 +++++++++++++++-------
 src/resources/customers/customers.ts      |  18 +-
 src/resources/invoices.ts                 |  12 +-
 src/resources/metrics.ts                  |  22 ++-
 src/resources/plans/external-plan-id.ts   |   4 +-
 src/resources/plans/plans.ts              |  14 +-
 src/resources/subscriptions.ts            |  10 +-
 7 files changed, 198 insertions(+), 90 deletions(-)

diff --git a/src/resources/customers/credits/ledger.ts b/src/resources/customers/credits/ledger.ts
index 1a4aeed2..1787e10e 100644
--- a/src/resources/customers/credits/ledger.ts
+++ b/src/resources/customers/credits/ledger.ts
@@ -502,8 +502,10 @@ export namespace LedgerListResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -548,8 +550,10 @@ export namespace LedgerListResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -600,8 +604,10 @@ export namespace LedgerListResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -648,8 +654,10 @@ export namespace LedgerListResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -694,8 +702,10 @@ export namespace LedgerListResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -744,8 +754,10 @@ export namespace LedgerListResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -796,8 +808,10 @@ export namespace LedgerListResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -857,8 +871,10 @@ export namespace LedgerCreateEntryResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -903,8 +919,10 @@ export namespace LedgerCreateEntryResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -955,8 +973,10 @@ export namespace LedgerCreateEntryResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1003,8 +1023,10 @@ export namespace LedgerCreateEntryResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1049,8 +1071,10 @@ export namespace LedgerCreateEntryResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1099,8 +1123,10 @@ export namespace LedgerCreateEntryResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1151,8 +1177,10 @@ export namespace LedgerCreateEntryResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1212,8 +1240,10 @@ export namespace LedgerCreateEntryByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1258,8 +1288,10 @@ export namespace LedgerCreateEntryByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1310,8 +1342,10 @@ export namespace LedgerCreateEntryByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1358,8 +1392,10 @@ export namespace LedgerCreateEntryByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1404,8 +1440,10 @@ export namespace LedgerCreateEntryByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1454,8 +1492,10 @@ export namespace LedgerCreateEntryByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1506,8 +1546,10 @@ export namespace LedgerCreateEntryByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1567,8 +1609,10 @@ export namespace LedgerListByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1613,8 +1657,10 @@ export namespace LedgerListByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1665,8 +1711,10 @@ export namespace LedgerListByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1713,8 +1761,10 @@ export namespace LedgerListByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1759,8 +1809,10 @@ export namespace LedgerListByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1809,8 +1861,10 @@ export namespace LedgerListByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1861,8 +1915,10 @@ export namespace LedgerListByExternalIDResponse {
     ledger_sequence_number: number;
 
     /**
-     * User specified key-value pairs. If not provided, this defaults to an empty
-     * dictionary.
+     * User specified key-value pairs for the resource. If not present, this defaults
+     * to an empty dictionary. Individual keys can be removed by setting the value to
+     * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+     * `null`.
      */
     metadata: Record<string, string>;
 
@@ -1957,7 +2013,9 @@ export namespace LedgerCreateEntryParams {
     invoice_settings?: LedgerCreateEntryParams.AddIncrementCreditLedgerEntryRequestParams.InvoiceSettings | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
 
@@ -2013,7 +2071,9 @@ export namespace LedgerCreateEntryParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
   }
@@ -2054,7 +2114,9 @@ export namespace LedgerCreateEntryParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
   }
@@ -2081,7 +2143,9 @@ export namespace LedgerCreateEntryParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
 
@@ -2113,7 +2177,9 @@ export namespace LedgerCreateEntryParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
   }
@@ -2164,7 +2230,9 @@ export namespace LedgerCreateEntryByExternalIDParams {
     invoice_settings?: LedgerCreateEntryByExternalIDParams.AddIncrementCreditLedgerEntryRequestParams.InvoiceSettings | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
 
@@ -2220,7 +2288,9 @@ export namespace LedgerCreateEntryByExternalIDParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
   }
@@ -2261,7 +2331,9 @@ export namespace LedgerCreateEntryByExternalIDParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
   }
@@ -2288,7 +2360,9 @@ export namespace LedgerCreateEntryByExternalIDParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
 
@@ -2320,7 +2394,9 @@ export namespace LedgerCreateEntryByExternalIDParams {
     description?: string | null;
 
     /**
-     * User-specified key/value pairs for the resource.
+     * User-specified key/value pairs for the resource. Individual keys can be removed
+     * by setting the value to `null`, and the entire metadata mapping can be cleared
+     * by setting `metadata` to `null`.
      */
     metadata?: Record<string, string | null> | null;
   }
diff --git a/src/resources/customers/customers.ts b/src/resources/customers/customers.ts
index b223354e..ca47685e 100644
--- a/src/resources/customers/customers.ts
+++ b/src/resources/customers/customers.ts
@@ -206,8 +206,10 @@ export interface Customer {
   external_customer_id: string | null;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
@@ -632,7 +634,9 @@ export interface CustomerCreateParams {
   external_customer_id?: string | null;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;
 
@@ -1034,7 +1038,9 @@ export interface CustomerUpdateParams {
   email_delivery?: boolean | null;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;
 
@@ -1448,7 +1454,9 @@ export interface CustomerUpdateByExternalIDParams {
   email_delivery?: boolean | null;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;
 
diff --git a/src/resources/invoices.ts b/src/resources/invoices.ts
index db4a9832..099d791c 100644
--- a/src/resources/invoices.ts
+++ b/src/resources/invoices.ts
@@ -299,8 +299,10 @@ export interface Invoice {
   memo: string | null;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
@@ -1368,8 +1370,10 @@ export interface InvoiceFetchUpcomingResponse {
   memo: string | null;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
diff --git a/src/resources/metrics.ts b/src/resources/metrics.ts
index e7d6f248..df1bd64d 100644
--- a/src/resources/metrics.ts
+++ b/src/resources/metrics.ts
@@ -67,8 +67,10 @@ export interface MetricCreateResponse {
   item: ItemsAPI.Item;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
@@ -95,8 +97,10 @@ export interface MetricListResponse {
   item: ItemsAPI.Item;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
@@ -123,8 +127,10 @@ export interface MetricFetchResponse {
   item: ItemsAPI.Item;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
@@ -155,7 +161,9 @@ export interface MetricCreateParams {
   sql: string;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;
 }
diff --git a/src/resources/plans/external-plan-id.ts b/src/resources/plans/external-plan-id.ts
index 8663f887..bfd80a08 100644
--- a/src/resources/plans/external-plan-id.ts
+++ b/src/resources/plans/external-plan-id.ts
@@ -66,7 +66,9 @@ export interface ExternalPlanIDUpdateParams {
   external_plan_id?: string | null;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;
 }
diff --git a/src/resources/plans/plans.ts b/src/resources/plans/plans.ts
index 44127333..ed29a3c3 100644
--- a/src/resources/plans/plans.ts
+++ b/src/resources/plans/plans.ts
@@ -136,8 +136,10 @@ export interface Plan {
   maximum_amount: string | null;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
@@ -321,7 +323,9 @@ export interface PlanCreateParams {
   external_plan_id?: string | null;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;
 
@@ -1135,7 +1139,9 @@ export interface PlanUpdateParams {
   external_plan_id?: string | null;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;
 }
diff --git a/src/resources/subscriptions.ts b/src/resources/subscriptions.ts
index 2c552cc5..a8416bdb 100644
--- a/src/resources/subscriptions.ts
+++ b/src/resources/subscriptions.ts
@@ -1127,8 +1127,10 @@ export interface Subscription {
   maximum_intervals: Array<Subscription.MaximumInterval>;
 
   /**
-   * User specified key-value pairs. If not provided, this defaults to an empty
-   * dictionary.
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. Individual keys can be removed by setting the value to
+   * `null`, and the entire metadata mapping can be cleared by setting `metadata` to
+   * `null`.
    */
   metadata: Record<string, string>;
 
@@ -2091,7 +2093,9 @@ export interface SubscriptionCreateParams {
   invoicing_threshold?: string | null;
 
   /**
-   * User-specified key/value pairs for the resource.
+   * User-specified key/value pairs for the resource. Individual keys can be removed
+   * by setting the value to `null`, and the entire metadata mapping can be cleared
+   * by setting `metadata` to `null`.
    */
   metadata?: Record<string, string | null> | null;