# 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 <>" \ -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 <>" \ -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` (object, required) The endpoint configuration for the batch job. - `endpoint.http_method` (enum, required) The HTTP method to use when calling the endpoint. Possible enum values: - `delete` HTTP DELETE method. - `post` HTTP POST method. - `endpoint.path` (string, required) The path of the endpoint to run this batch job against. In the form used in the documentation. For instance, for subscription migration this would be `/v1/subscriptions/:id/migrate`. - `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` (object, optional) Notification suppression settings for the batch job. - `notification_suppression.scope` (enum, required) The scope of notification suppression. Possible enum values: - `all` Suppress all notifications for the batch job. - `none` Do not suppress any notifications 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` (object, nullable) Additional details about the current state of the `batch_job`. - `status_details.batch_failed` (object, nullable) Additional details for the `BATCH_FAILED` status of the `batch_job`. - `status_details.batch_failed.error` (string) Details about the `batch_job` failure. - `status_details.canceled` (object, nullable) Additional details for the `CANCELED` status of the `batch_job`. - `status_details.canceled.failure_count` (int64) The total number of records that failed processing. - `status_details.canceled.output_file` (object) The output file details. If the `batch_job` is canceled, this is provided only if there is already output at this point. - `status_details.canceled.output_file.content_type` (string) The content type of the file. - `status_details.canceled.output_file.download_url` (object) A pre-signed URL that allows secure, time-limited access to download the file. - `status_details.canceled.output_file.download_url.expires_at` (timestamp, nullable) The time that the URL expires. - `status_details.canceled.output_file.download_url.url` (string) The URL that can be used for accessing the file. - `status_details.canceled.output_file.size` (int64) The total size of the file in bytes. - `status_details.canceled.success_count` (int64) The total number of records that were successfully processed. - `status_details.complete` (object, nullable) Additional details for the `COMPLETE` status of the `batch_job`. - `status_details.complete.failure_count` (int64) The total number of records that failed processing. - `status_details.complete.output_file` (object) The output file details. If the `batch_job` is canceled, this is provided only if there is already output at this point. - `status_details.complete.output_file.content_type` (string) The content type of the file. - `status_details.complete.output_file.download_url` (object) A pre-signed URL that allows secure, time-limited access to download the file. - `status_details.complete.output_file.download_url.expires_at` (timestamp, nullable) The time that the URL expires. - `status_details.complete.output_file.download_url.url` (string) The URL that can be used for accessing the file. - `status_details.complete.output_file.size` (int64) The total size of the file in bytes. - `status_details.complete.success_count` (int64) The total number of records that were successfully processed. - `status_details.in_progress` (object, nullable) Additional details for the `IN_PROGRESS` status of the `batch_job`. - `status_details.in_progress.failure_count` (int64) The number of records that failed processing so far. - `status_details.in_progress.success_count` (int64) The number of records that were successfully processed so far. - `status_details.ready_for_upload` (object, nullable) Additional details for the `READY_FOR_UPLOAD` status of the `batch_job`. - `status_details.ready_for_upload.upload_url` (object) The upload file details. - `status_details.ready_for_upload.upload_url.expires_at` (timestamp, nullable) The time that the URL expires. - `status_details.ready_for_upload.upload_url.url` (string) The URL that can be used for accessing the file. - `status_details.timeout` (object, nullable) Additional details for the `TIMEOUT` status of the `batch_job`. - `status_details.timeout.failure_count` (int64) The total number of records that failed processing. - `status_details.timeout.output_file` (object) The output file details. If the `batch_job` is canceled, this is provided only if there is already output at this point. - `status_details.timeout.output_file.content_type` (string) The content type of the file. - `status_details.timeout.output_file.download_url` (object) A pre-signed URL that allows secure, time-limited access to download the file. - `status_details.timeout.output_file.download_url.expires_at` (timestamp, nullable) The time that the URL expires. - `status_details.timeout.output_file.download_url.url` (string) The URL that can be used for accessing the file. - `status_details.timeout.output_file.size` (int64) The total size of the file in bytes. - `status_details.timeout.success_count` (int64) The total number of records that were successfully processed. - `status_details.validating` (object, nullable) Additional details for the `VALIDATING` status of the `batch_job`. - `status_details.validating.validated_count` (int64) The number of records that were validated. Note that there is no failure counter here; once we have any validation failures we give up. - `status_details.validation_failed` (object, nullable) Additional details for the `VALIDATION_FAILED` status of the `batch_job`. - `status_details.validation_failed.failure_count` (int64) The total number of records that failed processing. - `status_details.validation_failed.output_file` (object) The output file details. If the `batch_job` is canceled, this is provided only if there is already output at this point. - `status_details.validation_failed.output_file.content_type` (string) The content type of the file. - `status_details.validation_failed.output_file.download_url` (object) A pre-signed URL that allows secure, time-limited access to download the file. - `status_details.validation_failed.output_file.download_url.expires_at` (timestamp, nullable) The time that the URL expires. - `status_details.validation_failed.output_file.download_url.url` (string) The URL that can be used for accessing the file. - `status_details.validation_failed.output_file.size` (int64) The total size of the file in bytes. - `status_details.validation_failed.success_count` (int64) The total number of records that were successfully processed. ## 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. |