Skip to main content

Xero Component

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

Component key: xero

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

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"
}
]
}
}