Skip to main content

Xero Component

Manage invoices, items, accounts, payments and more objects from your Xero account.

Component key: xero

Changelog ↓

Description​

Xero is a cloud-based accounting software platform for small and medium-sized businesses. The Xero component allows you to manage your invoices, payments, items, and contacts through the Xero Rest API.

Connections​

Xero OAuth 2.0​

Xero uses OAuth 2.0 to authorize requests made to the API. In order for your integration to authenticate with your customers' Xero accounts, you will need to create a Xero OAuth 2.0 app:

  • Log on to Xero's developer portal
  • Click New app
    • Give your app a name
    • Select Web app for Integration type
    • Enter your company's URL for Company or application URL
    • Enter https://oauth2.prismatic.io/callback for the Redirect URI
  • Next, open the Configuration page
    • Click Generate Secret and take note of the Client id and Client secret - you'll enter those in a moment

When you add a Xero step to an integration, a Xero OAuth 2.0 connection config variable will be created automatically for you:

  • For Scopes, enter the scopes from this list that are relevant to your integration. Always include the offline_access scope in order for authentication tokens to refresh automatically.
  • For Client ID and Client Secret, enter the values you noted above.
  • A single customer might be logged in to multiple tenants, and Tenant Name is unique for each customer. Leave that input blank, and click the gear icon next to Tenant Name. Adjust Input Visibility and select Customer to make that input visible to your customers. That way, your customers will be prompted for their tenant name when they enable this integration.

For additional information regarding authentication, please refer to the Xero docs.

InputNotesExample
Authorize URL

The OAuth 2.0 Authorization URL for Xero

https://login.xero.com/identity/connect/authorize
Client ID

Provide the Client Id you received from the Xero Developer Console.

Client Secret

Provide the Client Secret you generated from the Xero Developer Console.

Scopes

A space-delimited set of one or more scopes to get the user's permission to access. You must specify 'offline_access' to enable automatic token refresh.

accounting.contacts
Tenant Name

The name of the tenant you are requesting access to.

Acme Inc.
Token URL

The OAuth 2.0 Token URL for Xero

https://identity.xero.com/connect/token

Xero OAuth 2.0 Client Credentials​

Xero uses OAuth 2.0 to authorize requests made to the API. You can use client credentials grant type to access data from a single Xero organization using Custom Connections.

Custom Connections are a premium integration option that utilize the client credentials grant type to access data from a single Xero organization.

Setting up a Custom Connection

  1. Create the Custom Connection

    • Log in to My Apps and click “New App”.
    • Give the integration a name and select “Custom connection” as the integration type.

  2. Select scopes and the authorizing user

    • Next, select the API scopes your integration will need and who will authorize the connection.
    • That user will then be emailed a link that takes them to the authorization step.
    • Once authorization is complete you will receive an email to let you know the connection has been authorized.

  3. Authorize the connection

    • After clicking the Connect button in the email, the authorizing user will be taken to a consent screen where they can see which scopes are being requested and select the organization to connect.
    • Note that an organization needs to have purchased a subscription with sufficient Custom Connections to be authorized and connected.
    • The only exception is the Xero Demo Company, which can be used for free for development purposes.

  4. Retrieve your client id and client secret

    • Once the custom connection has been authorized, the client id will be available on the app details page and you can generate the client secret.
    • You'll enter those into your connection.

For more information, check the documentation here.

InputNotesExample
Client ID

Provide the Client Id you received from the Xero Developer Console.

Client Secret

Provide the Client Secret you generated from the Xero Developer Console.

Scopes

A space-delimited set of one or more scopes to get the user's permission to access. Don't specify 'offline_access' as this is a client credentials flow.

accounting.contacts
Token URL

The OAuth 2.0 Token URL for Xero

https://identity.xero.com/connect/token

Triggers​

Webhook​

Receive and validate webhook requests from Xero for webhooks you configure. | key: webhook

InputNotesExample
Webhook Key

Provide the webhook key that was created upon subscription.

up/tz7l0Q9FM6Wyq3Rli0bqJrfqmtl4idswda/LQ==

{
  "response": {
    "contentType": "application/json; charset=UTF-8",
    "statusCode": 200
  },
  "payload": {
    "headers": {
      "Content-Type": "application/json; charset=UTF-8",
      "Host": "hooks.example.com",
      "x-xero-signature": "ubUJMsDNGuunnCBc/n1g0wc2SpjplAb"
    },
    "body": {
      "data": {
        "events": null,
        "firstEventSequence": 0,
        "lastEventSequence": 0,
        "entropy": "FMLHZNKCVK"
      },
      "contentType": "application/json; charset=UTF-8"
    },
    "rawBody": {
      "data": {
        "type": "Buffer",
        "data": [
          69,
          120,
          97,
          109,
          112,
          108,
          101
        ]
      }
    },
    "queryParameters": {},
    "webhookUrls": {
      "Flow 1": "https://hooks.example.com/trigger/EXAMPLEGbG93Q29uZmlnOmRlNmNmNDMyLTliNWMtN0005NDMxLTRmYzA4ZjViODgxOA=="
    },
    "webhookApiKeys": {
      "Flow 1": [
        "abc-123"
      ]
    },
    "customer": {
      "externalId": "customer-example-external-id",
      "name": "John Doe",
      "id": ""
    },
    "pathFragment": "",
    "invokeUrl": "",
    "executionId": "",
    "instance": {
      "id": "",
      "name": ""
    },
    "user": {
      "id": "",
      "name": "",
      "email": "",
      "externalId": ""
    },
    "integration": {
      "id": "",
      "name": "",
      "versionSequenceId": "",
      "externalVersion": ""
    },
    "flow": {
      "id": "",
      "name": ""
    },
    "startedAt": "",
    "globalDebug": false
  }
}

Data Sources​

Select Account​

Select an account from the list | key: selectAccount | type: picklist

InputNotesExample
Connection

The connection to use.

Select Contact​

Select a contact from the list | key: selectContact | type: picklist

InputNotesExample
Connection

The connection to use.

Select Invoice​

Select an invoice from the list | key: selectInvoice | type: picklist

InputNotesExample
Connection

The connection to use.

Select Item​

Select an item from the list | key: selectItem | type: picklist

InputNotesExample
Connection

The connection to use.

Select Payment​

Select a payment from the list | key: selectPayment | type: picklist

InputNotesExample
Connection

The connection to use.

Actions​

Add Note To Item​

Add a note to an item's history by Id | key: addNoteToItem

InputNotesExample
Item ID

Provide a string value for the Item ID.

example-e40f-414a-8f95-ce6a63196e1a
Notes

Provide a string value for notes to add to an object.

These are example notes.
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "HistoryRecords": [
      {
        "Changes": "Edited",
        "DateUTCString": "2021-11-23T18:38:24",
        "DateUTC": "/Date(1637692704697+0000)/",
        "User": "System Generated",
        "Details": "These are some example details"
      }
    ]
  }
}

Add Notes To Invoice​

Add additional notes to an invoice by Id | key: addNoteToInvoice

InputNotesExample
Invoice ID

Provide a string value for the Invoice ID.

example-e40f-414a-8f95-ce6a63196e1a
Notes

Provide a string value for notes to add to an object.

These are example notes.
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "HistoryRecords": [
      {
        "Changes": "Edited",
        "DateUTCString": "2021-11-23T18:38:24",
        "DateUTC": "/Date(1637692704697+0000)/",
        "User": "System Generated",
        "Details": "These are some example details"
      }
    ]
  }
}

Archive Account​

Archive the information and metadata of an account by Id | key: archiveAccount

InputNotesExample
Account ID

Provide a string value for the Account ID

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "accounts": [
      {
        "AccountID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "200",
        "Name": "Example Account",
        "Status": "ARCHIVED",
        "Type": "REVENUE",
        "TaxType": "OUTPUT"
      }
    ]
  }
}

Archive Contact​

Archive the information and metadata of a contact by Id | key: archiveContact

InputNotesExample
Contact ID

Provide a string value for the Contact ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "contacts": [
      {
        "ContactID": "example-7b92-4e10-84e8-efef27090697",
        "ContactStatus": "ARCHIVED",
        "Name": "Example Contact",
        "EmailAddress": "someone@example.com",
        "IsSupplier": "false",
        "IsCustomer": "false",
        "updatedDateUTC": "/Date(1637614988203+0000)/"
      }
    ]
  }
}

Create Account​

Create a new account | key: createAccount

InputNotesExample
Account Code

Provide a string value for the account code. This value is a customer defined alpha numeric account code.

200
Account Name

Provide a string value for the name of the account.

Example Account
Account Type

Provide a string value for the type of the given account. You can choose from the list of provided values here: https://developer.xero.com/documentation/api/accounting/types#accounts

BANK
Bank Account Number

This value is required if you are creating an account of type 'BANK'.

121-121-1234567
Optional Values

For each item, provide a key and value to be used in the request body.

exampleValue
Show In Expense Claims

This value will determine if your account will show in expense claims. This field is required for certain accounts.

false
Connection

The connection to use.

Xero has support for many different types of accounts. When creating certain accounts they may require you to provide additional fields. You can provide these fields with the 'Optional Values' input. For a list of the required values for each type of account, refer to the documentation provided by Xero.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "accounts": [
      {
        "AccountID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "200",
        "Name": "Example Account",
        "Status": "ARCHIVED",
        "Type": "REVENUE",
        "TaxType": "OUTPUT"
      }
    ]
  }
}

Create Attachment​

Add an attachment to an existing object. Existing attachments with that file name will be overridden. | key: createAttachment

InputNotesExample
Content Type

MIME type of the file you want to upload

image/png
File Data

Provide a value that represents the data of the file you want to upload

File Name

Provide a string value for the name of the file you want to attach to the object. The File Name will become the unique identifier of the file for update operations.

My Example File
Object ID

Provide a string value for the Id of the object.

example-e40f-414a-8f95-ce6a63196e1a
Object Type

Provide a string value for the type of object you would like to access.

Connection

The connection to use.

Create Contact​

Create a new contact | key: createContact

InputNotesExample
Accounts Payable Tax Type

Provide a string value for the tax type of accounts payable for the account. For more information on what value to provide, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/types#tax-types

OUTPUT
Accounts Receivable Tax Type

Provide a string value for the tax type of accounts receivable for the account. For more information on what value to provide, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/types#tax-types

OUTPUT
Additional Fields

Additional fields that might not be covered by the standard inputs. See https://developer.xero.com/documentation/api/accounting/contacts#post-contacts for additional fields.

Address

Provide a string value that represents a valid address.

4 Privet Drive
Address Type

Provide a string value for the address type.

POBOX
Bank Account Details

Provide a string value for the details of the contacts bank account. Depending on the type of account, providing a value for this field could cause your request to fail. For more information on the expected shape of the Account object, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/accounts/#get-accounts

01-0123-example-00
City

Provide a string value for the city of the address.

San Francisco
Contact Name

Provide a string value for the name of the contact.

Acme Inc.
Contact Status

Provide a string value for the status of the contact.

Country

Provide a string value for the country of the address.

United States
Default Currency

Provide a valid type of currency.

USD
Email Address

Provide a valid email address for the contact.

someone@example.com
First Name

Provide a string value for the first name of the contact.

John
Last Name

Provide a string value for the last name of the contact.

Doe
Postal Code

Provide a valid postal code.

48423
Region

Provide a string value for the region of the address.

California
Tax Number

Provide a string value for the Tax number. For more information on what value to provide, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/types#tax-types

12-345-678
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "contacts": [
      {
        "ContactID": "example-7b92-4e10-84e8-efef27090697",
        "ContactStatus": "Active",
        "Name": "Example Contact",
        "EmailAddress": "someone@example.com",
        "IsSupplier": "false",
        "IsCustomer": "false",
        "updatedDateUTC": "/Date(1637614988203+0000)/"
      }
    ]
  }
}

Create Invoice​

Create a new invoice | key: createInvoice

InputNotesExample
Additional Fields

Additional fields that might not be covered by the standard inputs. See https://developer.xero.com/documentation/api/accounting/invoices#post-invoices for additional fields.

Contact ID

Provide a string value for the Contact ID.

example-e40f-414a-8f95-ce6a63196e1a
Currency Code

The currency that invoice has been raised in.

USD
Date

Date invoice was issued. If the Date element is not specified it will default to the current date based on the timezone setting of the organization.

2024-10-01
Date String

Provide a string value for the date in which the invoice was created.

2021-05-27T00:00:00
Due Date

Date invoice is due.

2024-10-01
Due Date String

Provide a string value for the due date of the invoice.

2021-05-27T00:00:00
Invoice Number

Provide a string value for the unique invoice number.

INV01
Invoice Status

This value is required if you want to make payments on an invoice. Will default to 'DRAFT'

Invoice Type

Provide a string value for the type of the given invoice.

Line Amount Type

Provide a string value for the line Amount Types.

Line Items

Provide a JSON array, For each item, provide an object describing a valid line item. The 'ItemCode', 'Tracking', and 'DiscountRate' properties are optional. If you want to provide no line items, simply enter an empty Array.

Reference

Additional reference number (Accounts Receivable invoices only).

REF01
Sent To Contact

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 approve.

false
URL

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

https://example.com
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "Invoices": [
      {
        "InvoiceID": "example-7b92-4e10-84e8-efef27090697",
        "InvoiceNumber": "example01",
        "AmountDue": 800,
        "AmountPaid": 0,
        "SentToContact": false,
        "TotalDiscount": 200,
        "contact": {}
      }
    ]
  }
}

Create Item​

Create a new Item | key: createItem

InputNotesExample
Description

Provide a string value for the description.

This is an example description
Inventory Asset Account Code

Provide the account code for the inventory asset

200
Is Purchased

Provide a boolean value to determine if the item has been purchased yet.

false
Is Sold

Provide a boolean value to determine if the item has been sold yet.

false
Item Code

Provide a user-defined valid item code.

Untracked Item
Item Name

Provide a string value for the name of the item.

Example Name
Purchase Account Code

Provide the account code of the purchase.

200
Purchase Description

Provide a string value for the description.

This is an example description
Purchase Tax Type

Provide the tax type of the purchaser. Pick a value from the items listed here: https://developer.xero.com/documentation/api/accounting/types#tax-types

NONE
Purchase Unit Price

Provide the unit price of the purchase.

800
Sales Account Code

Provide the account code of the sale.

200
Sales Tax Type

Provide the tax type of the Seller. Provide a value from the items listed here: https://developer.xero.com/documentation/api/accounting/types#tax-types

NONE
Sales Unit Price

Provide the unit price of the sale, if the item has been sold.

50.69
Connection

The connection to use.

{
  "data": {
    "Items": [
      {
        "ItemID": "19b79d12-0ae1-496e-9649-cbd04b15c7c5",
        "Code": "ExampleThing",
        "Description": "I sell this untracked thing",
        "PurchaseDescription": "I buy this untracked thing",
        "UpdatedDateUTC": "/Date(1488338552390+0000)/",
        "PurchaseDetails": {
          "UnitPrice": 20,
          "AccountCode": "400",
          "TaxType": "NONE"
        },
        "SalesDetails": {
          "UnitPrice": 40,
          "AccountCode": "200",
          "TaxType": "OUTPUT2"
        },
        "Name": "An Example Untracked Item",
        "IsTrackedAsInventory": false,
        "IsSold": true,
        "IsPurchased": true
      }
    ]
  }
}

Delete Account​

Delete the information and metadata of an account by Id | key: deleteAccount

InputNotesExample
Account ID

Provide a string value for the Account ID

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "accounts": [
      {
        "AccountID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "200",
        "Name": "Example Account",
        "Status": "ARCHIVED",
        "Type": "REVENUE",
        "TaxType": "OUTPUT"
      }
    ]
  }
}

Delete Invoice​

Delete the information and metadata of an invoice by Id | key: deleteInvoice

InputNotesExample
Invoice ID

Provide a string value for the Invoice ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "Invoices": [
      {
        "InvoiceID": "example-7b92-4e10-84e8-efef27090697",
        "InvoiceNumber": "example01",
        "AmountDue": 800,
        "AmountPaid": 0,
        "SentToContact": false,
        "TotalDiscount": 200,
        "contact": {},
        "status": "Deleted"
      }
    ]
  }
}

Delete Item​

Delete the information and metadata of an item by Id | key: deleteItem

InputNotesExample
Item ID

Provide a string value for the Item ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

Get Account​

Get the information and metadata of an account by Id | key: getAccount

InputNotesExample
Account ID

Provide a string value for the Account ID

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "accounts": [
      {
        "AccountID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "200",
        "Name": "Example Account",
        "Status": "ARCHIVED",
        "Type": "REVENUE",
        "TaxType": "OUTPUT"
      }
    ]
  }
}

Get Attachment​

Get an attachment by ID | key: getAttachment

InputNotesExample
File Name

Provide a string value for the name of the file you want to attach to the object. The File Name will become the unique identifier of the file for update operations.

My Example File
Object ID

Provide a string value for the Id of the object.

example-e40f-414a-8f95-ce6a63196e1a
Object Type

Provide a string value for the type of object you would like to access.

Connection

The connection to use.

Get Contact​

Get the information and metadata of a contact by Id | key: getContact

InputNotesExample
Contact ID

Provide a string value for the Contact ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "contacts": [
      {
        "ContactID": "example-7b92-4e10-84e8-efef27090697",
        "ContactStatus": "Active",
        "Name": "Example Contact",
        "EmailAddress": "someone@example.com",
        "IsSupplier": "false",
        "IsCustomer": "false",
        "updatedDateUTC": "/Date(1637614988203+0000)/"
      }
    ]
  }
}

Get Contact History​

Get the information and metadata of a contact's history by Id | key: getContactHistory

InputNotesExample
Contact ID

Provide a string value for the Contact ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "HistoryRecords": [
      {
        "Changes": "Edited",
        "DateUTCString": "2021-11-23T18:38:24",
        "DateUTC": "/Date(1637692704697+0000)/",
        "User": "System Generated",
        "Details": "These are some example details"
      }
    ]
  }
}

Get Invoice​

Get the information and metadata of an invoice by Id | key: getInvoice

InputNotesExample
Invoice ID

Provide a string value for the Invoice ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "Invoices": [
      {
        "InvoiceID": "example-7b92-4e10-84e8-efef27090697",
        "InvoiceNumber": "example01",
        "AmountDue": 800,
        "AmountPaid": 0,
        "SentToContact": false,
        "TotalDiscount": 200,
        "contact": {}
      }
    ]
  }
}

Get Item​

Get the information and metadata of an item by Id | key: getItem

InputNotesExample
Item ID

Provide a string value for the Item ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "Items": [
      {
        "ItemID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "ExampleThing",
        "Description": "I sell this untracked thing",
        "PurchaseDescription": "I buy this untracked thing",
        "UpdatedDateUTC": "/Date(1488338552390+0000)/",
        "PurchaseDetails": {
          "UnitPrice": 20,
          "AccountCode": "400",
          "TaxType": "NONE"
        },
        "SalesDetails": {
          "UnitPrice": 40,
          "AccountCode": "200",
          "TaxType": "OUTPUT2"
        },
        "Name": "An Example Untracked Item",
        "IsTrackedAsInventory": false,
        "IsSold": true,
        "IsPurchased": true
      }
    ]
  }
}

Get Item History​

Get the information and metadata of an items's history by Id | key: getItemHistory

InputNotesExample
Item ID

Provide a string value for the Item ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "HistoryRecords": [
      {
        "Changes": "Updated",
        "DateUTCString": "2018-02-28T21:02:11",
        "DateUTC": "/Date(1519851731990+0000)/",
        "User": "Example",
        "Details": "Example Received through the Xero API from ABC Org"
      },
      {
        "Changes": "Created",
        "DateUTCString": "2018-02-28T21:01:29",
        "DateUTC": "/Date(1519851689297+0000)/",
        "User": "Example",
        "Details": "Example INV-0041 to ABC Furniture for 100.00."
      }
    ]
  }
}

Get Payment​

Get the information and metadata of a payment by id | key: getPayment

InputNotesExample
Payment ID

Provide a string value for the Id of the payment.

Connection

The connection to use.

{
  "data": {
    "Id": "example-d457-425f-8395-b3bdad78e517",
    "status": "OK",
    "ProviderName": "example-provider",
    "Payments": [
      {
        "PaymentID": "19b79d12-0ae1-496e-9649-cbd04b15c7c5",
        "Date": "/Date(1638144000000+0000)/",
        "BankAmount": 80,
        "CurrencyRate": 1,
        "PaymentType": "ACCRECPAYMENT",
        "Status": "AUTHORISED",
        "HasAccount": false
      }
    ]
  }
}

Get Payment History​

Get the information and metadata of a payment's history by Id | key: getPaymentHistory

InputNotesExample
Payment ID

Provide a string value for the Id of the payment.

Connection

The connection to use.

List Accounts​

List all accounts | key: listAccounts

InputNotesExample
Modified After

Only contacts created or modified since this timestamp will be returned.

yyyy-mm-ddThhss
Where

The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.

Name.Contains("Peter")
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "accounts": [
      {
        "AccountID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "200",
        "Name": "Example Account",
        "Status": "ARCHIVED",
        "Type": "REVENUE",
        "TaxType": "OUTPUT"
      },
      {
        "AccountID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "200",
        "Name": "Example Account",
        "Status": "ARCHIVED",
        "Type": "REVENUE",
        "TaxType": "OUTPUT"
      }
    ]
  }
}

List Connections​

List all connections | key: listConnections

InputNotesExample
Connection

The connection to use.

{
  "data": [
    {
      "id": "example-e40f-414a-8f95-ce6a63196e1a",
      "authEventId": "example-e40f-414a-8f95-ce6a63196e1a",
      "tenantId": "example-e40f-414a-8f95-ce6a63196e1a",
      "tenantType": "ORGANIZATION",
      "tenantName": "Example"
    }
  ]
}

List Contacts​

List all contacts | key: listContacts

InputNotesExample
Fetch All

Turn on to fetch all pages of results. This will ignore the page number input.

false
Modified After

Only contacts created or modified since this timestamp will be returned.

yyyy-mm-ddThhss
Page Number

Provide the page of the results you would like to return. Pagination will only be enabled if over 100 elements are returned by your request. It is not possible to specify the page size.

3
Where

The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.

Name.Contains("Peter")
Connection

The connection to use.

{
  "data": {
    "Id": "00000000-aaaa-bbbb-cccc-111111111111",
    "Status": "OK",
    "ProviderName": "ExampleProvider",
    "DateTimeUTC": "/Date(1650000000000)/",
    "pagination": {
      "page": 1,
      "pageSize": 1,
      "pageCount": 2,
      "itemCount": 2
    },
    "Contacts": [
      {
        "ContactID": "12345678-1234-5678-1234-567812345678",
        "ContactStatus": "ACTIVE",
        "Name": "John Doe",
        "Addresses": [
          {
            "AddressType": "POBOX"
          },
          {
            "AddressType": "STREET"
          }
        ],
        "Phones": [
          {
            "PhoneType": "DDI"
          },
          {
            "PhoneType": "DEFAULT"
          },
          {
            "PhoneType": "FAX"
          },
          {
            "PhoneType": "MOBILE"
          }
        ],
        "UpdatedDateUTC": "/Date(1650000123456+0000)/",
        "ContactGroups": [],
        "IsSupplier": false,
        "IsCustomer": true,
        "ContactPersons": [],
        "HasAttachments": false,
        "HasValidationErrors": false
      }
    ]
  }
}

List Invoices​

List all invoices | key: listInvoices

InputNotesExample
Fetch All

Turn on to fetch all pages of results. This will ignore the page number input.

false
Modified After

Only contacts created or modified since this timestamp will be returned.

yyyy-mm-ddThhss
Page Number

Provide the page of the results you would like to return. Pagination will only be enabled if over 100 elements are returned by your request. It is not possible to specify the page size.

3
Where

The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.

Name.Contains("Peter")
Connection

The connection to use.

{
  "data": {
    "Id": "c09006db-0bda-45c1-b23b-43fb3ba81951",
    "Status": "OK",
    "ProviderName": "ExampleProvider",
    "DateTimeUTC": "/Date(1750797099945)/",
    "Invoices": [
      {
        "Type": "ACCREC",
        "InvoiceID": "123e4567-e89b-12d3-a456-426614174000",
        "InvoiceNumber": "INV-1001",
        "Reference": "REF-2025",
        "Payments": [],
        "CreditNotes": [],
        "Prepayments": [],
        "Overpayments": [],
        "AmountDue": 150,
        "AmountPaid": 50,
        "AmountCredited": 0,
        "SentToContact": true,
        "CurrencyRate": 1.2,
        "IsDiscounted": true,
        "HasAttachments": false,
        "InvoiceAddresses": [],
        "HasErrors": false,
        "InvoicePaymentServices": [],
        "Contact": {
          "ContactID": "abcdef12-3456-7890-abcd-ef1234567890",
          "Name": "Example Contact",
          "Addresses": [],
          "Phones": [],
          "ContactGroups": [],
          "ContactPersons": [],
          "HasValidationErrors": false
        },
        "DateString": "2025-07-01T00:00:00",
        "Date": "/Date(1751328000000+0000)/",
        "DueDateString": "2025-07-15T00:00:00",
        "DueDate": "/Date(1752547200000+0000)/",
        "BrandingThemeID": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
        "Status": "AUTHORISED",
        "LineAmountTypes": "Exclusive",
        "LineItems": [],
        "SubTotal": 150,
        "TotalTax": 18,
        "Total": 168,
        "UpdatedDateUTC": "/Date(1751404400000+0000)/",
        "CurrencyCode": "USD"
      }
    ]
  }
}

List Items​

List all items | key: listItems

InputNotesExample
Modified After

Only contacts created or modified since this timestamp will be returned.

yyyy-mm-ddThhss
Where

The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.

Name.Contains("Peter")
Connection

The connection to use.

{
  "data": {
    "Id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "Status": "OK",
    "ProviderName": "ExampleProvider",
    "DateTimeUTC": "/Date(1750805000000)/",
    "Items": [
      {
        "ItemID": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
        "Code": "456",
        "Description": "Sample Item",
        "UpdatedDateUTC": "/Date(1750804000000+0000)/",
        "PurchaseDetails": {},
        "SalesDetails": {
          "UnitPrice": 10,
          "AccountCode": "300",
          "TaxType": "INPUT"
        },
        "Name": "Sample Item",
        "IsTrackedAsInventory": true,
        "IsSold": true,
        "IsPurchased": true
      }
    ]
  }
}

List Payments​

List all payments | key: listPayments

InputNotesExample
Fetch All

Turn on to fetch all pages of results. This will ignore the page number input.

false
Modified After

Only contacts created or modified since this timestamp will be returned.

yyyy-mm-ddThhss
Page Number

Provide the page of the results you would like to return. Pagination will only be enabled if over 100 elements are returned by your request. It is not possible to specify the page size.

3
Where

The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.

Name.Contains("Peter")
Connection

The connection to use.

{
  "data": {
    "Id": "12345678-aaaa-bbbb-cccc-1234567890ab",
    "Status": "OK",
    "ProviderName": "ExampleProvider",
    "DateTimeUTC": "/Date(1750801076272)/",
    "Payments": [
      {
        "PaymentID": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
        "Date": "/Date(1750723200000+0000)/",
        "BankAmount": 5,
        "Amount": 5,
        "CurrencyRate": 1,
        "PaymentType": "ACCRECPAYMENT",
        "Status": "AUTHORISED",
        "UpdatedDateUTC": "/Date(1750801011280+0000)/",
        "HasAccount": true,
        "IsReconciled": false,
        "Account": {
          "AccountID": "acc00001-aaaa-bbbb-cccc-ddddeeeeffff",
          "Code": "100"
        },
        "Invoice": {
          "Type": "ACCREC",
          "InvoiceID": "inv00001-aaaa-bbbb-cccc-ddddeeeeffff",
          "InvoiceNumber": "INV-1001",
          "Payments": [],
          "CreditNotes": [],
          "Prepayments": [],
          "Overpayments": [],
          "IsDiscounted": false,
          "InvoiceAddresses": [],
          "HasErrors": false,
          "InvoicePaymentServices": [],
          "Contact": {
            "ContactID": "cont0001-aaaa-bbbb-cccc-ddddeeeeffff",
            "Name": "Example Contact A",
            "Addresses": [],
            "Phones": [],
            "ContactGroups": [],
            "ContactPersons": [],
            "HasValidationErrors": false
          },
          "LineItems": [],
          "CurrencyCode": "USD"
        },
        "HasValidationErrors": false
      }
    ]
  }
}

Pay Invoice​

Create a new payment on an existing AP/AR invoice | key: payInvoice

InputNotesExample
Account ID

Provide a string value for the Account ID

example-e40f-414a-8f95-ce6a63196e1a
Date String

Provide a string value for the date in which the invoice was created.

2021-05-27T00:00:00
Invoice ID

Provide a string value for the Invoice ID.

example-e40f-414a-8f95-ce6a63196e1a
Payment Amount

Provide a string value for the amount of the payment. This value must be less than or equal to the outstanding amount owed on the invoice.

Connection

The connection to use.

Raw Request​

Send raw HTTP request to Xero | key: rawRequest

InputNotesExample
Connection

The connection to use.

Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Timeout

The maximum time that a client will await a response to its request

2000
URL

Input the path only (/Accounts), The base URL is already included (https://api.xero.com/api.xro/2.0). For example, to connect to https://api.xero.com/api.xro/2.0/Accounts, only /Accounts is entered in this field.

/Accounts
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

Reverse Payment​

Reverse a payment by Id | key: reversePayment

InputNotesExample
Payment ID

Provide a string value for the Id of the payment.

Connection

The connection to use.

{
  "data": {
    "Id": "example-d457-425f-8395-b3bdad78e517",
    "status": "OK",
    "ProviderName": "example-provider",
    "Payments": [
      {
        "PaymentID": "19b79d12-0ae1-496e-9649-cbd04b15c7c5",
        "Date": "/Date(1638144000000+0000)/",
        "BankAmount": 80,
        "CurrencyRate": 1,
        "PaymentType": "ACCRECPAYMENT",
        "Status": "DELETED",
        "HasAccount": false
      }
    ]
  }
}

Send Invoice​

Send an existing accounts receivable invoice through email | key: sendInvoice

InputNotesExample
Invoice ID

Provide a string value for the Invoice ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

You can use the Send Invoice action to trigger the email of a sales invoice out of Xero. The invoice must be of type ACCREC and a valid status for sending (SUBMITTED, AUTHORIZED or PAID). The email will be sent to the primary email address of the contact on the invoice and any additional contact persons that have IncludeInEmails flag set to true. The sender will be the user who authorized the app connection.

Update Account​

Update the information and metadata of an existing account by Id | key: updateAccount

InputNotesExample
Account Code

Provide a string value for the account code. This value is a customer defined alpha numeric account code.

200
Account ID

Provide a string value for the Account ID

example-e40f-414a-8f95-ce6a63196e1a
Account Name

Provide a string value for the name of the account.

Example Account
Account Type

Provide a string value for the type of the given account. You can choose from the list of provided values here: https://developer.xero.com/documentation/api/accounting/types#accounts

BANK
Description

Provide a string value for the description.

This is an example description
Enable Payments To Account

This flag will enable payments to be made to the given account.

false
Optional Values

For each item, provide a key and value to be used in the request body.

exampleValue
Purchase Tax Type

Provide the tax type of the purchaser. Pick a value from the items listed here: https://developer.xero.com/documentation/api/accounting/types#tax-types

NONE
Show In Expense Claims

This value will determine if your account will show in expense claims. This field is required for certain accounts.

false
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "accounts": [
      {
        "AccountID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "200",
        "Name": "Example Account",
        "Status": "ARCHIVED",
        "Type": "REVENUE",
        "TaxType": "OUTPUT"
      }
    ]
  }
}

Update Contact​

Update the information and metadata of a contact by Id | key: updateContact

InputNotesExample
Accounts Payable Tax Type

Provide a string value for the tax type of accounts payable for the account. For more information on what value to provide, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/types#tax-types

OUTPUT
Accounts Receivable Tax Type

Provide a string value for the tax type of accounts receivable for the account. For more information on what value to provide, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/types#tax-types

OUTPUT
Additional Fields

Additional fields that might not be covered by the standard inputs. See https://developer.xero.com/documentation/api/accounting/contacts#post-contacts for additional fields.

Address

Provide a string value that represents a valid address.

4 Privet Drive
Address Type

Provide a string value for the address type.

POBOX
Bank Account Details

Provide a string value for the details of the contacts bank account. Depending on the type of account, providing a value for this field could cause your request to fail. For more information on the expected shape of the Account object, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/accounts/#get-accounts

01-0123-example-00
City

Provide a string value for the city of the address.

San Francisco
Contact ID

Provide a string value for the Contact ID.

example-e40f-414a-8f95-ce6a63196e1a
Contact Name

Provide a string value for the name of the contact.

Acme Inc.
Contact Number

Provide a string value for the unique number identifier of the contact.

IDexample01
Contact Status

Provide a string value for the status of the contact.

Country

Provide a string value for the country of the address.

United States
Default Currency

Provide a valid type of currency.

USD
Email Address

Provide a valid email address for the contact.

someone@example.com
First Name

Provide a string value for the first name of the contact.

John
Last Name

Provide a string value for the last name of the contact.

Doe
Postal Code

Provide a valid postal code.

48423
Region

Provide a string value for the region of the address.

California
Tax Number

Provide a string value for the Tax number. For more information on what value to provide, refer to the Xero docs: https://developer.xero.com/documentation/api/accounting/types#tax-types

12-345-678
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "contacts": [
      {
        "ContactID": "example-7b92-4e10-84e8-efef27090697",
        "ContactStatus": "Active",
        "Name": "Example Contact",
        "EmailAddress": "someone@example.com",
        "IsSupplier": "false",
        "IsCustomer": "false",
        "updatedDateUTC": "/Date(1637614988203+0000)/"
      }
    ]
  }
}

Update Item​

Update the information and metadata of an item by Id | key: updateItem

InputNotesExample
Description

Provide a string value for the description.

This is an example description
Optional Values

For each item, provide a key and value to be used in the request body.

exampleValue
Inventory Asset Account Code

Provide the account code for the inventory asset

200
Is Purchased

Provide a boolean value to determine if the item has been purchased yet.

false
Is Sold

Provide a boolean value to determine if the item has been sold yet.

false
Item Code

Provide a user-defined valid item code.

Untracked Item
Item ID

Provide a string value for the Item ID.

example-e40f-414a-8f95-ce6a63196e1a
Item Name

Provide a string value for the name of the item.

Example Name
Purchase Account Code

Provide the account code of the purchase.

200
Purchase Description

Provide a string value for the description.

This is an example description
Purchase Tax Type

Provide the tax type of the purchaser. Pick a value from the items listed here: https://developer.xero.com/documentation/api/accounting/types#tax-types

NONE
Purchase Unit Price

Provide the unit price of the purchase.

800
Sales Account Code

Provide the account code of the sale.

200
Sales Tax Type

Provide the tax type of the Seller. Provide a value from the items listed here: https://developer.xero.com/documentation/api/accounting/types#tax-types

NONE
Sales Unit Price

Provide the unit price of the sale, if the item has been sold.

50.69
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "Items": [
      {
        "ItemID": "example-7b92-4e10-84e8-efef27090697",
        "Code": "ExampleThing",
        "Description": "I sell this untracked thing",
        "PurchaseDescription": "I buy this untracked thing",
        "UpdatedDateUTC": "/Date(1488338552390+0000)/",
        "PurchaseDetails": {
          "UnitPrice": 20,
          "AccountCode": "400",
          "TaxType": "NONE"
        },
        "SalesDetails": {
          "UnitPrice": 40,
          "AccountCode": "200",
          "TaxType": "OUTPUT2"
        },
        "Name": "An Example Untracked Item",
        "IsTrackedAsInventory": false,
        "IsSold": true,
        "IsPurchased": true
      }
    ]
  }
}

Void Invoice​

Void an existing approved invoice that has no payments applied to it. | key: voidInvoice

InputNotesExample
Invoice ID

Provide a string value for the Invoice ID.

example-e40f-414a-8f95-ce6a63196e1a
Connection

The connection to use.

{
  "data": {
    "ID": "example-7b92-4e10-84e8-efef27090697",
    "status": "OK",
    "ProviderName": "MyExampleProvider",
    "DateTimeUTC": "/Date(1637616068092)/",
    "Invoices": [
      {
        "InvoiceID": "example-7b92-4e10-84e8-efef27090697",
        "InvoiceNumber": "example01",
        "AmountDue": 800,
        "AmountPaid": 0,
        "SentToContact": false,
        "TotalDiscount": 200,
        "contact": {},
        "Status": "VOIDED"
      }
    ]
  }
}

Changelog​

2025-09-11​

Added improved error handling for invalid webhook signatures to enhance security

2025-07-03​

Added data sources and inline data sources for improved integration with Xero accounting platform