API v2 に依存関係のある応答値を含める

特定のプロパティに対してデフォルトで null を返す API 応答を管理する方法をご紹介します。

一部の API v2 レスポンスには、実際の値に関係なく、特定のプロパティの null 値がデフォルトで含まれています。これにより、基本的なレスポンス構造を維持しながら、レスポンスペイロードのサイズを縮小できます。これらのプロパティの実際の値を取得するには、配列の include リクエストパラメーターで指定します。

特定のリクエストでincludeパラメータを使用する必要があるかどうかを判断するには、リクエストの説明をご覧ください。includeパラメータの列挙値は、includeパラメータに依存する応答プロパティを表します。

エンドポイント依存関係

レスポンスプロパティがデフォルトで null になるかどうかは、エンドポイントが参照するオブジェクトではなく、リクエストエンドポイントによって異なります。複数のエンドポイントが同じオブジェクトからデータを返す場合、特定のプロパティは、あるエンドポイントではincludeに依存する場合がありますが、別のエンドポイントではデフォルトで実際の値が返されます。

ハッシュプロパティは、1 つの include 値、または子プロパティに関連付けられた複数の include 値に依存する場合があります。たとえば、アカウントを更新するときに、identity ハッシュ全体の実際の値を返すには、include パラメーターで identity を指定します。それ以外の場合、レスポンスで identity ハッシュは null になります。ただし、configuration ハッシュの実際の値を返すには、リクエストで個別の設定を指定する必要があります。1つ以上の設定を指定するが、すべてを指定するわけではない場合、指定された設定は実際の値を返しますが、指定されていない設定は null を返します。設定を指定しない場合、レスポンスで configuration ハッシュは null になります。

次の例では、Accountを更新してcustomerとmerchantの設定を追加しますが、include パラメータにプロパティは指定しません。

レスポンスは以下のようになります。

{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": null,
  "contact_email": "furever@example.com",
  "created": "2025-06-09T21:16:03.000Z",
  "dashboard": "full",
  "defaults": null,
  "display_name": "Furever",
  "identity": null,
  "livemode": true,
  "metadata": {},
  "requirements": null
}

この例では同じリクエストを行いますが、include パラメータで configuration.customer と identity を指定します。

レスポンスにはcustomerの設定とidentityの詳細が含まれますが、その他すべての設定では null が返されます。

{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "automatic_indirect_tax": {
        ...
      },
      "billing": {
        ...
      },
      "capabilities": {
        ...
      },
      ...
    },
    "merchant": null,
    "recipient": null
  },
  "contact_email": "furever@example.com",
  "created": "2025-06-09T21:16:03.000Z",
  "dashboard": "full",
  "defaults": null,
  "display_name": "Furever",
  "identity": {
    "business_details": {
      "doing_business_as": "FurEver",
      "id_numbers": [
        {
          "type": "us_ein"
        }
      ],
      "product_description": "Saas pet grooming platform at furever.dev using Connect embedded components",
      "structure": "sole_proprietorship",
      "url": "http://accessible.stripe.com"
    },
    "country": "US"
  },
  "livemode": true,
  "metadata": {},
  "requirements": null
}