Einbindungsabhängige Antwortwerte in API v2
Erfahren Sie, wie Sie API-Antworten verwalten, die für bestimmte Eigenschaften standardmäßig Null zurückgeben.
Einige API-v2-Antworten enthalten standardmäßig Nullwerte für bestimmte Eigenschaften, unabhängig von deren tatsächlichen Werten. Dadurch wird die Größe der Antwort-Payloads reduziert, während die Grundstruktur der Antwort erhalten bleibt. Um die tatsächlichen Werte für diese Eigenschaften abzurufen, geben Sie sie in dem Anfrageparameter Array include.
Um festzustellen, ob Sie den Parameter include in einer bestimmten Anfrage verwenden müssen, sehen Sie sich die Beschreibung der Anfrage an. Die Enum-Werte des Parameters include stellen die Antwort-Eigenschaften dar, die vom Parameter include abhängen.
Endpoint-Abhängigkeit
Ob eine Antwort-Eigenschaft standardmäßig auf Null gesetzt wird, hängt vom Endpoint der Anfrage ab, nicht vom Objekt, auf das der Endpoint verweist. Wenn mehrere Endpunkte Daten von demselben Objekt zurückgeben, kann eine bestimmte Eigenschaft bei einem Endpunkt von include abhängen und bei einem anderen Endpunkt standardmäßig ihren tatsächlichen Wert zurückgeben.
Eine Hash-Eigenschaft kann von einem einzigen include-Wert oder von mehreren include-Werten abhängen, die mit ihren untergeordneten Eigenschaften verbunden sind. Wenn Sie beispielsweise bei der Aktualisierung eines Kontos aktuelle Werte für den gesamten identity-Hash zurückgeben möchten, geben Sie Identität im Parameter include an. Andernfalls ist der identity-Hash in der Antwort Null. Um jedoch tatsächliche Werte für den Hash configuration zurückzugeben, müssen Sie in der Anfrage individuelle Konfigurationen angeben. Wenn Sie mindestens eine, aber nicht alle Konfigurationen angeben, geben angegebene Konfigurationen tatsächliche Werte zurück und nicht angegebene Konfigurationen geben Null zurück. Wenn Sie keine Konfigurationen angeben, ist der Hash configuration in der Antwort Null.
Das folgende Beispiel aktualisiert ein Account, um die Konfigurationen customer und merchant hinzuzufügen, gibt aber keine Eigenschaften im Parameter include an:
Die Antwort könnte wie folgt aussehen:
{ "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 }
This example makes the same request, but specifies configuration. and identity in the include parameter:
Die Antwort enthält Details über die Konfiguration customer und identity, gibt aber für alle anderen Konfigurationen Null zurück:
{ "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 }