# Batch-Job ausführen

Sie können Ergebnisse für einen Batch-Job erstellen, hochladen, überwachen und herunterladen.

Die vollständige API-Referenz mit allen verfügbaren Parametern und Antwortfeldern finden Sie in der [Batch-Jobs-API-Referenz](https://docs.stripe.com/api/v2/core/batch-jobs.md?api-version=preview).

Führen Sie zum die folgenden Schritte aus, um einen Batch-Auftrag zu verarbeiten:

1. [Erstellen Sie einen Batch-Auftrag](https://docs.stripe.com/batch-api/create.md#create-a-batch-job) und geben Sie den Ziel-API-Endpoint an.
2. [Laden Sie die Eingabedatei](https://docs.stripe.com/batch-api/create.md#upload-the-input-file) mit Ihren Batch-Anfragen hoch.
3. [Überwachen Sie den Auftragsstatus](https://docs.stripe.com/batch-api/create.md#monitor-job-status) über Webhooks oder Abfragen.
4. [Ergebnisse herunterladen](https://docs.stripe.com/batch-api/create.md#download-the-results).

## Einen Batch-Auftrag erstellen

Erstellen Sie zunächst einen Batch-Auftrag, indem Sie eine `POST`-Anfrage an `/v2/core/batch_jobs` senden. Geben Sie den Ziel-Endpoint und alle Verarbeitungsoptionen an:

```curl
curl -X POST https://api.stripe.com/v2/core/batch_jobs \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-09-30.preview" \
  --json '{
    "endpoint": {
        "path": "/v1/subscriptions/:id/migrate",
        "http_method": "post"
    },
    "skip_validation": false
  }'
```

Der Inhaltstyp für diese Anfrage ist eine JSON-Datei. Dadurch wird ein Batch-Auftrags-Objekt mit dem Status `ready_for_upload` zurückgegeben. Die Upload-URL und ihre Ablaufzeit befinden sich im Feld `status_details`:

```json
{
  "id": "batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz",
  "object": "v2.core.batch_job",
  "created": "2026-03-09T20:55:31.000Z",
  "skip_validation": false,
  "status": "ready_for_upload",
  "status_details": {
    "ready_for_upload": {
      "upload_url": {
        "expires_at": "2026-03-09T21:00:31.000Z",
        "url": "https://stripeusercontent.com/files/upload/..."
      }
    }
  }
}
```

The contents of `status_details` depend on the `status` of the batch job. When `status` is `ready_for_upload`, `status_details` contains the presigned upload URL and its expiration timestamp. A presigned URL includes its own authorization, so you can upload your file to it without your API key. The URL accepts only `PUT` requests and expires 5 minutes after you create the batch job.

### Parameter

| Parameter | Erforderlich | Beschreibung |
| --- | --- | --- |
| `endpoint.path` | Ja | Der zu verwendende API-Endpoint (z.&nbsp;B. `/v1/subscriptions/:id/migrate`). Siehe [Unterstützte Endpoints](https://docs.stripe.com/batch-api/supported-endpoints.md). |
| `endpoint.http_method` | Ja | The HTTP method of the target endpoint, either `post` or `delete`. Batch jobs don’t support `get`. |
| `skip_validation` | Nein | Wählen Sie `true`, um die Validierung der Eingabedatei zu überspringen und sofort mit der Verarbeitung zu beginnen. Der Standardwert lautet `false`. |
| `notification_suppression` | Nein | Steuert, ob Webhooks aus den zugrunde liegenden API-Vorgängen zugestellt werden. Wähhlen Sie `{"scope": "all"}` aus, um Webhooks auf Operationsebene zu unterdrücken. Batch-Ereignisse werden unabhängig von dieser Einstellung immer zugestellt. Der Standardwert lautet `{"scope": "none"}`. |
| `metadata` | Nein | Schlüssel-Wert-Paare für Ihre interne Nachverfolgung. Metadaten sind in Batch-Auftrags-Ereignissen enthalten, einschließlich Fehlerereignissen. |

## Eingabedatei hochladen

Nachdem Sie den Batch-Auftrag erstellt haben, laden Sie Ihre Eingabedatei in die URL in `status_details.ready_for_upload.upload_url.url` hoch. Verwenden Sie eine `PUT`-Anfrage mit dem Dateiinhalt:

```bash
curl {UPLOAD_URL} \
  -X PUT \
  -T input.jsonl \
  -H "Content-Type: application/jsonlines"
```

Die Eingabedatei für diese Anfrage muss eine JSONL-Datei sein und der Inhaltstyp muss `application/jsonlines` sein. Nach Abschluss des Uploads beginnt Stripe automatisch mit der Verarbeitung. Es gibt keinen separaten `start`-Schritt.

> Eine `200`-Antwort auf das `PUT` stammt aus dem Speicher (Amazon&nbsp;S3), der die rohen Bytes direkt über die vorsignierte URL akzeptiert. Sie bestätigt nur, dass der Upload erfolgreich und der Header `Content-Type` korrekt war. Das bedeutet nicht, dass Stripe die Datei überprüft hat oder der Inhalt erfolgreich validiert wurde.
> 
> Die Validierung des Hauptteils der Datei (gültiges JSONL, erforderliche Felder usw.) wird nach dem Hochladen asynchron ausgeführt. Wenn `skip_validation` den Wert `false` aufweist, wechselt der Auftrag zu `validating` und dann zu `validation_failed`, falls der Inhalt ungültig ist.
> 
> Um das Ergebnis zu erfahren, [fragen Sie den Batch-Auftrag ab](https://docs.stripe.com/batch-api/create.md#monitor-job-status) (`GET /v2/core/batch_jobs/{BATCH_JOB_ID}`) und überprüfen Sie seinen `status` und seine `status_details`.

Die Upload-URL läuft 5&nbsp;Minuten nach Erstellung des Batch-Auftrags ab. Im Feld `expires_at` können Sie die genaue Frist sehen. Wenn die URL abläuft, bevor Sie die Datei hochladen, ändert sich der Status des Auftrags in `upload_timeout`, und Sie müssen einen neuen Batch-Auftrag erstellen. Generieren Sie die Eingabedatei, bevor Sie den Batch-Auftrag erstellen, damit Sie sie umgehend hochladen können.

### Eingabedateiformat

Die Datei muss UTF-8-codiert sein und das JSONL-Format verwenden (newline-delimited JSON-Zeile, also ein Objekt pro Zeile). Jede Zeile stellt eine einzelne API-Anfrage an den Ziel-Endpoint dar. CSV und andere Formate werden nicht unterstützt.

Die Datei ist auf 2 Millionen Zeilen begrenzt. Stripe zählt die Zeilen nach Abschluss des Uploads, und Aufträge, die das Limit überschreiten, wechseln in den Status `validation_failed`, ohne Anfragen abzuwickeln. Um mehr als 2 Millionen Zeilen abzuwickeln, teilen Sie die Arbeitslast in mehrere Stapelverarbeitungen zu je maximal 2 Millionen Zeilen auf und reichen Sie diese nacheinander ein – warten Sie, bis ein Auftrag abgeschlossen ist, bevor Sie den nächsten erstellen. Das gleichzeitige Ausführen mehrerer großer Stapelverarbeitungen kann langsamer und unzuverlässiger sein, als wenn Sie dieselbe Aufgabe in aufeinanderfolgenden Aufträgen ausführen. Wenn Sie mehr Kapazität benötigen, wenden Sie sich an den [Stripe-Support](https://support.stripe.com/contact).

Jedes JSON-Objekt unterstützt die folgenden Felder:

| Feld | Erforderlich | Beschreibung |
| --- | --- | --- |
| `id` | Ja | Eine eindeutige Kennung, um diese Anfrage mit ihrem Ergebnis zu verknüpfen. Die IDs der Pfadparameter und die IDs auf dem Endpoint müssen übereinstimmen, wobei der Nutzer/die Nutzerin frei wählen kann, wie er/sie sie benennen möchte: muss übereinstimmen mit `/^[A-Za-z0-9_-]+$/`. |
| `path_params` | Vorbehaltlich | Pfadparameter für den Endpoint. Erforderlich, wenn der Endpoint-Pfad Platzhalter enthält (zum Beispiel `:id`). Die Schlüssel in `path_params` müssen genau mit den Platzhaltern im Endpoint-Pfad übereinstimmen. |
| `params` | Nein | Parameter des Anfragetextes für den API-Aufruf. Je nach API-Methode können Abweichungen auftreten. |
| `context` | Nein | Die ID eines Stripe-Kontos. Verwenden Sie diese, um die Anfrage für ein bestimmtes Konto, z.&nbsp;B. ein verbundenes Konto, auszuführen. |

### Beispiel für eine Eingabedatei

Each example uses JSONL format, with one complete JSON object per line, so you can copy it directly into an input file. To see the example for an endpoint, select its path from the **Endpoint** list.

#### Endpoint - /v1/accounts (POST)

Für den Endpoint `POST /v1/accounts`:

```json
{"id": "req_001", "params": {"type": "custom", "country": "US", "capabilities": {"card_payments": {"requested": true}}}}
{"id": "req_002", "params": {"type": "custom", "country": "GB", "capabilities": {"card_payments": {"requested": true}}}}
```

#### Endpoint - /v1/accounts/:id (POST)

Für den Endpoint `POST /v1/accounts/:id`:

```json
{"id": "req_001", "path_params": {"id": "acct_1AbCdEfGhIjKlMn"}, "params": {"business_type": "company", "company": {"name": "Updated Company Name"}}}
{"id": "req_002", "path_params": {"id": "acct_2BcDeFgHiJkLmNo"}, "params": {"business_type": "individual"}}
```

#### Endpoint - /v1/coupons (POST)

Für den `POST /v1/coupons`-Endpoint:

```json
{"id": "req_001", "params": {"percent_off": 25, "duration": "repeating", "duration_in_months": 3}}
{"id": "req_002", "context": "acct_1234567890", "params": {"amount_off": 500, "currency": "usd", "duration": "once", "name": "Summer Sale"}}
```

#### Endpoint - /v1/coupons/:coupon (POST)

Für den Endpoint `POST /v1/coupons/:coupon`:

```json
{"id": "req_001", "path_params": {"coupon": "nVJYDOag"}, "params": {"name": "Summer Sale"}}
{"id": "req_002", "path_params": {"coupon": "Z4OV52SU"}, "params": {"metadata": {"campaign": "winter_2025"}}}
```

#### Endpoint - /v1/coupons/:coupon (DELETE)

Für den Endpoint `DELETE /v1/coupons/:coupon`:

```json
{"id": "req_001", "path_params": {"coupon": "nVJYDOag"}}
{"id": "req_002", "path_params": {"coupon": "Z4OV52SU"}}
```

#### Endpoint - /v1/credit_notes (POST)

Für den Endpoint `POST /v1/credit_notes`:

```json
{"id": "req_001", "params": {"invoice": "in_1AbCdEfGhIjKlMn", "amount": 1000}}
{"id": "req_002", "params": {"invoice": "in_2BcDeFgHiJkLmNo", "amount": 500, "memo": "Service credit"}}
```

#### Endpoint - /v1/customers (POST)

Für den Endpoint `POST /v1/customers`:

```json
{"id": "req_001", "params": {"email": "alice@example.com", "name": "Alice Smith"}}
{"id": "req_002", "params": {"email": "bob@example.com", "name": "Bob Jones", "phone": "+18005550123"}}
{"id": "req_003", "context": "acct_1234567890", "params": {"email": "carol@example.com", "name": "Carol White", "metadata": {"import_id": "legacy_001"}}}
```

#### Endpoint - /v1/customers/:customer/bank_accounts/:id (POST)

Für den Endpoint `POST /v1/customers/:customer/bank_accounts/:id`:

```json
{"id": "req_001", "path_params": {"customer": "cus_1AbCdEfGhIjKlMn", "id": "ba_1AbCdEfGhIjKlMn"}, "params": {"account_holder_name": "Jane Doe"}}
{"id": "req_002", "path_params": {"customer": "cus_2BcDeFgHiJkLmNo", "id": "ba_2BcDeFgHiJkLmNo"}, "params": {"account_holder_name": "John Smith"}}
```

#### Endpoint - /v1/customers/:id (POST)

Für den Endpoint `POST /v1/customers/:id`:

```json
{"id": "req_001", "path_params": {"id": "cus_1AbCdEfGhIjKlMn"}, "params": {"name": "Jenny Rosen", "email": "jenny@example.com"}}
{"id": "req_002", "path_params": {"id": "cus_2BcDeFgHiJkLmNo"}, "params": {"name": "John Smith", "metadata": {"tier": "premium"}}}
{"id": "req_003", "context": "acct_1234567890", "path_params": {"id": "cus_3CdEfGhIjKlMnOp"}, "params": {"description": "Updated by batch"}}
```

#### Endpoint - /v1/customers/:id (DELETE)

Für den `DELETE /v1/customers/:id`-Endpoint:

```json
{"id": "req_001", "path_params": {"id": "cus_1AbCdEfGhIjKlMn"}, "params": {}}
{"id": "req_002", "path_params": {"id": "cus_2BcDeFgHiJkLmNo"}, "params": {}}
```

#### Endpoint - /v1/disputes/:dispute/close (POST)

Für den Endpoint `POST /v1/disputes/:dispute/close`:

```json
{"id": "req_001", "path_params": {"dispute": "dp_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"dispute": "dp_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/entitlements/features (POST)

Für den Endpoint `POST /v1/entitlements/features`:

```json
{"id": "req_001", "params": {"name": "Premium Access", "lookup_key": "premium_access"}}
{"id": "req_002", "params": {"name": "Advanced Analytics", "lookup_key": "advanced_analytics"}}
```

#### Endpoint - /v1/entitlements/features/:id (POST)

Für den Endpoint `POST /v1/entitlements/features/:id`:

```json
{"id": "req_001", "path_params": {"id": "feat_1AbCdEfGhIjKlMn"}, "params": {"name": "Updated Feature Name"}}
{"id": "req_002", "path_params": {"id": "feat_2BcDeFgHiJkLmNo"}, "params": {"active": false}}
```

#### Endpoint - /v1/invoiceitems (POST)

Für den Endpoint `POST /v1/invoiceitems`:

```json
{"id": "req_001", "params": {"customer": "cus_1AbCdEfGhIjKlMn", "amount": 1000, "currency": "usd", "description": "Consulting fee"}}
{"id": "req_002", "params": {"customer": "cus_2BcDeFgHiJkLmNo", "amount": 2500, "currency": "usd", "description": "Platform fee"}}
```

#### Endpoint - /v1/invoiceitems/:id (POST)

Für den Endpoint `POST /v1/invoiceitems/:id`:

```json
{"id": "req_001", "path_params": {"id": "ii_1AbCdEfGhIjKlMn"}, "params": {"description": "Updated consulting fee"}}
{"id": "req_002", "path_params": {"id": "ii_2BcDeFgHiJkLmNo"}, "params": {"amount": 3000}}
```

#### Endpoint - /v1/invoiceitems/:id (DELETE)

Für den Endpoint `DELETE /v1/invoiceitems/:id`:

```json
{"id": "req_001", "path_params": {"id": "ii_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"id": "ii_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/invoices/:id (POST)

Für den Endpoint `POST /v1/invoices/:id`:

```json
{"id": "req_001", "path_params": {"id": "in_1AbCdEfGhIjKlMn"}, "params": {"collection_method": "send_invoice", "days_until_due": 30}}
{"id": "req_002", "path_params": {"id": "in_2BcDeFgHiJkLmNo"}, "params": {"description": "Updated invoice description"}}
```

#### Endpoint - /v1/invoices/:invoice/add_lines (POST)

Für den Endpoint `POST /v1/invoices/:invoice/add_lines`:

```json
{"id": "req_001", "path_params": {"invoice": "in_1AbCdEfGhIjKlMn"}, "params": {"lines": [{"amount": 1000, "description": "Consulting services"}]}}
{"id": "req_002", "path_params": {"invoice": "in_2BcDeFgHiJkLmNo"}, "params": {"lines": [{"amount": 2500, "description": "Platform fee"}]}}
```

#### Endpoint - /v1/plans (POST)

Für den Endpoint `POST /v1/plans`:

```json
{"id": "req_001", "params": {"amount": 1000, "currency": "usd", "interval": "month", "product": "prod_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "params": {"amount": 2500, "currency": "usd", "interval": "year", "product": "prod_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/plans/:id (POST)

Für den Endpoint `POST /v1/plans/:id`:

```json
{"id": "req_001", "path_params": {"id": "plan_1AbCdEfGhIjKlMn"}, "params": {"nickname": "Monthly standard"}}
{"id": "req_002", "path_params": {"id": "plan_2BcDeFgHiJkLmNo"}, "params": {"active": "false"}}
```

#### Endpoint - /v1/plans/:id (DELETE)

Für den Endpoint `DELETE /v1/plans/:id`:

```json
{"id": "req_001", "path_params": {"id": "plan_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"id": "plan_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/prices/:id (POST)

Für den Endpoint `POST /v1/prices/:id`:

```json
{"id": "req_001", "path_params": {"id": "price_1AbCdEfGhIjKlMn"}, "params": {"active": false}}
{"id": "req_002", "path_params": {"id": "price_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"tier": "premium"}}}
```

#### Endpoint - /v1/products (POST)

Für den Endpoint `POST /v1/products`:

```json
{"id": "req_001", "params": {"name": "Premium Widget"}}
{"id": "req_002", "context": "acct_1234567890", "params": {"name": "Basic Widget", "description": "An affordable widget", "metadata": {"category": "widgets"}}}
```

#### Endpoint - /v1/products/:id (POST)

Für den Endpoint `POST /v1/products/:id`:

```json
{"id": "req_001", "path_params": {"id": "prod_1AbCdEfGhIjKlMn"}, "params": {"name": "Updated Product Name", "description": "New description"}}
{"id": "req_002", "path_params": {"id": "prod_2BcDeFgHiJkLmNo"}, "params": {"active": false}}
```

#### Endpoint - /v1/products/:id (DELETE)

Für den Endpoint `DELETE /v1/products/:id`:

```json
{"id": "req_001", "path_params": {"id": "prod_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"id": "prod_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/products/:product/features (POST)

Für den Endpoint `POST /v1/products/:product/features`:

```json
{"id": "req_001", "path_params": {"product": "prod_1AbCdEfGhIjKlMn"}, "params": {"entitlement_feature": "feat_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"product": "prod_2BcDeFgHiJkLmNo"}, "params": {"entitlement_feature": "feat_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/products/:product/features/:id (DELETE)

Für den Endpoint `DELETE /v1/products/:product/features/:id`:

```json
{"id": "req_001", "path_params": {"product": "prod_1AbCdEfGhIjKlMn", "id": "prodft_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"product": "prod_2BcDeFgHiJkLmNo", "id": "prodft_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/promotion_codes (POST)

Für den Endpoint `POST /v1/promotion_codes`:

```json
{"id": "req_001", "params": {"promotion": {"type": "coupon", "coupon": "nVJYDOag"}, "code": "SUMMER25"}}
{"id": "req_002", "params": {"promotion": {"type": "coupon", "coupon": "Z4OV52SU"}, "code": "WINTER50", "max_redemptions": 100}}
```

#### Endpoint - /v1/promotion_codes/:id (POST)

Für den Endpoint `POST /v1/promotion_codes/:id`:

```json
{"id": "req_001", "path_params": {"id": "promo_1AbCdEfGhIjKlMn"}, "params": {"active": false}}
{"id": "req_002", "path_params": {"id": "promo_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"tier": "premium"}}}
```

#### Endpoint - /v1/radar/value_list_items (POST)

Für den Endpoint `POST /v1/radar/value_list_items`:

```json
{"id": "req_001", "params": {"value_list": "rsl_1AbCdEfGhIjKlMn", "value": "1.2.3.4"}}
{"id": "req_002", "params": {"value_list": "rsl_1AbCdEfGhIjKlMn", "value": "5.6.7.8"}}
```

#### Endpoint - /v1/subscription_items/:item (POST)

Für den Endpoint `POST /v1/subscription_items/:item`:

```json
{"id": "req_001", "path_params": {"item": "si_1AbCdEfGhIjKlMn"}, "params": {"price": "price_1AbCdEfGhIjKlMn", "quantity": 5}}
{"id": "req_002", "path_params": {"item": "si_2BcDeFgHiJkLmNo"}, "params": {"price": "price_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/subscription_items/:item (DELETE)

Für den Endpoint `DELETE /v1/subscription_items/:item`:

```json
{"id": "req_001", "path_params": {"item": "si_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"item": "si_2BcDeFgHiJkLmNo"}, "params": {"clear_usage": true}}
```

#### Endpoint - /v1/subscription_schedules (POST)

Für den Endpoint `POST /v1/subscription_schedules`:

```json
{"id": "req_001", "params": {"customer": "cus_1AbCdEfGhIjKlMn", "start_date": 1640995200, "phases": [{"items": [{"price": "price_1AbCdEfGhIjKlMn", "quantity": 1}], "iterations": 12}]}}
{"id": "req_002", "params": {"customer": "cus_2BcDeFgHiJkLmNo", "start_date": 1640995200, "phases": [{"items": [{"price": "price_2BcDeFgHiJkLmNo", "quantity": 2}], "iterations": 6}]}}
```

#### Endpoint - /v1/subscription_schedules/:id (POST)

Für den Endpoint `POST /v1/subscription_schedules/:id`:

```json
{"id": "req_001", "path_params": {"id": "sub_sched_1AbCdEfGhIjKlMn"}, "params": {"end_behavior": "cancel"}}
{"id": "req_002", "path_params": {"id": "sub_sched_2BcDeFgHiJkLmNo"}, "params": {"end_behavior": "release"}}
```

#### Endpoint - /v1/subscription_schedules/:id/cancel (POST)

Für den Endpoint `POST /v1/subscription_schedules/:id/cancel`:

```json
{"id": "req_001", "path_params": {"id": "sub_sched_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"id": "sub_sched_2BcDeFgHiJkLmNo"}}
```

#### Endpoint - /v1/subscription_schedules/:schedule/release (POST)

Für den Endpoint `POST /v1/subscription_schedules/:schedule/release`:

```json
{"id": "req_001", "path_params": {"schedule": "sub_sched_1AbCdEfGhIjKlMn"}, "params": {}}
{"id": "req_002", "path_params": {"schedule": "sub_sched_2BcDeFgHiJkLmNo"}, "params": {"preserve_cancel_date": true}}
```

#### Endpoint - /v1/subscriptions (POST)

Für den Endpoint `POST /v1/subscriptions`:

```json
{"id": "req_001", "params": {"customer": "cus_1AbCdEfGhIjKlMn", "items": [{"price": "price_1AbCdEfGhIjKlMn"}]}}
{"id": "req_002", "params": {"customer": "cus_2BcDeFgHiJkLmNo", "items": [{"price": "price_2BcDeFgHiJkLmNo", "quantity": 3}]}}
```

#### Endpoint - /v1/subscriptions/:id (POST)

Für den Endpoint `POST /v1/subscriptions/:id`:

```json
{"id": "req_001", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}, "params": {"description": "Updated subscription description"}}
{"id": "req_002", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"migration_batch": "v2"}}}
{"id": "req_003", "context": "acct_1234567890", "path_params": {"id": "sub_3CdEfGhIjKlMnOp"}, "params": {"cancel_at_period_end": true}}
```

#### Endpoint - /v1/subscriptions/:id (DELETE)

Für den `DELETE /v1/subscriptions/:id`-Endpoint:

```json
{"id": "req_001", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}}
{"id": "req_002", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"cancellation_details": {"comment": "Customer requested cancellation"}}}
```

#### Endpoint - /v1/subscriptions/:id/migrate (POST)

Für den Endpoint `POST /v1/subscriptions/:id/migrate`:

```json
{"id": "req_001", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}, "params": {"billing_mode": {"type": "flexible"}}}
{"id": "req_002", "context": "acct_1234567890", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"billing_mode": {"type": "flexible", "flexible": {"proration_discounts": "included"}}}}
```

#### Endpoint - /v1/tax/registrations (POST)

Für den Endpoint `POST /v1/tax/registrations`:

```json
{"id": "req_001", "params": {"country": "IE", "country_options": {"ie": {"type": "standard"}}, "active_from": "now"}}
{"id": "req_002", "params": {"country": "DE", "country_options": {"de": {"type": "standard"}}, "active_from": "now"}}
```

#### Endpoint - /v1/tax/registrations/:id (POST)

Für den Endpoint `POST /v1/tax/registrations/:id`:

```json
{"id": "req_001", "path_params": {"id": "taxreg_1abc"}, "params": {"expires_at": 1735689600}}
{"id": "req_002", "path_params": {"id": "taxreg_2def"}, "params": {"expires_at": 1735689600}}
```

#### Endpoint - /v1/tax/settings (POST)

Für den Endpoint `POST /v1/tax/settings`:

```json
{"id": "req_001", "params": {"defaults": {"tax_code": "txcd_10000000"}}}
```

#### Endpoint - /v1/tax_rates/:id (POST)

Für den Endpoint `POST /v1/tax_rates/:id`:

```json
{"id": "req_001", "path_params": {"id": "txr_1abc"}, "params": {"active": false}}
{"id": "req_002", "path_params": {"id": "txr_2def"}, "params": {"display_name": "Updated Tax"}}
```

#### Endpoint - /v1/transfers (POST)

Für den Endpoint `POST /v1/transfers`:

```json
{"id": "req_001", "params": {"destination": "acct_1AbCdEfGhIjKlMn", "currency": "usd", "amount": 1000}}
{"id": "req_002", "params": {"destination": "acct_2BcDeFgHiJkLmNo", "currency": "usd", "amount": 2500}}
```

#### Endpoint - /v1/transfers/:id (POST)

Für den Endpoint `POST /v1/transfers/:id`:

```json
{"id": "req_001", "path_params": {"id": "tr_1AbCdEfGhIjKlMn"}, "params": {"description": "Updated transfer description"}}
{"id": "req_002", "path_params": {"id": "tr_2BcDeFgHiJkLmNo"}, "params": {"metadata": {"order_id": "6735"}}}
```

Jede `id` muss innerhalb der Datei eindeutig sein. Stripe verwendet sie, um Anfragen mit Ergebnissen zu verknüpfen, da die Ergebnisdatei nicht genauso geordnet ist wie die Eingabedatei.

## Auftragsstatus überwachen

Sie können Ihren Batch-Auftrag nachverfolgen, indem Sie den Endpoint abfragen oder [Webhook-Ereignisse](https://docs.stripe.com/batch-api/create.md#webhook-events) überwachen. Wir empfehlen die Verwendung von Webhook-Ereignissen für Produktionsintegrationen.

### Status abfragen

```curl
curl https://api.stripe.com/v2/core/batch_jobs/batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-09-30.preview"
```

Der Inhaltstyp für diese Anfrage ist eine JSON-Datei. Während der Ausführung des Auftrags enthält `status_details` Fortschrittsanzeigen in Echtzeit:

```json
{
  "status": "in_progress",
  "status_details": {
    "in_progress": {
      "success_count": "1",
      "failure_count": "0"
    }
  }
}
```

Während der Phase `validating` ist in `status_details` ein Feld `validated_count` enthalten, das angibt, wie viele Zeilen Stripe bisher validiert hat.

Batch-Auftrag-API-Aufrufe werden im Stripe-Dashboard oder in den Workbench-Anfrageprotokollen angezeigt. Die zugrunde liegenden API-Aufrufe werden nicht in den Anfrageprotokollen angezeigt. Verwenden Sie den Abruf-Endpoint oder Webhook-Ereignisse, um den Fortschritt zu überwachen. Um Fehler bei einzelnen Anfragen zu beheben, überprüfen Sie die Ergebnisdatei.

### Lifecycle des Auftrags

Nachdem Sie die Eingabedatei hochgeladen haben, durchläuft der Batch-Auftrag die folgenden Statusphasen:

| Status | Beschreibung |
| --- | --- |
| `ready_for_upload` | Der Batch-Auftrag wurde erstellt und wartet auf die Eingabedatei. |
| `validating` | Stripe hat die hochgeladene Datei akzeptiert und validiert sie. Wird übersprungen, wenn `skip_validation` auf `true` gesetzt ist. |
| `in_progress` | Validierung übergeben (oder übersprungen) und Stripe verarbeitet die Anfragen. |
| `complete` | Alle Anfragen wurden bearbeitet. Die Ergebnisse können heruntergeladen werden. |
| `cancelling` | Eine Stornierung wurde angefordert. Stripe schließt die laufenden Anfragen ab. |

### Terminal-Status

| Status | Beschreibung |
| --- | --- |
| `validation_failed` | Die Eingabedatei enthält Fehler. Es wurden keine Anfragen verarbeitet. Überprüfen Sie das Batch-Auftrags-Objekt auf Fehlerdetails. Dies gilt nur für `skip_validation: false`. |
| `batch_failed` | Während der Verarbeitung ist ein unerwarteter Fehler aufgetreten. |
| `Storniert` | Der Batch-Auftrag wurde storniert. Teilergebnisse sind möglicherweise verfügbar. |
| `upload_timeout` | Die Upload-URL ist abgelaufen, bevor die Datei hochgeladen wurde. Erstellen Sie einen neuen Batch-Auftrag. |
| `timeout` | Der Batch-Job hat die maximale Verarbeitungsdauer von 7&nbsp;Tagen überschritten. Möglicherweise sind Teilergebnisse verfügbar. |

### Validierung

When `skip_validation` is `false` (the default), Stripe validates the entire input file before processing any requests. This validation catches errors such as:

- Invalid JSON on any line
- Missing or invalid `id` fields
- Duplicate IDs
- Missing required `path_params` for the target endpoint

For `/v1` endpoints, validation also checks the parameters in each request, so unknown parameters and invalid parameter values fail validation. Errors that depend on the state of the objects you reference, such as migrating a subscription that isn’t active, only appear when Stripe executes the request. These failures appear in the results file with a non-`200` status. To catch them before you run a large batch, [test your input with a small batch](https://docs.stripe.com/batch-api/best-practices.md#test-with-a-small-batch-first) first.

Wenn die Validierung fehlschlägt, ändert sich der Status in `validation_failed` und Stripe versucht keine Anfragen. Das Batch-Auftrags-Objekt enthält Details zum ersten aufgetretenen Fehler.

Wenn `skip_validation` `true` ist, wechselt der Job nach dem Hochladen direkt von `ready_for_upload` zu `in_progress`. Bei Fehlern in einzelnen Anfragen wird nicht der gesamte Batch blockiert, sondern die Fehler werden in der Ergebnisdatei angezeigt.

### Webhook-Ereignisse

Batch-Aufträge erzeugen für jeden Zustandswechsel v2 Thin-Ereignisse. Um diese Ereignisse zu empfangen, müssen Sie ein [v2-Ereignisziel](https://docs.stripe.com/events/set-up-events.md) konfigurieren.

Batch-Auftrags-Ereignisse erfordern v2-Ereignisziele. Sie werden nicht an v1 Webhook-Endpoints übermittelt.

Folgende Ereignisse sind verfügbar:

| Ereignistyp | Beschreibung |
| --- | --- |
| `v2.core.batch_job.created` | Ein Batch-Auftrag wurde erstellt. |
| `v2.core.batch_job.ready_for_upload` | Der Batch-Auftrag kann jetzt hochgeladen werden. |
| `v2.core.batch_job.validating` | Datei-Upload abgeschlossen, Validierung läuft. |
| `v2.core.batch_job.validation_failed` | Validierung der Eingabedatei fehlgeschlagen. |
| `v2.core.batch_job.completed` | Alle Anfragen wurden verarbeitet. |
| `v2.core.batch_job.batch_failed` | Der Batch-Auftrag ist unerwartet fehlgeschlagen. |
| `v2.core.batch_job.canceled` | Der Batch-Auftrag wurde abgebrochen. |
| `v2.core.batch_job.timeout` | Der Batch-Auftrag hat die maximale Verarbeitungsdauer überschritten. |
| `v2.core.batch_job.upload_timeout` | Die Upload-URL ist abgelaufen, bevor die Datei hochgeladen wurde. |
| `v2.core.batch_job.updated` | Der Status oder Fortschritt des Batch-Auftrags hat sich geändert. |

Alle Batch-Auftrags-Ereignisse enthalten die Metadaten, die Sie beim Erstellen des Auftrags angegeben haben. Verwenden Sie diese, um Ereignisse mit Ihren internen Systemen zu verknüpfen.

Wenn `notification_suppression` auf `{"scope": "all"}` festgelegt ist, werden Webhooks aus den zugrunde liegenden API-Vorgängen (z.&nbsp;B. Abonnementaktualisierungsereignisse) unterdrückt. Die oben aufgeführten Batch-Ereignisse werden unabhängig von dieser Einstellung immer zugestellt.

## Ergebnisse herunterladen

Wenn der Batch-Auftrag den Status `complete` erreicht, enthält das Feld `status_details` eine Zusammenfassung der Erfolge und Fehler sowie eine vorsignierte URL, die für die Ausgabedatei heruntergeladen wird:

```json
{
  "id": "batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz",
  "object": "v2.core.batch_job",
  "created": "2026-03-09T20:55:31.000Z",
  "skip_validation": true,
  "status": "complete",
  "status_details": {
    "complete": {
      "success_count": "2",
      "failure_count": "0",
      "output_file": {
        "content_type": "application/jsonlines",
        "size": "8514",
        "download_url": {
          "expires_at": "2026-03-09T22:05:31.000Z",
          "url": "https://stripeusercontent.com/files/download/..."
        }
      }
    }
  }
}
```

Laden Sie die Datei mit der URL in `status_details.complete.output_file.download_url.url` herunter. Stripe stellt eine Ausgabedatei bereit, wenn der Batch-Auftrag eine der folgenden Statusphasen erreicht:

- `complete`
- `Storniert`
- `timeout`
- `validation_failed`

Im Feld `expires_at` können Sie sehen, wann die Frist der heruntergeladenen URL abläuft.

Die Ergebnisdatei enthält sowohl erfolgreiche als auch fehlgeschlagene Anfragen in einer einzelnen Datei. Um Fehler zu finden, filtern Sie nach Zeilen, in denen der `status` nicht `200` ist.

### Ergebnisdateiformat

Die Ausgabedatei verwendet das JSONL-Format (ein JSON-Objekt pro Zeile). Jede Zeile enthält die folgenden Felder:

| Feld | Beschreibung |
| --- | --- |
| `id` | Die ID der Anfrage aus der Eingabedatei. Verwenden Sie diese, um Ergebnisse mit Anfragen zu verknüpfen. |
| `response` | Das vollständige API-Antwortobjekt. Enthält im Erfolgsfall die Ressource, im Fehlerfall ein Fehlerobjekt. |
| `status` | Der HTTP-Statuscode als ganze Zahl (z.&nbsp;B. `200`, `402`). |
| `context` | Das verbundene Konto, für das die Anfrage ausgeführt wurde. |

### Beispiel-Ergebnisdatei

Erfolgreiche Anfragen geben die vollständige API-Ressource im `response` zurück:

```json
{
  "id": "req_001",
  "response": {
    "id": "sub_1AbCdEfGhIjKlMn",
    "object": "subscription",
    "status": "active",
    "billing_cycle_anchor": 1710021331,
    "current_period_end": 1712613331,
    "current_period_start": 1710021331
  },
  "status": 200
}
{
  "id": "req_002",
  "response": {
    "id": "sub_2BcDeFgHiJkLmNo",
    "object": "subscription",
    "status": "active",
    "billing_cycle_anchor": 1710021331,
    "current_period_end": 1712613331,
    "current_period_start": 1710021331
  },
  "status": 200
}
```

Fehlgeschlagene Anfragen geben ein Fehlerobjekt zurück:

```json
{
  "id": "req_003",
  "response": {
    "error": {
      "message": "This subscription cannot be migrated because it is not active. Current status is canceled.",
      "type": "invalid_request_error",
      "code": "resource_invalid_state"
    }
  },
  "status": 400
}
```

Wenn eine Eingabezeile einen `Kontext` enthält, ist dieser in der entsprechenden Ausgabe enthalten:

```json
{
  "id": "req_001",
  "context": "acct_1234567890",
  "response": {
    "id": "sub_1AbCdEfGhIjKlMn",
    "object": "subscription",
    "status": "active"
  },
  "status": 200
}
```

> Stripe doesn’t process requests in input order, and the results file doesn’t follow the order of the input file. Results from a small test file might appear in order, but don’t rely on that for any file size. Always use the `id` field to match each result to its request.

## Create related objects across batches

Each request in a batch runs independently, so a request can’t reference an object that another request in the same batch creates. To create related objects, such as customers and their subscriptions, run a separate batch job for each step:

1. Create a batch job for the first endpoint (for example, `POST /v1/customers`). Give each line an `id` that identifies the record in your system.

   ```json
   {"id": "user_001", "params": {"email": "alice@example.com"}}
   {"id": "user_002", "params": {"email": "bob@example.com"}}
   ```

2. When the first job finishes, download the results file and map each `id` to the Stripe object ID in `response.id`. Leave lines where the `status` field isn’t `200` out of the next batch, and handle those failures separately.

3. Create a second batch job for the next endpoint (for example, `POST /v1/subscriptions`) and use the customer IDs from the first results file in each line.

   ```json
   {"id": "user_001", "params": {"customer": "cus_1AbCdEfGhIjKlMn", "items": [{"price": "price_1AbCdEfGhIjKlMn"}]}}
   {"id": "user_002", "params": {"customer": "cus_2BcDeFgHiJkLmNo", "items": [{"price": "price_1AbCdEfGhIjKlMn"}]}}
   ```

Wait for each job to finish before you create the next one. Because results aren’t ordered, always build the mapping from the `id` field, not from the line position.

## Batch-Auftrag stornieren

Sie können einen Batch-Auftrag, der noch nicht abgeschlossen ist, stornieren, indem Sie eine `POST`-Anfrage senden:

```curl
curl -X POST https://api.stripe.com/v2/core/batch_jobs/batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz/cancel \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-09-30.preview"
```

Die Stornierung erfolgt asynchron. Der Auftrag wechselt zunächst zu `cancelling`, während laufende Anfragen abgeschlossen werden, und dann zu `cancelled`. Alle Teilergebnisse aus Anfragen, die vor der Stornierung verarbeitet wurden, sind in der Ergebnisdatei verfügbar.

## Mit Connect verwenden

Plattform-Konten können Batch-Aufträge im Namen verbundener Konten ausführen. Erstellen Sie die Batch-Aufträge wie gewohnt mit dem API-Schlüssel Ihrer Plattform. Um ein verbundenes Konto für einzelne Anfragen in der Eingabedatei als Ziel festzulegen, setzen Sie das Feld `context` auf die ID des verbundenen Kontos. Dies ist das pro Anfrage geltende Äquivalent zum Header `Stripe-Account` in direkten API-Aufrufen.

```curl
curl -X POST https://api.stripe.com/v2/core/batch_jobs \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-09-30.preview" \
  --json '{
    "endpoint": {
        "path": "/v1/subscriptions/:id/migrate",
        "http_method": "post"
    }
  }'
```

Fügen Sie in der Eingabedatei `context` zu jeder Zeile hinzu, die als ein verbundenes Konto ausgeführt werden soll:

```json
{"id": "req_001", "context": "acct_1AbCdEfGhIjKlMn", "path_params": {"id": "sub_1AbCdEfGhIjKlMn"}, "params": {"billing_cycle_anchor": "unchanged"}}
{"id": "req_002", "context": "acct_2BcDeFgHiJkLmNo", "path_params": {"id": "sub_2BcDeFgHiJkLmNo"}, "params": {"billing_cycle_anchor": "unchanged"}}
{"id": "req_003", "path_params": {"id": "sub_3CdEfGhIjKlMnOp"}, "params": {"billing_cycle_anchor": "unchanged"}}
```

Zeilen ohne `context` werden als Plattform-Konto ausgeführt. Zeilen mit `context` werden als das angegebene verbundene Konto ausgeführt. Sie können in einer Batch-Datei beide Varianten mischen.