In this section
Use this guide to understand how to configure, check, and troubleshoot Xero data in Jira.
Best practices — recommended setup guidance for reliable invoice matching.
Troubleshooting — common questions, checks, and actions when Xero data does not appear as expected.
Frequently asked questions — quick answers to common setup and usage questions.
Support information — details to collect before asking for help.
💡 Tip: Start with the fields customers need most. Check the results in the Xero activity tab first, then add more filters only if they help customers find invoices faster.
Map Xero Invoice Number first. This is the most direct way to find one specific invoice, for example INV-0029.
Use consistent Jira field names. Match the names used in this guide, such as Invoice Status, Amount Due, Total, Invoice Date, Due Date, Customer Name, Currency Code, Tracking Region, and Tracking Project.
Choose the right Jira field type. Use Short text for invoice numbers, references, names, and currency codes; Date picker for invoice and due dates; and Number field for amount values where possible.
Enter values exactly as they appear in Xero. Small differences in invoice numbers, status values, dates, customer names, or currency codes can stop matching invoices from appearing.
Use Select lists for fixed values. For fields such as Invoice Status, Currency Code, Tracking Region, or Tracking Project, a Select list can reduce typing mistakes.
Refresh after changing Jira field values. If a user updates a mapped Jira field, they should click Refresh in the Xero activity tab to load the latest matching data.
Keep the Xero connection secure. Treat the Client Secret like a password and only share it with trusted administrators.
⚠️ Start here: If Xero data does not appear in Jira, use these questions to check the most common causes first.
Question | What to check | What to do |
|---|---|---|
I see “Not connected to Xero”. What do I do? | The Xero connection may not be authenticated, or the connection may have expired. | Go to Jira Admin Settings → Apps → Xero Settings → Xero Connection, confirm the credentials, and authenticate with Xero again. |
I see “No mappings configured”. What should I check? | The app does not yet know which Jira fields should match which Xero fields. | Open the Field Mapping tab and add mappings for the fields you want to use, starting with Xero Invoice Number. |
I created field mapping, but invoices are still not fetching. What should I check? | The Jira custom field used on the issue must be the same field that was selected in Field Mapping. A field with a similar name will not work if it is a different Jira custom field. | Check the mapping and the Jira issue field side by side. For example, if Xero Invoice Number is mapped to Invoice Number, enter |
I entered an invoice number, but no invoice appears. Why? | The Jira value may not exactly match the invoice number in the connected Xero organisation. | Check that the Jira field value matches the Xero invoice number exactly, for example |
I made an Invoice Status field, and the name is correct, but it is not fetching values. What could be wrong? | The field name may be correct, but the Jira field type may not match the kind of value the app needs to compare with Xero. | Use a Short text field for Invoice Status, or a Select list if the options exactly match Xero values. Enter values such as |
My status filter is not finding invoices. What should I check? | The status value in Jira may not match the status value expected by Xero. | Use the same status values shown in this guide: |
I changed a mapped Jira field, but the Xero tab still shows old data. What should I do? | The Xero activity tab may need to reload the latest values. | Click Refresh in the Xero activity tab after updating mapped fields such as status, amount, date, reference, customer name, currency code, or tracking values. |
My amount or date filter is not matching. What could be wrong? | The value format may be different from the value stored in Xero, or the Jira field type may not be suitable. | For amounts, use a Number field or Short text and enter values like |
My reference, customer name, or currency code filter is not matching. What should I verify? | The value may not be entered exactly as it appears in Xero, or the wrong Jira field may be mapped. | Check the mapped Jira field and value. For example, Reference can use |
My tracking category filter is not working. What should I verify? | The Jira tracking field may be mapped to the wrong Xero tracking category, or the value may not match the tracking option in Xero. | Make sure Tracking Region maps to Tracking → Region and Tracking Project maps to Tracking → Project. Use the same option values as Xero, such as |
I created the right field, but users cannot see it on the Jira issue. What should I check? | The custom field may not be added to the issue screen or project context where users are working. | In Jira administration, confirm the field is available for the relevant project and issue type, and that it appears on the issue view or edit screen. Then enter the value and refresh the Xero activity tab. |
The mapping looks correct, but the value on the Jira issue is empty. Will Xero data appear? | The app needs a value in the mapped Jira field before it can search Xero. | Enter the correct value in the mapped field first. For example, add |
I selected the wrong Xero organisation during authentication. What should I do? | The app may be connected to a Xero organisation that does not contain the invoice you are trying to fetch. | Go back to Xero Connection, authenticate again, and select the correct Xero organisation. Then reopen the Jira issue and refresh the Xero activity tab. |
A Jira administrator should configure the connection because the setup requires access to Jira app settings and Xero credentials.
A callback URL, also called a Redirect URI, is the address Xero uses to send the administrator back to Jira after approving the connection. It must be copied exactly from Jira into the Xero Developer app.
OAuth is the secure approval method used by Xero. In simple terms, it lets Jira access approved Xero information without asking users to share their Xero password inside Jira.
Start with Xero Invoice Number mapped to Invoice Number. This gives the most accurate match because it points to one specific invoice.
Yes. Users can use mapped fields such as invoice status, amount due, total, invoice date, due date, reference, customer name, currency code, and tracking categories, depending on what the administrator has configured.
Refresh reloads the latest matching data from Xero. Use it after changing a mapped Jira field or when an invoice was recently updated in Xero.
If users still cannot see the expected Xero data after checking the troubleshooting steps, collect the details below before contacting your internal Jira administrator or support team.
The Jira issue key where the problem appears.
The mapped Jira field name and value, such as Xero Invoice Number = INV-0029.
The Xero field it is mapped to, such as Invoice Number, Status, Invoice → Amount Due, or Tracking → Project.
The message shown in Jira, if any, such as No mappings configured or No matching invoices found.
Confirmation that the Xero connection is authenticated.
A screenshot of the Xero activity tab or the relevant Field Mapping configuration, if available.
ℹ️ Note: Do not share the Client Secret in screenshots or support messages. Treat it like a password.
