Troubleshooting Xero Exports and Common Errors

Overview

Data sent from your Astute portal to your Xero organisation will need to meet particular requirements in order to send successfully. You may come across the below common warnings or errors when exporting data from Astute to Xero. Please click on an error for more information.

• Future Dated Payroll/Invoice
• GL Code errors prior to export (Validation Errors)
• Workplace State Missing
• Invalid Account Code (Payroll)
• Invalid Account Code (Invoicing)
• Credit Note Warning
• Client Error Response/Error 403 (Forbidden)
• The contact with the specified contact details has been archived

Future Dated Payroll/Invoice

The pay runs, invoices or credit notes that appear for export in your Xero Integration screen will depend on the Report Settings that you have configured. To check these settings, click the Report Settings tab and update the dropdown fields as required.

Please note that if the Show tab is set to 'All outstanding up to today', no future dated pay runs or invoices will appear. 

GL Code errors prior to export (Validation Errors)

The Astute system will validate the data that is included in your filter criteria prior to you exporting. A list of Validation Errors displays at the bottom of the Xero Integration screen, and will need to be amended prior to completing your export to prevent further issues.

Please note that Validation Errors will not prevent you from exporting data to Xero. They are listed as a reference for you to amend any incorrect or invalid data prior to export. 

If they are not corrected and your data is exported, you will receive an error message at the top of the screen.

Example Invoicing Error Messages

Validation Error Format: 'Invoice #XX includes invoice items with invalid GL account codes'.

Error after exporting: No valid GL Code found for Pay Category [name of pay item] or No valid Account Code found using the GL Accounts groups. ([Name of Group]).

Example Payroll Error Messages

Error after exporting: Deduction [Name of Item] has a missing [code type] and it is not set in the [name of group] GL Group. (As set in job [name of Job] for employee [name of employee]).

Solution

To correct the error, you will need to add the relevant GL codes in Config > Payroll > GL Groups.

Please also ensure that the relevant GL Group has been allocated to the employee or job (whichever option is being used).

Workplace State Missing

A workplace state is required for a Payroll Journal, regardless of the Payroll Tax liability status. If a workplace state has not been set for a workplace that is included in a pay run, you will receive an error.

This error will mention the first employee impacted, but can also include other employees. All missing workplace states will need to be amended before you can successfully send the journal.

Example error message

Format: Workplace State, used for Payroll Tax calculation, is missing for one or more jobs - including [name of employee] at [workplace].

Solution

Run the Payroll Tax (Historical Data) report for the month that relates to the pay runs you are exporting. 

Sort the report by Workplace State, then click the employee name and navigate to the Workplace Details tab to update their information. At a minimum, you will need to record the Country, State and Postcode in the Workplace Address section. 

Invalid Account Code (Payroll)

Data that is sent to Xero may be rejected if the submission contains an invalid account code. This error can lie in either your Astute portal or your Xero organisation. 

The error will specify the account code and the pay run number.

Example Error Message

Format: 1 Payrun has failed when exported to [Name of Xero organisation].

Account code '[XXX]' is not a valid code for this document. (Payrun: [pay run number])

Solution

You will need to determine first where the code has been missed or entered incorrectly: Astute or Xero.

If it is missing or incorrect in Astute, you'll need to update the GL code in Config > Payroll > GL Groups, by selecting the relevant GL Group and updating the code as required.

If the error lies in Xero, you will need to amend the GL Code setup in Xero. Generally, the issue is an incorrect Tax Type or Account Type. For example, all Payroll GL codes must be set with a Tax Type of 'BAS Excluded', and therefore can't be set with 'GST on Expense' for expense reimbursements. 

Once you have located and amended the issue, you can re-run the Payroll Export. You won't need to update the pay run, as the Payroll Journal is built each time the export is run. 

Invalid Account Code (Invoicing)

Data that is sent to Xero may be rejected if the submission contains an invalid account code. This error can lie in either your Astute portal or your Xero organisation. 

The error will specify the account code and the invoice number.

Example Error Message

Format: There were some errors generating the transactions to export. The export has been aborted.

Invalid account code for an invoice item in Invoice #XX

Solution

You will need to update the GL code in either Astute or Xero, depending on where you determine the error occurs. 

If this is in your Astute portal, you will need to update the GL code in Config > Payroll > GL Groups, by selecting the relevant GL Group and updating the code as required.

You will also need to update the related invoice. Once you've navigated to the invoice, click the Edit button in the top right, check that the GL Code has updated accordingly, then click Save. No other information in the invoice needs to be changed. 

Once you've amended the issue and saved any changes, you can re-run the Invoice export.

Credit Note Warning

The Credit Note export will contain any credit notes that are generated by writing off invoices. Depending on whether the original invoice is exported to Xero, you may receive a warning message when you perform the Credit Note export. 

The warning message (below) indicates that the original invoice is not in Xero and, as a result, the Credit Note cannot be matched to it. 

Example Warning Message

Format: X Credit Note(s) has successfully been created in [Name of Xero organisation].

[warning] Unable to allocate credit note, please link them manually in XERO. 

Solution

This error will not prevent the Credit Note data from exporting to Xero, however, it will sit in Xero in an 'Awaiting Payment' status. You will need to manually allocate the Credit Note to the relevant invoice in Xero.

If the invoice is exported to Xero prior to it being written off in Astute, then the exported Credit Note will match to that invoice in Xero and will update to Paid. You won't receive a warning message in this case.

Client Error Response/Error 403 (Forbidden)

The 403 (Forbidden) error means that there is a connection error between Astute and Xero. The error message you see will vary slightly depending on whether you are requesting a Payroll export or an Invoice export.

You may see a different error number, but if your error is structured as per the below example, it is likely to be caused by a connection error. 

Example Error Messages:

For payroll, the error message format is Client error response [status code] 403 [reason phrase] Forbidden [url] https://api.xero.com/api.xro.2.0/ManualJournals?unitdp=4@summarizeErrors=false

For invoicing, the error message format is Client error response [status code] 403 [reason phrase] Forbidden [url] https://api.xero.com/api.xro.2.0/Invoices?unitdp=4@summarizeErrors=false

Solution

You will need to reauthorise the app in Astute to re-establish the connection with Xero. 

1. Go to Config > Company Management > select your entity > Integrations. 
2. Next to 'Link to Xero', click Remove, then OK on the confirmation popup screen.
3. Click Authorize to link Astute to your Xero App again.
4. In the authorisation screen, select the organisation from the dropdown list that you want to connect to, then click Allow Access. You won't need to re-enter any other credentials. 

The contact with the specified contact details has been archived

This invoicing error means the Xero contact linked to the invoice has been archived. If you're merging or archiving Contacts in Xero, it's important that the one linked to the Customer profile in Astute is the one that is left active. 

Example Error Message:

'The contact with the specified contact details has been archived. The contact must be un-archived before creating new invoices or credit notes.'

Solution

You need to find the contact that has been archived in Xero and un-archive it, so Astute can link to it. 

1. Click on the hyperlinked invoice/credit note number in the error message in Astute, or find it via the Invoicing tab to determine which Customer profile it relates to. 
2. Click on the Customer name from the Invoicing section or go to Users > Customers > select that customer > Integration.
3. Copy the 'XERO Contact ID' from the Astute customer profile. Also, take note of the Customer ID (BID) in the URL. 
   
   
4. Go to your Xero organisation and click into any Contact, then Paste the 'Xero Contact ID' from Astute into the URL.
5. Confirm that this is the correct Contact by checking the 'Contact Code' on the right-hand side. This should match the BID from the Customer profile in Astute.
6.  Restore the Contact in Xero.
7. Go back to the Xero Integration Report in Astute and export the invoices again.