Xero: Creates one or many batch payments for invoices

← Accounting operations · Get started

Operation xero.createbatchpayment

Provider route: PUT /api.xro/2.0/BatchPayments. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/xero with npm, or alter-sdk-xero with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { XeroIntegration } from "@alter-ai/xero";

async function execute(input: Parameters<XeroIntegration["accounting"]["createBatchPayment"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new XeroIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.accounting.createBatchPayment(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_xero import XeroIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = XeroIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.accounting.create_batch_payment(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.summarizeErrors	boolean	Optional	Default: false
headers	object	Required within parent	Additional keys: not allowed
headers.xero-tenant-id	string	Required within parent
headers.Idempotency-Key	string	Optional
body	Model	Required within parent	Expand Creates one or many batch payments for invoices — request body — body

Referenced models: Creates one or many batch payments for invoices — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Creates one or many batch payments for invoices — response body

Referenced models: Creates one or many batch payments for invoices — response body

Schemas

45 more schemas are linked from the tables above, on the schema pages.

Creates one or many batch payments for invoices — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
BatchPayments	array	Optional
BatchPayments[]	Model	Each item	Expand Creates a single payment for invoice or credit notes — request body — body Batch Payment

Referenced models: Creates a single payment for invoice or credit notes — request body — body Batch Payment

Creates one or many batch payments for invoices — response body

Field	Type	Presence	Description and constraints
$	object	Root
BatchPayments	array	Optional
BatchPayments[]	Model	Each item	Expand Creates one or many batch payments for invoices — response body — Batch Payments item

Referenced models: Creates one or many batch payments for invoices — response body — Batch Payments item

Creates a single payment for invoice or credit notes — request body — body Batch Payment

Field	Type	Presence	Description and constraints
$	object	Root
Account	Model	Optional	Expand Creates a new chart of accounts — request body — body
Amount	number	Optional	The amount of the payment. Must be less than or equal to the outstanding amount owing on the invoice e.g. 200.00 Format: double
BatchPaymentID	string	Optional	The Xero generated unique identifier for the bank transaction (read-only) Format: uuid Read only: true
Code	string	Optional	(NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Maximum length: 12
Date	string	Optional	Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06
DateString	string	Optional	Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06
Details	string	Optional	(Non-NZ Only) These details are sent to the org’s bank as a reference for the batch payment transaction. They will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement imported into Xero. Maximum field length = 18
IsReconciled	boolean	Optional	Booelan that tells you if the batch payment has been reconciled (read-only) Read only: true
Narrative	string	Optional	(UK Only) Only shows on the statement line in Xero. Max length =18 Maximum length: 18
Particulars	string	Optional	(NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Maximum length: 12
Payments	array	Optional	An array of payments
Payments[]	Model	Each item	Expand Creates a single payment for invoice or credit notes — request body — body
Reference	string	Optional	(NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Maximum length: 255
Status	string	Optional	AUTHORISED or DELETED (read-only). New batch payments will have a status of AUTHORISED. It is not possible to delete batch payments via the API. One of: AUTHORISED, DELETED Read only: true
TotalAmount	number	Optional	The total of the payments that make up the batch (read-only) Format: double Read only: true
Type	string	Optional	PAYBATCH for bill payments or RECBATCH for sales invoice payments (read-only) One of: PAYBATCH, RECBATCH Read only: true
UpdatedDateUTC	string	Optional	UTC timestamp of last update to the payment Read only: true
ValidationErrors	array	Optional	Displays array of validation error messages from the API
ValidationErrors[]	Model	Each item	Expand Retrieves journals — response body — Warnings item

Referenced models: Creates a new chart of accounts — request body — body, Retrieves journals — response body — Warnings item, Creates a single payment for invoice or credit notes — request body — body

Creates one or many batch payments for invoices — response body — Batch Payments item

Field	Type	Presence	Description and constraints
$	object	Root
Account	Model	Optional	Expand Deletes a chart of accounts — response body — Accounts item
Amount	JSON	Optional
Amount (anyOf 1)	number	Alternative	The amount of the payment. Must be less than or equal to the outstanding amount owing on the invoice e.g. 200.00 Format: double
Amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
BatchPaymentID	string	Optional	The Xero generated unique identifier for the bank transaction (read-only) Format: uuid Read only: true
Code	string	Optional	(NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Maximum length: 12
Date	string	Optional	Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06
DateString	string	Optional	Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06
Details	string	Optional	(Non-NZ Only) These details are sent to the org’s bank as a reference for the batch payment transaction. They will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement imported into Xero. Maximum field length = 18
IsReconciled	boolean	Optional	Booelan that tells you if the batch payment has been reconciled (read-only) Read only: true
Narrative	string	Optional	(UK Only) Only shows on the statement line in Xero. Max length =18 Maximum length: 18
Particulars	string	Optional	(NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Maximum length: 12
Payments	array	Optional	An array of payments
Payments[]	Model	Each item	Expand Retrieves payments for invoices and credit notes — response body — Payments item
Reference	string	Optional	(NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Maximum length: 255
Status	string	Optional	AUTHORISED or DELETED (read-only). New batch payments will have a status of AUTHORISED. It is not possible to delete batch payments via the API. Known values: AUTHORISED, DELETED Read only: true
TotalAmount	JSON	Optional
TotalAmount (anyOf 1)	number	Alternative	The total of the payments that make up the batch (read-only) Format: double Read only: true
TotalAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
Type	string	Optional	PAYBATCH for bill payments or RECBATCH for sales invoice payments (read-only) Known values: PAYBATCH, RECBATCH Read only: true
UpdatedDateUTC	string	Optional	UTC timestamp of last update to the payment Read only: true
ValidationErrors	array	Optional	Displays array of validation error messages from the API
ValidationErrors[]	Model	Each item	Expand Retrieves journals — response body — Warnings item

Referenced models: Deletes a chart of accounts — response body — Accounts item, Retrieves payments for invoices and credit notes — response body — Payments item, Retrieves journals — response body — Warnings item

Retrieves journals — response body — Warnings item

Field	Type	Presence	Description and constraints
$	object	Root
Message	string	Optional	Validation error message

Create a new currency for a Xero organisation — request body — body Code

Field	Type	Presence	Description and constraints
$	string	Root	3 letter alpha code for the currency – see list of currency codes One of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLE, SLL, SOS, SRD, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZMK, ZWD

Creates a single payment for invoice or credit notes — request body — body Invoice Attachments item

Field	Type	Presence	Description and constraints
$	object	Root
AttachmentID	string	Optional	Unique ID for the file Format: uuid
ContentLength	integer	Optional	Length of the file content
FileName	string	Optional	Name of the file
IncludeOnline	boolean	Optional	Include the file with the online invoice
MimeType	string	Optional	Type of file
Url	string	Optional	URL to the file on xero.com

Policy, approvals and errors

SDK function policy ID: xero.createbatchpayment. Catalog operation: createBatchPayment. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source