Xero Component
Manage invoices, items, accounts, payments and more objects from your Xero account.
Component key: xeroDescription
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 Prismatic 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.
Triggers
Webhook
Trigger for handling webhook requests from your Xero tenant | key: webhook
Output Example Payload
{
"response": {
"contentType": "application/json; charset=UTF-8",
"statusCode": 200
},
"payload": {
"headers": {
"Content-Type": "application/json; charset=UTF-8",
"Host": "hooks.example.prismatic.io",
"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.prismatic.io/trigger/EXAMPLEGbG93Q29uZmlnOmRlNmNmNDMyLTliNWMtN0005NDMxLTRmYzA4ZjViODgxOA=="
},
"webhookApiKeys": {
"Flow 1": ["abc-123"]
},
"customer": {
"externalId": "customer-example-external-id",
"name": "John Doe"
}
}
}
Actions
Add Note To Item
Add a note to an item's history by Id | key: addNoteToItem
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
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.
Output Example Payload
{
"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
Create Contact
Create a new contact | key: createContact
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Get Account
Get the information and metadata of an account by Id | key: getAccount
Output Example Payload
{
"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
Get Contact
Get the information and metadata of a contact by Id | key: getContact
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
List Accounts
List all accounts | key: listAccounts
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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)/"
}
]
}
}
List Invoices
List all invoices | key: listInvoices
Output Example Payload
{
"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": {}
}
]
}
}
List Items
List all items | key: listItems
Output Example Payload
{
"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
}
]
}
}
List Payments
List all payments | key: listPayments
Output Example Payload
{
"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
}
]
}
}
Pay Invoice
Create a new payment on an existing AP/AR invoice | key: payInvoice
Raw Request
Send Raw Request to Asana | key: rawRequest
Reverse Payment
Reverse a payment by Id | key: reversePayment
Output Example Payload
{
"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
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, AUTHORISED 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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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
Output Example Payload
{
"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"
}
]
}
}