Xero: Updates or creates one or more sales invoices or purchase bills

← Accounting operations · Get started

Operation xero.updateorcreateinvoices

Provider route: POST /api.xro/2.0/Invoices. 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"]["updateOrCreateInvoices"]>[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.updateOrCreateInvoices(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.update_or_create_invoices(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
query.unitdp	integer	Optional
query.allowBackorders	boolean	Optional
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 Updates a specific sales invoices or purchase bills — request body — body

Referenced models: Updates a specific sales invoices or purchase bills — 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 Retrieves sales invoices or purchase bills — response body

Referenced models: Retrieves sales invoices or purchase bills — response body

Schemas

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

Updates a specific sales invoices or purchase bills — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
Invoices	array	Optional
Invoices[]	Model	Each item	Expand Creates a single payment for invoice or credit notes — request body — body Invoice
Warnings	array	Optional	Displays array of warning messages from the API
Warnings[]	Model	Each item	Expand Retrieves journals — response body — Warnings item
pagination	Model	Optional	Expand Creates a new credit note — request body — body pagination

Referenced models: Creates a new credit note — request body — body pagination, Creates a single payment for invoice or credit notes — request body — body Invoice, Retrieves journals — response body — Warnings item

Retrieves sales invoices or purchase bills — response body

Field	Type	Presence	Description and constraints
$	object	Root
Invoices	array	Optional
Invoices[]	Model	Each item	Expand Deletes an Allocation from a Prepayment — response body — Invoice
Warnings	array	Optional	Displays array of warning messages from the API
Warnings[]	Model	Each item	Expand Retrieves journals — response body — Warnings item
pagination	Model	Optional	Expand Retrieves prepayments — response body — pagination

Referenced models: Retrieves prepayments — response body — pagination, Deletes an Allocation from a Prepayment — response body — Invoice, Retrieves journals — response body — Warnings item

Creates a new credit note — request body — body pagination

Field	Type	Presence	Description and constraints
$	object	Root
itemCount	integer	Optional
page	integer	Optional
pageCount	integer	Optional
pageSize	integer	Optional

Retrieves journals — response body — Warnings item

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

Retrieves prepayments — response body — pagination

Field	Type	Presence	Description and constraints
$	object	Root
itemCount	JSON	Optional
itemCount (anyOf 1)	integer	Alternative
itemCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
page	JSON	Optional
page (anyOf 1)	integer	Alternative
page (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pageCount	JSON	Optional
pageCount (anyOf 1)	integer	Alternative
pageCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pageSize	JSON	Optional
pageSize (anyOf 1)	integer	Alternative
pageSize (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

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

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

Field	Type	Presence	Description and constraints
$	object	Root
AddressLine1	string	Optional	First line of a physical address
AddressLine2	string	Optional	Second line of a physical address
AddressLine3	string	Optional	Third line of a physical address
AddressLine4	string	Optional	Fourth line of a physical address
City	string	Optional	City of a physical address
Country	string	Optional	Country of a physical address
InvoiceAddressType	string	Optional	Indicates whether the address is defined as origin (FROM) or destination (TO) One of: FROM, TO
PostalCode	string	Optional	Postal code of a physical address
Region	string	Optional	Region or state of a physical address

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

Field	Type	Presence	Description and constraints
$	object	Root
AccountCode	string	Optional	See Accounts
AccountID	string	Optional	The associated account ID related to this line item Format: uuid
Description	string	Optional	Description needs to be at least 1 char long. A line item with just a description (i.e no unit amount or quantity) can be created by specifying just a <Description> element that contains at least 1 character
DiscountAmount	number	Optional	Discount amount being applied to a line item. Only supported on ACCREC invoices and quotes. ACCPAY invoices and credit notes in Xero do not support discounts. Format: double
DiscountRate	number	Optional	Percentage discount being applied to a line item (only supported on ACCREC invoices – ACC PAY invoices and credit notes in Xero do not support discounts Format: double
Item	Model	Optional	Expand Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Item
ItemCode	string	Optional	See Items
LineAmount	number	Optional	If you wish to omit either the Quantity or UnitAmount you can provide a LineAmount and Xero will calculate the missing amount for you. The line amount reflects the discounted price if either a DiscountRate or DiscountAmount has been used i.e. LineAmount = Quantity * Unit Amount * ((100 - DiscountRate)/100) or LineAmount = (Quantity * UnitAmount) - DiscountAmount Format: double
LineItemID	string	Optional	LineItem unique ID Format: uuid
Quantity	number	Optional	LineItem Quantity Format: double
RepeatingInvoiceID	string	Optional	The Xero identifier for a Repeating Invoice Format: uuid
SalesTaxCodeId	number	Optional	The ID of the sales tax code
TaxAmount	number	Optional	The tax amount is auto calculated as a percentage of the line amount (see below) based on the tax rate. This value can be overriden if the calculated <TaxAmount> is not correct. Format: double
TaxBreakdown	array	Optional	An array of tax components defined for this line item
TaxBreakdown[]	Model	Each item	Expand Creates a single payment for invoice or credit notes — request body — body Invoice Line Items item Tax Breakdown item
TaxType	string	Optional	The tax type from TaxRates
Taxability	string	Optional	The type of taxability One of: TAXABLE, NON_TAXABLE, EXEMPT, PART_TAXABLE, NOT_APPLICABLE
Tracking	array	Optional	Optional Tracking Category – see Tracking. Any LineItem can have a maximum of 2 <TrackingCategory> elements.
Tracking[]	Model	Each item	Expand Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Tracking item
UnitAmount	number	Optional	LineItem Unit Amount Format: double

Referenced models: Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Item, Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Tracking item, Creates a single payment for invoice or credit notes — request body — body Invoice Line Items item Tax Breakdown item

Policy, approvals and errors

SDK function policy ID: xero.updateorcreateinvoices. Catalog operation: updateOrCreateInvoices. 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