Skip to main content

Xero Component

Xero

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.

InputDefaultNotesExample
Authorize URL
string
/ Required
Hidden Field
authorizeUrl
https://login.xero.com/identity/connect/authorize
The OAuth 2.0 Authorization URL for Xero
 
Client ID
string
/ Required
clientId
Provide the Client Id you received from the Xero Developer Console.
 
Client Secret
password
/ Required
clientSecret
Provide the Client Secret you generated from the Xero Developer Console.
 
Scopes
string
/ Required
scopes
offline_access accounting.settings accounting.contacts accounting.attachments
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
string
/ Required
tenant
The name of the tenant you are requesting access to.
Acme Inc.
Token URL
string
/ Required
Hidden Field
tokenUrl
https://identity.xero.com/connect/token
The OAuth 2.0 Token URL for Xero
 

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 in Prismatic.

For more information, check the documentation here.

InputDefaultNotesExample
Client ID
string
/ Required
clientId
Provide the Client Id you received from the Xero Developer Console.
 
Client Secret
password
/ Required
clientSecret
Provide the Client Secret you generated from the Xero Developer Console.
 
Scopes
string
/ Required
scopes
accounting.settings accounting.contacts accounting.attachments
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
string
/ Required
Hidden Field
tokenUrl
https://identity.xero.com/connect/token
The OAuth 2.0 Token URL for Xero
 

Triggers​

Webhook​

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

InputNotesExample
Webhook Key
string
webhookKey
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.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

InputNotesExample
Item ID
string
/ Required
itemId
Provide a string value for the Item ID.
example-e40f-414a-8f95-ce6a63196e1a
Notes
string
notes
Provide a string value for notes to add to an object.
These are example notes.
Connection
connection
/ Required
xeroConnection
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
string
/ Required
invoiceId
Provide a string value for the Invoice ID.
example-e40f-414a-8f95-ce6a63196e1a
Notes
string
notes
Provide a string value for notes to add to an object.
These are example notes.
Connection
connection
/ Required
xeroConnection
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
string
/ Required
accountId
Provide a string value for the Account ID
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
contactId
Provide a string value for the Contact ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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

InputDefaultNotesExample
Account Code
string
/ Required
accountCode
Provide a string value for the account code. This value is a customer defined alpha numeric account code.
200
Account Name
string
/ Required
accountName
Provide a string value for the name of the account.
Example Account
Account Type
string
/ Required
accountType
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
string
bankAccountNumber
This value is required if you are creating an account of type 'BANK'.
121-121-1234567
Optional Values
string
Key Value List
fieldValues
For each item, provide a key and value to be used in the request body.
exampleValue
Show In Expense Claims
boolean
showInExpenseClaims
false
This value will determine if your account will show in expense claims. This field is required for certain accounts.
 
Connection
connection
/ Required
xeroConnection
 
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
string
/ Required
contentType
MIME type of the file you want to upload
image/png
File Data
data
/ Required
file
Provide a value that represents the data of the file you want to upload
 
File Name
string
/ Required
fileName
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
string
/ Required
objectId
Provide a string value for the Id of the object.
example-e40f-414a-8f95-ce6a63196e1a
Object Type
string
/ Required
objectType
Provide a string value for the type of object you would like to access.
 
Connection
connection
/ Required
xeroConnection
The connection to use.
 

Create Contact​

Create a new contact | key: createContact

InputNotesExample
Accounts Payable Tax Type
string
accountsPayableTaxType
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
string
accountsReceivableTaxType
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
code
additionalFields
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
string
address
Provide a string value that represents a valid address.
4 Privet Drive
Address Type
string
addressType
Provide a string value for the address type.
POBOX
Bank Account Details
string
bankAccountDetails
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
string
city
Provide a string value for the city of the address.
San Francisco
Contact Name
string
/ Required
contactName
Provide a string value for the name of the contact.
Acme Inc.
Contact Status
string
contactStatus
Provide a string value for the status of the contact.
 
Country
string
country
Provide a string value for the country of the address.
United States
Default Currency
string
defaultCurrency
Provide a valid type of currency.
USD
Email Address
string
email
Provide a valid email address for the contact.
someone@example.com
First Name
string
firstName
Provide a string value for the first name of the contact.
John
Last Name
string
lastName
Provide a string value for the last name of the contact.
Doe
Postal Code
string
postalCode
Provide a valid postal code.
48423
Region
string
region
Provide a string value for the region of the address.
California
Tax Number
string
taxNumber
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
connection
/ Required
xeroConnection
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

InputDefaultNotesExample
Additional Fields
code
additionalFields
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
string
/ Required
contactId
Provide a string value for the Contact ID.
example-e40f-414a-8f95-ce6a63196e1a
Currency Code
string
currencyCode
The currency that invoice has been raised in.
USD
Date
string
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
string
dateString
Provide a string value for the date in which the invoice was created.
2021-05-27T00:00:00
Due Date
string
dueDate
Date invoice is due.
2024-10-01
Due Date String
string
dueDateString
Provide a string value for the due date of the invoice.
2021-05-27T00:00:00
Invoice Number
string
invoiceNumber
Provide a string value for the unique invoice number.
INV01
Invoice Status
string
invoiceStatus
This value is required if you want to make payments on an invoice. Will default to 'DRAFT'
 
Invoice Type
string
/ Required
invoiceType
Provide a string value for the type of the given invoice.
 
Line Amount Type
string
/ Required
lineAmountTypes
Provide a string value for the line Amount Types.
 
Line Items
code
lineItems
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
string
reference
Additional reference number (Accounts Receivable invoices only).
REF01
Sent To Contact
boolean
sentToContact
false
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.
 
URL
string
url
URL link to a source document – shown as "Go to [appName]" in the Xero app.
https://example.com
Connection
connection
/ Required
xeroConnection
 
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

InputDefaultNotesExample
Description
string
description
Provide a string value for the description.
This is an example description
Inventory Asset Account Code
string
inventoryAssetAccountCode
Provide the account code for the inventory asset
200
Is Purchased
boolean
isPurchased
false
Provide a boolean value to determine if the item has been purchased yet.
 
Is Sold
boolean
isSold
false
Provide a boolean value to determine if the item has been sold yet.
 
Item Code
string
/ Required
itemCode
Provide a user-defined valid item code.
Untracked Item
Item Name
string
itemName
Provide a string value for the name of the item.
Example Name
Purchase Account Code
string
purchaseAccountCode
Provide the account code of the purchase.
200
Purchase Description
string
purchaseDescription
Provide a string value for the description.
This is an example description
Purchase Tax Type
string
purchaseTaxType
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
string
purchaseUnitPrice
Provide the unit price of the purchase.
800
Sales Account Code
string
salesAccountCode
Provide the account code of the sale.
200
Sales Tax Type
string
salesTaxType
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
string
salesUnitPrice
Provide the unit price of the sale, if the item has been sold.
50.69
Connection
connection
/ Required
xeroConnection
 
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
string
/ Required
accountId
Provide a string value for the Account ID
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
invoiceId
Provide a string value for the Invoice ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
itemId
Provide a string value for the Item ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
The connection to use.
 

Get Account​

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

InputNotesExample
Account ID
string
/ Required
accountId
Provide a string value for the Account ID
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
fileName
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
string
/ Required
objectId
Provide a string value for the Id of the object.
example-e40f-414a-8f95-ce6a63196e1a
Object Type
string
/ Required
objectType
Provide a string value for the type of object you would like to access.
 
Connection
connection
/ Required
xeroConnection
The connection to use.
 

Get Contact​

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

InputNotesExample
Contact ID
string
/ Required
contactId
Provide a string value for the Contact ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
contactId
Provide a string value for the Contact ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
invoiceId
Provide a string value for the Invoice ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
itemId
Provide a string value for the Item ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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
string
/ Required
itemId
Provide a string value for the Item ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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

InputNotes
Payment ID
string
/ Required
paymentId
Provide a string value for the Id of the payment.
Connection
connection
/ Required
xeroConnection
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

InputNotes
Payment ID
string
/ Required
paymentId
Provide a string value for the Id of the payment.
Connection
connection
/ Required
xeroConnection
The connection to use.

List Accounts​

List all accounts | key: listAccounts

InputNotesExample
Modified After
string
modifiedAfter
Only contacts created or modified since this timestamp will be returned.
yyyy-mm-ddThhss
Where
string
where
The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.
Name.Contains("Peter")
Connection
connection
/ Required
xeroConnection
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

InputNotes
Connection
connection
/ Required
xeroConnection
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
Modified After
string
modifiedAfter
Only contacts created or modified since this timestamp will be returned.
yyyy-mm-ddThhss
Page Number
string
page
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
string
where
The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.
Name.Contains("Peter")
Connection
connection
/ Required
xeroConnection
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)/"
      }
    ]
  }
}

List Invoices​

List all invoices | key: listInvoices

InputNotesExample
Modified After
string
modifiedAfter
Only contacts created or modified since this timestamp will be returned.
yyyy-mm-ddThhss
Page Number
string
page
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
string
where
The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.
Name.Contains("Peter")
Connection
connection
/ Required
xeroConnection
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": {}
      }
    ]
  }
}

List Items​

List all items | key: listItems

InputNotesExample
Modified After
string
modifiedAfter
Only contacts created or modified since this timestamp will be returned.
yyyy-mm-ddThhss
Page Number
string
page
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
string
where
The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.
Name.Contains("Peter")
Connection
connection
/ Required
xeroConnection
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
      }
    ]
  }
}

List Payments​

List all payments | key: listPayments

InputNotesExample
Modified After
string
modifiedAfter
Only contacts created or modified since this timestamp will be returned.
yyyy-mm-ddThhss
Page Number
string
page
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
string
where
The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.
Name.Contains("Peter")
Connection
connection
/ Required
xeroConnection
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
      }
    ]
  }
}

Pay Invoice​

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

InputNotesExample
Account ID
string
/ Required
accountId
Provide a string value for the Account ID
example-e40f-414a-8f95-ce6a63196e1a
Date String
string
dateString
Provide a string value for the date in which the invoice was created.
2021-05-27T00:00:00
Invoice ID
string
/ Required
invoiceId
Provide a string value for the Invoice ID.
example-e40f-414a-8f95-ce6a63196e1a
Payment Amount
string
/ Required
paymentAmount
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
connection
/ Required
xeroConnection
The connection to use.
 

Raw Request​

Send raw HTTP request to Xero | key: rawRequest

InputDefaultNotesExample
Connection
connection
/ Required
connection
 
The connection to use.
 
Data
string
data
The HTTP body payload to send to the URL.
{"exampleKey": "Example Data"}
Debug Request
boolean
debugRequest
false
Enabling this flag will log out the current request.
 
File Data
string
Key Value List
fileData
File Data to be sent as a multipart form upload.
[{key: "example.txt", value: "My File Contents"}]
File Data File Names
string
Key Value List
fileDataFileNames
File names to apply to the file data inputs. Keys must match the file data keys above.
 
Form Data
string
Key Value List
formData
The Form Data to be sent as a multipart form upload.
[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header
string
Key Value List
headers
A list of headers to send with the request.
User-Agent: curl/7.64.1
Max Retry Count
string
maxRetries
0
The maximum number of retries to attempt.
 
Method
string
/ Required
method
The HTTP method to use.
 
Query Parameter
string
Key Value List
queryParams
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
string
/ Required
responseType
json
The type of data you expect in the response. You can request json, text, or binary data.
 
Retry On All Errors
boolean
retryAllErrors
false
If true, retries on all erroneous responses regardless of type.
 
Retry Delay (ms)
string
retryDelayMS
0
The delay in milliseconds between retries.
 
Timeout
string
timeout
The maximum time that a client will await a response to its request
2000
URL
string
/ Required
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
boolean
useExponentialBackoff
false
Specifies whether to use a pre-defined exponential backoff strategy for retries.
 

Reverse Payment​

Reverse a payment by Id | key: reversePayment

InputNotes
Payment ID
string
/ Required
paymentId
Provide a string value for the Id of the payment.
Connection
connection
/ Required
xeroConnection
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
string
/ Required
invoiceId
Provide a string value for the Invoice ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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

InputDefaultNotesExample
Account Code
string
accountCode
Provide a string value for the account code. This value is a customer defined alpha numeric account code.
200
Account ID
string
/ Required
accountId
Provide a string value for the Account ID
example-e40f-414a-8f95-ce6a63196e1a
Account Name
string
accountName
Provide a string value for the name of the account.
Example Account
Account Type
string
accountType
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
string
description
Provide a string value for the description.
This is an example description
Enable Payments To Account
boolean
enablePaymentsToAccount
false
This flag will enable payments to be made to the given account.
 
Optional Values
string
Key Value List
fieldValues
For each item, provide a key and value to be used in the request body.
exampleValue
Purchase Tax Type
string
purchaseTaxType
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
boolean
showInExpenseClaims
false
This value will determine if your account will show in expense claims. This field is required for certain accounts.
 
Connection
connection
/ Required
xeroConnection
 
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
string
accountsPayableTaxType
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
string
accountsReceivableTaxType
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
code
additionalFields
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
string
address
Provide a string value that represents a valid address.
4 Privet Drive
Address Type
string
addressType
Provide a string value for the address type.
POBOX
Bank Account Details
string
bankAccountDetails
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
string
city
Provide a string value for the city of the address.
San Francisco
Contact ID
string
/ Required
contactId
Provide a string value for the Contact ID.
example-e40f-414a-8f95-ce6a63196e1a
Contact Name
string
contactName
Provide a string value for the name of the contact.
Acme Inc.
Contact Number
string
contactNumber
Provide a string value for the unique number identifier of the contact.
IDexample01
Contact Status
string
contactStatus
Provide a string value for the status of the contact.
 
Country
string
country
Provide a string value for the country of the address.
United States
Default Currency
string
defaultCurrency
Provide a valid type of currency.
USD
Email Address
string
email
Provide a valid email address for the contact.
someone@example.com
First Name
string
firstName
Provide a string value for the first name of the contact.
John
Last Name
string
lastName
Provide a string value for the last name of the contact.
Doe
Postal Code
string
postalCode
Provide a valid postal code.
48423
Region
string
region
Provide a string value for the region of the address.
California
Tax Number
string
taxNumber
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
connection
/ Required
xeroConnection
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

InputDefaultNotesExample
Description
string
description
Provide a string value for the description.
This is an example description
Optional Values
string
Key Value List
fieldValues
For each item, provide a key and value to be used in the request body.
exampleValue
Inventory Asset Account Code
string
inventoryAssetAccountCode
Provide the account code for the inventory asset
200
Is Purchased
boolean
isPurchased
false
Provide a boolean value to determine if the item has been purchased yet.
 
Is Sold
boolean
isSold
false
Provide a boolean value to determine if the item has been sold yet.
 
Item Code
string
/ Required
itemCode
Provide a user-defined valid item code.
Untracked Item
Item ID
string
/ Required
itemId
Provide a string value for the Item ID.
example-e40f-414a-8f95-ce6a63196e1a
Item Name
string
itemName
Provide a string value for the name of the item.
Example Name
Purchase Account Code
string
purchaseAccountCode
Provide the account code of the purchase.
200
Purchase Description
string
purchaseDescription
Provide a string value for the description.
This is an example description
Purchase Tax Type
string
purchaseTaxType
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
string
purchaseUnitPrice
Provide the unit price of the purchase.
800
Sales Account Code
string
salesAccountCode
Provide the account code of the sale.
200
Sales Tax Type
string
salesTaxType
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
string
salesUnitPrice
Provide the unit price of the sale, if the item has been sold.
50.69
Connection
connection
/ Required
xeroConnection
 
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
string
/ Required
invoiceId
Provide a string value for the Invoice ID.
example-e40f-414a-8f95-ce6a63196e1a
Connection
connection
/ Required
xeroConnection
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"
      }
    ]
  }
}