Get Invoices

Retrieves sales invoices or purchase bills

GET/Invoices

Use it in a workflow

Add a step and choose the Xero connector.
Pick the Get Invoices action (under Xero).
Fill in the fields below, then reference the result from later steps as {{getInvoices.response.data}}.

Request

Query parameters

wherestring

Filter by an any element

orderstring

Order by an any element

IDsarray<string (uuid)>

Filter by a comma-separated list of InvoicesIDs.

InvoiceNumbersarray<string>

Filter by a comma-separated list of InvoiceNumbers.

ContactIDsarray<string (uuid)>

Filter by a comma-separated list of ContactIDs.

Statusesarray<string>

Filter by a comma-separated list Statuses. For faster response times we recommend using these explicit parameters instead of passing OR conditions into the Where filter.

pageinteger

e.g. page=1 – Up to 100 invoices will be returned in a single API call with line items shown for each invoice

includeArchivedboolean

e.g. includeArchived=true - Invoices with a status of ARCHIVED will be included in the response

createdByMyAppboolean

When set to true you'll only retrieve Invoices created by your app

unitdpinteger

e.g. unitdp=4 – (Unit Decimal Places) You can opt in to use four decimal places for unit amounts

summaryOnlyboolean

Use summaryOnly=true in GET Contacts and Invoices endpoint to retrieve a smaller version of the response object. This returns only lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient.

Default false

pageSizeinteger

Number of records to retrieve per page

searchTermstring

Search parameter that performs a case-insensitive text search across the fields e.g. InvoiceNumber, Reference.

Headers

xero-tenant-idstringrequired

Xero identifier for Tenant

If-Modified-Sincestring (date-time)

Only records created or modified since this timestamp will be returned

Response

Returns 200 with an object. Read it in later steps with {{getInvoices.response.data.<field>}}.

paginationobject

pageinteger

pageSizeinteger

pageCountinteger

itemCountinteger

Warningsarray<object>

Displays array of warning messages from the API

Messagestring

Validation error message

Invoicesarray<object>

Typestring

See Invoice Types

One ofACCPAYACCPAYCREDITAPOVERPAYMENTAPPREPAYMENTACCRECACCRECCREDITAROVERPAYMENTARPREPAYMENT

Contactobject40 fields

LineItemsarray<object>18 fields

See LineItems

Datestring

Date invoice was issued – YYYY-MM-DD. If the Date element is not specified it will default to the current date based on the timezone setting of the organisation

DueDatestring

Date invoice is due – YYYY-MM-DD

LineAmountTypesstring

Line amounts are exclusive of tax by default if you don’t specify this element. See Line Amount Types

One ofExclusiveInclusiveNoTax

InvoiceNumberstring

ACCREC – Unique alpha numeric code identifying invoice (when missing will auto-generate from your Organisation Invoice Settings) (max length = 255)

Referencestring

ACCREC only – additional reference number

BrandingThemeIDstring (uuid)

See BrandingThemes

Urlstring

URL link to a source document – shown as “Go to [appName]” in the Xero app

CurrencyCodestring

3 letter alpha code for the currency – see list of currency codes

One ofAEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBYRBZDCADCDFCHFCLFCLPCNYCOPCRCCUCCUPCVECZKDJFDKK

CurrencyRatenumber (double)

The currency rate for a multicurrency invoice. If no rate is specified, the XE.com day rate is used. (max length = [18].[6])

Statusstring

See Invoice Status Codes

One ofDRAFTSUBMITTEDDELETEDAUTHORISEDPAIDVOIDED

SentToContactboolean

Boolean to set whether the invoice in the Xero app should be marked as “sent”. This can be set only on invoices that have been approved

ExpectedPaymentDatestring

Shown on sales invoices (Accounts Receivable) when this has been set

PlannedPaymentDatestring

Shown on bills (Accounts Payable) when this has been set

CISDeductionnumber (double)

CIS deduction for UK contractors

CISRatenumber (double)

CIS Deduction rate for the organisation

SubTotalnumber (double)

Total of invoice excluding taxes

TotalTaxnumber (double)

Total tax on invoice

Totalnumber (double)

Total of Invoice tax inclusive (i.e. SubTotal + TotalTax). This will be ignored if it doesn’t equal the sum of the LineAmounts

TotalDiscountnumber (double)

Total of discounts applied on the invoice line items

InvoiceIDstring (uuid)

Xero generated unique identifier for invoice

RepeatingInvoiceIDstring (uuid)

Xero generated unique identifier for repeating invoices

HasAttachmentsboolean

boolean to indicate if an invoice has an attachment

Default "false"

IsDiscountedboolean

boolean to indicate if an invoice has a discount

Paymentsarray<object>29 fields

See Payments

Prepaymentsarray<object>23 fields

See Prepayments

Overpaymentsarray<object>21 fields

See Overpayments

AmountDuenumber (double)

Amount remaining to be paid on invoice

AmountPaidnumber (double)

Sum of payments received for invoice

FullyPaidOnDatestring

The date the invoice was fully paid. Only returned on fully paid invoices

AmountCreditednumber (double)

Sum of all credit notes, over-payments and pre-payments applied to invoice

UpdatedDateUTCstring

UTC timestamp of last update to the invoice

UpdatedDateUTCStringstring

UTC ISO-8601 formatted timestamp of last update to the invoice

CreditNotesarray<object>

Details of credit notes that have been applied to an invoice

Attachmentsarray<object>6 fields

Displays array of attachments from the API

HasErrorsboolean

A boolean to indicate if a invoice has an validation errors

Default "false"

StatusAttributeStringstring

A string to indicate if a invoice status

ValidationErrorsarray<object>1 fields

Displays array of validation error messages from the API

json

{
  "pagination": {
    "page": 0,
    "pageSize": 0,
    "pageCount": 0,
    "itemCount": 0
  },
  "Warnings": [
    {
      "Message": "string"
    }
  ],
  "Invoices": [
    {
      "Type": "ACCPAY",
      "Contact": {
        "ContactID": "00000000-0000-0000-0000-000000000000",
        "MergedToContactID": "00000000-0000-0000-0000-000000000000",
        "ContactNumber": "string",
        "AccountNumber": "string",
        "ContactStatus": "ACTIVE",
        "Name": "string",
        "FirstName": "string",
        "LastName": "string",
        "CompanyNumber": "string",
        "EmailAddress": "string",
        "ContactPersons": [
          {
            "FirstName": "string",
            "LastName": "string",
            "EmailAddress": "string",
            "IncludeInEmails": false
          }
        ],
        "BankAccountDetails": "string"
      },
      "LineItems": [
        {
          "LineItemID": "00000000-0000-0000-0000-000000000000",
          "Description": "string",
          "Quantity": 0,
          "UnitAmount": 0,
          "ItemCode": "string",
          "AccountCode": "string",
          "AccountID": "00000000-0000-0000-0000-000000000000",
          "TaxType": "string",
          "TaxAmount": 0,
          "Item": {
            "Code": "string",
            "Name": "string",
            "ItemID": "00000000-0000-0000-0000-000000000000"
          },
          "LineAmount": 0,
          "Tracking": [
            {
              "TrackingCategoryID": null,
              "TrackingOptionID": null,
              "Name": null,
              "Option": null
            }
          ]
        }
      ],
      "Date": "string",
      "DueDate": "string",
      "LineAmountTypes": "Exclusive",
      "InvoiceNumber": "string",
      "Reference": "string",
      "BrandingThemeID": "00000000-0000-0000-0000-000000000000",
      "Url": "string",
      "CurrencyCode": "AED",
      "CurrencyRate": 0
    }
  ]
}

Need more? See the Xero guide for connection setup and behaviour shared by every action.

Was this page helpful?