# バッチジョブの実行

バッチジョブの作成、入力ファイルのアップロード、ジョブの監視、結果のダウンロードを行います。

使用可能なすべてのパラメーターや応答フィールドなど、API リファレンスの詳細については、[バッチジョブ API リファレンス](https://docs.stripe.com/api/v2/core/batch-jobs.md?api-version=preview)を参照してください。

バッチジョブを処理するには、次の手順に従います。

1. [バッチジョブを作成](https://docs.stripe.com/batch-api/create.md#create-a-batch-job)し、ターゲット API エンドポイントを指定します。
2. [入力ファイルをアップロード](https://docs.stripe.com/batch-api/create.md#upload-the-input-file)して、バッチリクエストを含めます。
3. Webhook またはポーリングを使用して[ジョブステータスを監視](https://docs.stripe.com/batch-api/create.md#monitor-job-status)します。
4. [結果をダウンロード](https://docs.stripe.com/batch-api/create.md#download-the-results)します。

## バッチジョブの作成

まず、`POST` リクエストを `/v2/core/batch_jobs` に送信してバッチジョブを作成します。ターゲットエンドポイントと処理オプションを指定します。

```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
  }'
```

このリクエストのコンテンツタイプは JSON ファイルです。これにより、`ready_for_upload` ステータスのバッチジョブオブジェクトが返されます。アップロード URL とその有効期限は `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.

### パラメーター

| パラメーター | 必須 | 説明 |
| --- | --- | --- |
| `endpoint.path` | はい | 対象の API エンドポイント (`/v1/subscriptions/:id/migrate` など)。[サポート対象エンドポイント](https://docs.stripe.com/batch-api/supported-endpoints.md)をご覧ください。 |
| `endpoint.http_method` | はい | The HTTP method of the target endpoint, either `post` or `delete`. Batch jobs don’t support `get`. |
| `skip_validation` | いいえ | 入力ファイルの検証をスキップし、直ちに処理を開始するには、`true` に設定します。デフォルトは `false` です。 |
| `notification_suppression` | いいえ | 基盤となる API 操作からの Webhook を送信するかどうかを制御します。操作レベルの Webhook を抑制するには、`{"scope": "all"}` を設定します。バッチレベルのイベントは、この設定に関係なく常に配信されます。デフォルトは `{"scope": "none"}` です。 |
| `metadata` | いいえ | 内部追跡のキーと値のペア。メタデータは、失敗イベントなどのバッチジョブイベントに含まれます。 |

## 入力ファイルをアップロードする

バッチジョブを作成したら、`status_details.ready_for_upload.upload_url.url` の URL に入力ファイルをアップロードします。ファイルの内容を指定した `PUT` リクエストを使用します。

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

このリクエストの入力ファイルは JSONL ファイルである必要があり、コンテンツタイプは `application/jsonlines` である必要があります。アップロードが完了すると、Stripe が自動的に処理を開始します。個別の`開始`ステップはありません。

> `PUT` に対する `200` レスポンスは、プレサイン付き URL 経由で生のバイトデータを直接受け取るストレージ (Amazon S3) から返されます。これにより、アップロードが成功し、`Content-Type` ヘッダーが正しいことのみが確認されます。Stripe がファイルを検査したことや、コンテンツが検証に合格したことを意味するものではありません。
> 
> ファイル本文の検証 (有効な JSONL、必須フィールドなど) は、アップロード後に非同期で実行されます。`skip_validation` が `false` の場合、ジョブは `validating` に移行し、コンテンツが無効な場合は `validation_failed` に移行します。
> 
> 結果を確認するには、[バッチジョブをポーリングし](https://docs.stripe.com/batch-api/create.md#monitor-job-status) (`GET /v2/core/batch_jobs/{BATCH_JOB_ID}`)、その `status` と `status_details` を確認します。

アップロード URL は、バッチジョブの作成後 5 分で有効期限が切れます。正確な期限については、`expires_at` フィールドを確認してください。ファイルをアップロードする前に URL の有効期限が切れた場合、ジョブのステータスは `upload_timeout` に変わり、新しいバッチジョブを作成する必要があります。バッチジョブを作成する前に入力ファイルを生成し、すばやくアップロードできるようにします。

### 入力ファイル形式

ファイルは UTF-8 エンコードで、JSONL 形式 (改行区切りの JSON、1 行に 1 つのオブジェクト) を使用する必要があります。各行は、ターゲットエンドポイントへの 1 つの API リクエストを表します。CSV やその他の形式はサポートされません。

ファイルの上限は 200 万行です。アップロードが完了すると Stripe で行数がカウントされ、上限を超えるジョブはリクエストを一切処理せずに `validation_failed` ステータスに移行します。200 万行を超える処理を行うには、ワークロードをそれぞれ最大 200 万行の複数の batch ジョブに分割し、順次送信してください。1 つのジョブが完了するまで待ってから次のジョブを作成してください。大規模なバッチジョブを複数同時に実行すると、同じ処理を順次実行する場合に比べて処理が遅くなり、信頼性が低下する可能性があります。これ以上の処理容量が必要な場合は、[Stripe サポート](https://support.stripe.com/contact)にお問い合わせください。

各 JSON オブジェクトは、次のフィールドをサポートしています。

| フィールド | 必須 | 説明 |
| --- | --- | --- |
| `id` | はい | このリクエストを結果と関連付ける一意の識別子。パスパラメータの ID とエンドポイントの ID は一致している必要がありますが、ユーザーが名前を指定する方法を自由に選択できます。`/^[A-Za-z0-9_-]+$/` と一致する必要があります。 |
| `path_params` | 条件付き | エンドポイントのパスパラメータ。エンドポイントパスにプレースホルダー (`:id` など) が含まれる場合に必要です。`path_params` のキーは、エンドポイントパスのプレースホルダーと正確に一致する必要があります。 |
| `params` | いいえ | API コールのリクエスト本文パラメータ。API メソッドによって異なる場合があります。 |
| `context` | いいえ | Stripe アカウント ID。連結アカウントなどの特定のアカウントに対してリクエストを実行する場合に使用します。 |

### 入力ファイルの例

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)

`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)

`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)

`POST /v1/coupons` エンドポイントの場合:

```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)

`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)

`DELETE /v1/coupons/:coupon` エンドポイントの場合:

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

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

`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)

`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)

`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)

`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)

`DELETE /v1/customers/:id` エンドポイントの場合:

```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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`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)

`DELETE /v1/subscriptions/:id` エンドポイントの場合:

```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)

`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)

`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)

`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)

`POST /v1/tax/settings` エンドポイントの場合:

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

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

`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)

`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)

`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"}}}
```

各 `id` は、ファイル内で一意である必要があります。結果ファイルは入力ファイルと同じ順序ではないため、Stripe はこれを使用してリクエストと結果を関連付けます。

## ジョブのステータスを監視する

バッチジョブは、取得エンドポイントをポーリングするか、[Webhook イベント](https://docs.stripe.com/batch-api/create.md#webhook-events)をリッスンすることで追跡できます。本番環境の組み込みには Webhook イベントを使用することをお勧めします。

### ステータスのポーリング

```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"
```

このリクエストのコンテンツタイプは json ファイルです。ジョブの実行中は、`status_details` にリアルタイムの進捗状況が表示されます。

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

`検証`フェーズでは、`status_details` には、Stripe がこれまでに検証した行数を示す `validated_count` フィールドが含まれます。

バッチジョブの API コールは、Stripe ダッシュボードまたはワークベンチのリクエストログに表示されます。基になる API コールはリクエストログに表示されません。取得エンドポイントまたは Webhook イベントを使用して進捗を監視します。個別のリクエストの失敗をデバッグするには、結果ファイルを確認してください。

### ジョブのライフサイクル

入力ファイルをアップロードすると、バッチジョブは次のステータスで進行します。

| ステータス | 説明 |
| --- | --- |
| `ready_for_upload` | バッチジョブが作成され、入力ファイルを待機しています。 |
| `validating` | Stripe はアップロードされたファイルを受け付け、検証しています。`skip_validation` が `true` の場合は、検証がスキップされます。 |
| `in_progress` | 検証が成功 (またはスキップ) し、Stripe がリクエストを処理しています。 |
| `complete` | すべてのリクエストが処理されました。結果はダウンロードできます。 |
| `cancelling` | キャンセルがリクエストされました。Stripe は処理中のリクエストを完了させています。 |

### Terminal ステータス

| ステータス | 説明 |
| --- | --- |
| `validation_failed` | 入力ファイルにエラーが含まれています。リクエストは処理されませんでした。エラーの詳細については、バッチジョブオブジェクトを確認してください。これは、`skip_validation: false` の場合にのみ適用されます。 |
| `batch_failed` | 処理中に予期しないエラーが発生しました。 |
| `cancelled` | バッチジョブがキャンセルされました。一部の結果が利用可能な場合があります。 |
| `upload_timeout` | ファイルがアップロードされる前にアップロード URL の有効期限が切れました。新しいバッチジョブを作成してください。 |
| `timeout` | バッチジョブが 7 日間の最大処理期間を超過しました。一部の結果を利用できる場合があります。 |

### 検証

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.

検証が失敗すると、ステータスは `validation_failed` に変わり、Stripe はリクエストを試行しません。バッチジョブオブジェクトには、最初に発生したエラーの詳細が含まれます。

`skip_validation` が `true` の場合、アップロード後にジョブは `ready_for_upload` から `in_progress` へ直接移行します。個々のリクエストのエラーは、バッチ全体をブロックするのではなく、結果ファイルに表示されます。

### Webhook イベント

バッチジョブは、ライフサイクルの移行ごとに v2 シンイベントを送信します。これらのイベントを受信するには、[v2 イベント送信先](https://docs.stripe.com/events/set-up-events.md)を設定する必要があります。

バッチジョブイベントには、v2 イベントの送信先が必要です。これらは v1 Webhook エンドポイントには配信されません。

次のイベントを使用できます。

| イベントタイプ | 説明 |
| --- | --- |
| `v2.core.batch_job.created` | バッチジョブが作成されました。 |
| `v2.core.batch_job.ready_for_upload` | バッチジョブでファイルをアップロードする準備ができました。 |
| `v2.core.batch_job.validating` | ファイルのアップロードが完了しました。検証中です。 |
| `v2.core.batch_job.validation_failed` | 入力ファイルの検証に失敗しました。 |
| `v2.core.batch_job.completed` | すべてのリクエストが処理されました。 |
| `v2.core.batch_job.batch_failed` | バッチジョブが予期せず失敗しました。 |
| `v2.core.batch_job.canceled` | バッチジョブがキャンセルされました。 |
| `v2.core.batch_job.timeout` | バッチジョブが最大処理時間を超えました。 |
| `v2.core.batch_job.upload_timeout` | ファイルがアップロードされる前にアップロード URL の有効期限が切れました。 |
| `v2.core.batch_job.updated` | バッチジョブのステータスまたは進捗状況が変更されました。 |

すべてのバッチジョブイベントには、ジョブの作成時に指定したメタデータが含まれます。これを使用して、イベントを内部システムと関連付けることができます。

`notification_suppression`が `{"scope": "all"}`に設定されている場合、基本となる API 操作 (サブスクリプション更新イベントなど) からの Webhook は抑制されます。上記のバッチレベルのイベントは、この設定に関係なく常に配信されます。

## 結果をダウンロードする

バッチジョブが `complete` ステータスに達すると、`status_details` フィールドには、成功と失敗のサマリーと、出力ファイルの事前署名済みダウンロード URL が含まれます。

```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/..."
        }
      }
    }
  }
}
```

`status_details.complete.output_file.download_url.url` の URL を使用してファイルをダウンロードします。Stripe は、バッチジョブが次のいずれかの状態になると出力ファイルを提供します。

- `complete`
- `cancelled`
- `timeout`
- `validation_failed`

ダウンロード URL の有効期限を確認するには、`expires_at` フィールドで期限を確認します。

結果ファイルには、成功したリクエストと失敗したリクエストの両方が 1 つのファイルに含まれています。失敗を見つけるには、`status` が `200` 以外の行でフィルタリングします。

### 結果のファイル形式

出力ファイルは JSONL 形式 (1 行に 1 つの JSON オブジェクト) を使用します。各行には次のフィールドが含まれます。

| フィールド | 説明 |
| --- | --- |
| `id` | 入力ファイルのリクエスト ID。これを使用して、結果をリクエストと照合します。 |
| `response` | 完全な API レスポンスオブジェクト。成功した場合はリソース、失敗した場合はエラーオブジェクトが含まれます。 |
| `status` | HTTP ステータスコードを整数で指定します (`200`、`402` など)。 |
| `context` | リクエストの実行対象となった連結アカウント。 |

### 結果ファイルの例

リクエストが成功すると、API リソース全体が `response` フィールドに返されます。

```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
}
```

失敗したリクエストはエラーオブジェクトを返します。

```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
}
```

入力行に `context` が含まれる場合、対応する出力にそれが反映されます。

```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.

## バッチジョブをキャンセルする

まだ完了していないバッチジョブをキャンセルするには、`POST` リクエストを送信します。

```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"
```

キャンセルは非同期で行われます。ジョブはまず、処理中のリクエストが完了する間 `cancelling` に移行し、その後 `cancelled` に移行します。キャンセル前に処理されたリクエストの一部の結果は、結果ファイルで確認できます。

## Connect での利用

プラットフォームアカウントは、連結アカウントに代わってバッチジョブを実行できます。通常どおり、プラットフォームの API キーを使用してバッチジョブを作成します。入力ファイルの個別のリクエストで連結アカウントを対象にするには、`context` フィールドを連結アカウントの ID に設定します。これは、ダイレクト API コールにおける `Stripe-Account` ヘッダーのリクエストごとの相当機能です。

```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"
    }
  }'
```

入力ファイル内で、連結アカウントとして実行する各行に `context` を追加します。

```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"}}
```

`context` のない行は、プラットフォームアカウントとして実行されます。`context` のある行は、指定された連結アカウントとして実行されます。同じバッチファイル内で両方を混在させることができます。