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.
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 organisation 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
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.
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.
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.
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 in Prismatic.
For more information, check the documentation here.
Triggers
Webhook
Receive and validate webhook requests from Xero for webhooks you configure. | 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 HTTP request to Xero | 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"
}
]
}
}