# Batch jobs

Process multiple API requests asynchronously with a single file upload.

The Batch Jobs API lets you perform bulk operations on Stripe resources. Instead of making an individual API call for each operation, which can trigger rate limits, you can upload a file with all of your operations and let Stripe process them asynchronously. Use batch jobs for one-time migrations, bulk updates, or any operation that requires processing many resources.

## When to use batch jobs

Batch jobs work well for:

- **Bulk migrations**: Move large numbers of subscriptions to new billing modes.
- **Mass updates**: Update many accounts or subscriptions at once.

Batch jobs don’t work well for:

- Operations that require an immediate synchronous response.
- Real-time processing with tight timing requirements.
- A single API request.
- Sequential flows where one request depends on the result of another, such as creating customers and then subscriptions for them. Instead, run each step as a separate batch job. For details, see [Create related objects across batches](https://docs.stripe.com/batch-api/create.md#create-related-objects-across-batches).
- Multiple updates to the same object in a single batch. Batch jobs don’t guarantee processing order, so the final state of the object is unpredictable.

## How batch jobs work

Each batch job follows four steps, which [Running a batch job](https://docs.stripe.com/batch-api/create.md) covers in detail:

1. [Create a batch job](https://docs.stripe.com/batch-api/create.md#create-a-batch-job) and specify the target API endpoint.
2. [Upload the input file](https://docs.stripe.com/batch-api/create.md#upload-the-input-file) with your requests.
3. [Monitor job status](https://docs.stripe.com/batch-api/create.md#monitor-job-status) through webhooks or polling.
4. [Download the results](https://docs.stripe.com/batch-api/create.md#download-the-results).

## Supported endpoints

The Batch Jobs API supports many endpoints across Stripe resources. Each batch job targets a single endpoint, and all requests in the batch go to that endpoint.

For the complete list of available endpoints, see [Supported endpoints](https://docs.stripe.com/batch-api/supported-endpoints.md).

## Limitations

Review the following limitations:

- Input files are limited to 5 GB. If you need to process a larger file, split it into multiple batch jobs.

- Batch jobs support only JSONL (newline-delimited JSON) files. Batch jobs don’t accept CSV or other formats.

- Requests in a batch can use only `POST` or `DELETE`. Batch jobs don’t support `GET`.

- All requests in a batch must target the same API endpoint.

- Batch jobs don’t guarantee processing order, and the results file doesn’t follow the order of the input file. Use the `id` field to match each result to its request.

- Batch jobs have a maximum processing duration of 7 days. Jobs that exceed this limit transition to `timeout` status, with partial results available.

- Batch jobs are capped at 2 million lines per run. Jobs that exceed this limit fail validation and create no resources. To process more, split the workload into multiple batch jobs and submit them sequentially. See [Split large workloads](https://docs.stripe.com/batch-api/best-practices.md#split-large-workloads). If you need more capacity than this, contact [Stripe support](https://support.stripe.com/contact).

- Results are available for download for 30 days after the job finishes. Each time you retrieve the batch job, Stripe returns a new download URL.

- The upload URL expires 5 minutes after job creation. After that period, the job transitions to `upload_timeout` and you need to create a new one.

- You must upload the input file with an HTTP `PUT` request to the upload URL. The URL doesn’t accept other methods, such as `POST`.