> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://zuora.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server. # Create a bulk job POST https://rest.test.zuora.com/bulk-data/bulk-jobs Content-Type: application/json Creates a new bulk job. The job type can be one of Import, Delete, Update, or Cancel. The response includes the job ID and information needed to upload your data file to S3. ### Next Step: Upload the File to S3 After creating a bulk job, you must upload the data file to Amazon S3 using the information returned in the `uploadFileInfo` object. This includes: * `uploadUrl`: The S3 endpoint to which the file must be uploaded. * `formFields`: Key-value pairs to include in a multipart/form-data POST request. * `jobId`: The ID of the job, used for later submission. You can use the following cURL command to upload the file: ``` curl --request POST \ --url '' \ --header 'Content-Type: multipart/form-data' \ --form 'key=' \ --form 'bucket=' \ --form 'x-amz-algorithm=' \ --form 'x-amz-credential=' \ --form 'x-amz-date=' \ --form 'Policy=' \ --form 'x-amz-signature=' \ --form 'x-amz-security-token=' \ --form 'file=@/path/to/your/file.csv' ``` **Note**: Always use the exact form field keys returned in the `formFields` object of the API response. This is a presigned Amazon S3 POST operation and not a Zuora endpoint. After uploading the file, you must call the "Submit a bulk job for processing" operation endpoint to start processing the job. Reference: https://zuora.ferndocs.com/developers/api-reference/zuora-api/data-loader/bulk-data/create-bulk-job ## Authentication - `Authorization` header (bearer token, required) — Use `Bearer {{token}}` in the `Authorization` header for authentication. ## Servers - `https://rest.test.zuora.com` (US Developer & Central Sandbox (incl. Test Drive), default) - `https://rest.sandbox.na.zuora.com` (US API Sandbox Cloud 1) - `https://rest.apisandbox.zuora.com` (US API Sandbox Cloud 2) - `https://rest.na.zuora.com` (US Production Cloud 1) - `https://rest.zuora.com` (US Production Cloud 2) - `https://rest.test.eu.zuora.com` (EU Developer & Central Sandbox) - `https://rest.sandbox.eu.zuora.com` (EU API Sandbox) - `https://rest.eu.zuora.com` (EU Production) - `https://rest.test.ap.zuora.com` (APAC Developer & Central Sandbox) - `https://rest.ap.zuora.com` (APAC Production) ## Request ### Headers - `Accept-Encoding` (string, optional) — Include the `Accept-Encoding: gzip` header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a `Content-Encoding` header with the compression algorithm so that your client can decompress it. - `Content-Encoding` (string, optional) — Include the `Content-Encoding: gzip` header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload. - `Zuora-Entity-Ids` (string, optional) — An entity ID. If you have [Zuora Multi-entity](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Multi-entity) enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header. - `Zuora-Org-Ids` (string, optional) — Comma separated IDs. If you have Zuora Multi-Org enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header. The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs. - `Zuora-Track-Id` (string, optional) — A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue. The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (`:`), semicolon (`;`), double quote (`"`), and quote (`'`). ### Body (application/json) This endpoint expects a BulkJobRequest. - `name` (string, required) — Name of the job. Max length is 255 characters - `objectType` (string, required) — Type of the object. Supported object types: - `account` - `accountingcode` - `accountingperiod` - `amendment` - `bill-run` - `bill-run-batches` - `bill-run-filters` - `contact` - `credit-memo` - `credit-memo-from-charge` - `credit-memo-from-invoice` - `debit-memo` - `debit-memo-from-charge` - `debit-memo-from-invoice` - `invoice` - `journal-entry` - `journal-run` - `offer` - `omni-channel-subscription` - `order` - `order-create-order-line-item` - `order-create-subscription-existing-account` - `order-create-subscription-existing-account-with-volume-charge` - `order-create-subscription-with-new-account` - `order-remove-product` - `order-update-subscription-add-product` - `order-update-subscription-change-plan` - `order-update-subscription-price-quantity-change` - `payment` - `payment-profile` - `payment-schedule` - `payment-schedule-item` - `payments-simple` - `payments-unapply` - `price-book-item` - `product` - `product-charge-definition` - `product-rate-plan` - `product-rate-plan-charge` - `product-rate-plan-charge-tier` - `product-rate-plan-definition` - `refund` - `revenue-accounting-code` - `subscription` - `subscription-add-rate-plan` - `subscription-change-rate-plan` - `subscription-remove-rate-plan` - `subscription-update-rate-plan` - `taxation-item` - `unitofmeasure` - `usage` - `description` (string, optional) — Short description of the job. Max length is 255 characters - `mappings` (list of BulkJobRequestMappingsItems, optional) — List of mappings. Each mapping maps a source field to a target field in the object. If the field is an array, the type and arrayType must be specified. - `headers` (list of string, optional) — List of headers in the source file. Required if the source file does not have a header row. - `rowIdHeader` (string, optional) — Header in the source file that contains the row id. - `delimiter` (string, optional) — Delimiter used in the source file. Default is comma. Supported values: comma, tab, pipe, semicolon, colon, caret, tilde, dot/period - `hasHeaders` (boolean, optional) — Indicates if the source file has a header row. Default is false - `fileType` (enum, optional) — Type of the source file. Supported values: csv, jsonl Default is csv, which means delimited file where the delimiter can be comma but can also be one of the other supported delimiters - Allowed values: `csv`, `jsonl` - `jobType` (enum, optional) — Type of the bulk job being created. Default is IMPORT - Allowed values: `Import`, `Delete`, `Update`, `Cancel` - `isCustomObject` (boolean, optional) — Indicates if the object type is a custom object. Default is false - `customObjectNamespace` (string, optional) — Namespace of the custom object. Applicable only when isCustomObject is true. Default namespace is 'default'. - `dataSourceType` (enum, optional) — The data source type of the job - Allowed values: `UserUpload`, `Salesforce`, `Chargebee`, `Stripe` - `systemType` (enum, optional) — The system type for the job - Allowed values: `BILLING` ## Response ### 200 Job creation successful - `id` (string, optional) — Unique identifier for the job - `uploadUrl` (string, optional) — URL to upload the file. This is the URL to which the file should be uploaded using a PUT request. - `uploadRequest` (CreateResponseUploadRequest, optional) - `status` (enum, optional) — Status of the job - Allowed values: `Created`, `Submitted`, `In Progress`, `Aborting`, `Completed`, `Failed`, `Aborted`, `Cancelled`, `Downloading` - `jobType` (enum, optional) — Type of the job - Allowed values: `Import`, `Delete`, `Update`, `Cancel` ## Types ### BulkJobRequestMappingsItems - `source` (string, required) — Source field name - `target` (string, required) — Target field name. **Note**: The `target` field must not contain spaces, dots (`.`), underscores (`_`), or asterisks (`*`). - `type` (enum, optional) — Field type - Allowed values: `array`, `string`, `number`, `boolean` - `arrayType` (enum, optional) — Type of objects in the array if the field is an array type - Allowed values: `string`, `number`, `boolean` ### CreateResponseUploadRequest - `uri` (string, optional) — URL to which the file must be uploaded. - `fields` (map from string to string, optional) — Form fields required to complete the S3 file upload. ## Examples **Request** ```json { "name": "Customer Account Import April 2026", "objectType": "account" } ``` **Response** ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "uploadUrl": "https://zuora-bulk-upload.s3.amazonaws.com/upload/3fa85f64-5717-4562-b3fc-2c963f66afa6", "uploadRequest": { "uri": "https://zuora-bulk-upload.s3.amazonaws.com/upload/3fa85f64-5717-4562-b3fc-2c963f66afa6", "fields": {} }, "status": "Created", "jobType": "Import" } ``` **SDK Code** ```python import requests url = "https://rest.test.zuora.com/bulk-data/bulk-jobs" payload = { "name": "Customer Account Import April 2026", "objectType": "account" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://rest.test.zuora.com/bulk-data/bulk-jobs'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"Customer Account Import April 2026","objectType":"account"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://rest.test.zuora.com/bulk-data/bulk-jobs" payload := strings.NewReader("{\n \"name\": \"Customer Account Import April 2026\",\n \"objectType\": \"account\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://rest.test.zuora.com/bulk-data/bulk-jobs") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Customer Account Import April 2026\",\n \"objectType\": \"account\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://rest.test.zuora.com/bulk-data/bulk-jobs") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Customer Account Import April 2026\",\n \"objectType\": \"account\"\n}") .asString(); ``` ```php request('POST', 'https://rest.test.zuora.com/bulk-data/bulk-jobs', [ 'body' => '{ "name": "Customer Account Import April 2026", "objectType": "account" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://rest.test.zuora.com/bulk-data/bulk-jobs"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Customer Account Import April 2026\",\n \"objectType\": \"account\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "Customer Account Import April 2026", "objectType": "account" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://rest.test.zuora.com/bulk-data/bulk-jobs")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```