# Create a Batch Job

Creates a new batch job.

#### Create a batch job

#### Create a batch job

## Request

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

### Response

```json
{
  "id": "batchv2_AbCdEfGhIjKlMnOpQrStUvWxYz",
  "object": "v2.core.batch_job",
  "created": "2026-03-09T20:55:31.000Z",
  "maximum_rps": 10,
  "metadata": {},
  "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/..."
      }
    }
  }
}
```

#### Create with custom RPS and skip validation

#### Create with custom RPS and skip validation

## Request

```curl
curl -X POST https://api.stripe.com/v2/core/batch_jobs \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "endpoint": {
        "path": "/v1/customers/:customer",
        "http_method": "post"
    },
    "maximum_rps": 25,
    "skip_validation": true,
    "metadata": {
        "batch_id": "run_abc123"
    }
  }'
```

### Response

```json
{
  "id": "batchv2_BcDeFgHiJkLmNoPqRsTuVwXyZa",
  "object": "v2.core.batch_job",
  "created": "2026-03-09T20:55:31.000Z",
  "maximum_rps": 25,
  "metadata": {
    "batch_id": "run_abc123"
  },
  "skip_validation": true,
  "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/..."
      }
    }
  }
}
```

## Parameters

- [`endpoint`](https://docs.stripe.com/api/v2/core/batch-jobs/create.md?query=endpoint&api-version=2026-04-22.preview) (object, required)
  The endpoint configuration for the batch job.

- `metadata` (map, required)
  The metadata of the `batch_job`.

- `skip_validation` (boolean, required)
  Allows the user to skip validation.

- `maximum_rps` (integer, optional)
  Optional field that allows the user to control how fast they want this batch job to run. Gives them a control over the number of webhooks they receive.

- [`notification_suppression`](https://docs.stripe.com/api/v2/core/batch-jobs/create.md?query=notification_suppression&api-version=2026-04-22.preview) (object, optional)
  Notification suppression settings for the batch job.

## Returns

## Response attributes

- `id` (string)
  Unique identifier for the `batch_job`.

- `object` (string, value is "v2.core.batch_job")
  String representing the object’s type. Objects of the same type share the same value of the object field.

- `created` (timestamp)
  Timestamp at which the `batch_job` was created.

- `livemode` (boolean)
  Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.

- `maximum_rps` (integer)
  The maximum requests per second defined for the `batch_job`.

- `metadata` (map)
  The metadata of the `batch_job`.

- `skip_validation` (boolean)
  Whether validation runs before executing the `batch_job`.

- `status` (enum)
  The current status of the `batch_job`.
Possible enum values:
  - `batch_failed`
    The batch job failed to complete because of an error.

  - `canceled`
    The batch job was canceled.

  - `cancelling`
    The batch job is in the process of being canceled.

  - `complete`
    The batch job successfully finished.

  - `in_progress`
    Validation succeeded and the batch job is in progress.

  - `ready_for_upload`
    The batch job was initialized and the user can upload the input file now.

  - `timeout`
    The batch job timed out.

  - `upload_timeout`
    The input file wasn’t uploaded in time.

  - `validating`
    Input file was uploaded and validation is in progress.

  - `validation_failed`
    The batch job failed validation and was never processed.

- [`status_details`](https://docs.stripe.com/api/v2/core/batch-jobs/create.md?query=status_details&api-version=2026-04-22.preview) (object, nullable)
  Additional details about the current state of the `batch_job`.

## Error Codes

| HTTP status code | Code | Description |
| --- | --- | --- |
| 400 | auth_unauthorized_endpoint | Returned when merchant isn’t allowed to access endpoint. |
| 400 | batch_api_invalid_maximum_rps | Returned when a merchant provided an invalid maximum requests per second. |
| 400 | batch_api_unsupported_endpoint | Returned when using an invalid endpoint. |
| 400 | stripe_api_version_not_provided | Returned when the Stripe API version is not provided on the request. |