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 miteinbeziehen.
Um festzustellen, ob Sie den Parameter einbeziehen in einer bestimmten Anfrage verwenden müssen, sehen Sie sich die Beschreibung der Anfrage an. Die Enum-Werte des Parameters einbeziehen stellen die Antwort-Eigenschaften dar, die vom Parameter einbeziehen 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 einbeziehen abhängen und bei einem anderen Endpunkt standardmäßig ihren tatsächlichen Wert zurückgeben.
Eine Hash-Eigenschaft kann von einem einzigen einbeziehen-Wert oder von mehreren einbeziehen-Werten abhängen, die mit ihren untergeordneten Eigenschaften verbunden sind. Wenn Sie beispielsweise bei der Aktualisierung eines Kontos aktuelle Werte für den gesamten Identitäts-Hash zurückgeben möchten, geben Sie Identität im Parameter einbeziehen an. Andernfalls ist der Identitäts-Hash in der Antwort Null. Um jedoch tatsächliche Werte für den Hash Konfiguration 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 Konfiguration in der Antwort Null.
Das folgende Beispiel aktualisiert ein Konto, um die Konfigurationen Kunde/Kundin und Händler/in hinzuzufügen, gibt aber keine Eigenschaften im Parameter einbeziehen 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 Kunde/Kundin und Identität, 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 }