Split an invoice

PUT

/v1/invoices/:invoiceKey/split

PUT

/v1/invoices/:invoiceKey/split

from zuora import ZuoraClient, SplitInvoiceResponseSplitItems
import datetime
client = ZuoraClient(
    token="YOUR_TOKEN_HERE",
)
client.invoices.split_invoice(
    invoice_key="invoiceKey",
    split_type="Amount",
    splits=[
        SplitInvoiceResponseSplitItems(
            split_amount=50,
            invoice_date=datetime.date.fromisoformat("2026-02-01"),
            payment_term="Due Upon Receipt",
        ),
        SplitInvoiceResponseSplitItems(
            split_amount=80,
            invoice_date=datetime.date.fromisoformat("2026-02-15"),
            payment_term="Net 30",
        )
    ],
)

{
  "response": {
    "id": "8a90b9ce9cda030a019cdc3e8a455fc5",
    "invoices": [
      {
        "amount": 50,
        "id": "8a90ff929cda0319019cdc458ee6669e",
        "invoiceDate": "2026-02-01",
        "invoiceNumber": "INV00049021"
      },
      {
        "amount": 80,
        "id": "8a90ff929cda0319019cdc458ef266a1",
        "invoiceDate": "2026-02-15",
        "invoiceNumber": "INV00049022"
      }
    ],
    "jobId": "8a90ff929cda0319019cdc458e8d669c",
    "jobStatus": "Completed",
    "success": true
  }
}

Splits a draft invoice into 2 to 20 invoices based on specified amounts or percentages. The source invoice must be in Draft status. For amount-based splits, the sum of all split amounts must exactly equal the original invoice total, and each split amount must be at least the minimum currency unit. For percentage-based splits, the sum of all split percentages must be exactly 100, up to 9 decimal places. Zuora distributes charges, discounts, tax amounts, and tax-exempt amounts proportionally across split invoices and uses a Largest Remainder algorithm to ensure precise rounding at both the line and invoice levels.

In exclusive-tax mode, split amounts can be specified excluding tax, with tax calculated at posting, or including tax when draft tax is calculated. In inclusive-tax mode, split amounts always represent tax-inclusive invoice totals, with embedded tax distributed proportionally.

For invoices with a large number of invoice items, this operation might be processed asynchronously. Use the jobStatus field in the response to determine the job status:

If jobStatus is Completed, the operation has finished and the response contains the result.
If jobStatus is Pending, the operation is still in progress, and you must retrieve the job status later to confirm completion.

Authentication

AuthorizationBearer

Use Bearer {{token}} in the Authorization header for authentication.

Path parameters

invoiceKeystringRequired

The ID or number of the invoice. For example, 2c92c8955bd63cc1015bd7c151af02ab or INV-0000001.

Headers

Content-EncodingstringOptional

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-Org-IdsstringOptional

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.

Request

This endpoint expects an object.

splitTypeenumOptional

How the split is calculated.

Allowed values:

splitslist of objectsOptional

Array of split configurations.

Response headers

Content-EncodingstringOptional

This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.

Note that only the following MIME types support gzipped responses:

application/json
application/xml
text/html
text/csv
text/plain

RateLimit-LimitstringOptional

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingdouble

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetdouble

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-IdstringOptional

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-IdstringOptional

A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

Concurrency-Limit-TypestringOptional

The type of the concurrency limit, which can be Default, High-volume transactions, or Object Query.

For more information, see Concurrent request limits.

Concurrency-Limit-Limitinteger

The total number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Concurrency-Limit-Remaininginteger

The remaining number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Response

successbooleanOptional

Indicates whether the request was successful.

idstringOptional

Unique identifier for the request.

jobIdstringOptional

Identifier of the async job.

jobStatusenumOptional

Status of the job.

For invoices with a large number of invoice items, this operation might run asynchronously. In this case, the response includes jobId and jobStatus. The jobId identifies the operation job, and jobStatus indicates whether the operation is Completed or Pending. If jobStatus is Pending, use the “Retrieve an operation job” operation to check the job status until the operation is complete.

Allowed values:

invoiceslist of objectsOptional

List of generated invoices.

Errors

4XX

Client Request Error

500

Internal Server Error