¶ Xero Integration
¶ Pre-requisites for the Integration
- You need to have at least one business profile and bank added to your Marmin account.
- The email IDs on Marmin and Xero should be the same.
¶ Integrating Marmin with the respective Xero Account
- Log into Marmin:
- Go to Settings.
- Navigate to "Organization Settings" under Settings.
- Xero Webhook Integration:
- Navigate to the section "Xero Webhook Integration."
- The status will show "Disconnected."
- Select the business profile and bank that should be selected by default for the invoices being synced from Xero. This can be changed later if needed.
- Click on "Connect to Xero."
- You will be redirected to Xero to allow access to the respective organization to sync data to Marmin.
- Once access is granted, you will be redirected back to Marmin, and you will see the connection status as green, indicating the Xero organization that has been linked.
With this integration, customers and invoices/CNs created on Xero will be synced in real-time to Marmin.
¶ Resolving Data Syncing Issues between Xero and Marmin
If data is not syncing between Xero and Marmin, begin by checking the integration status on both platforms. Navigate to the integration screens in both Marmin and Xero to verify that the connection is properly established and active. Refer to the screenshots below for guidance.
If the connection is not established on either platform, disconnect from the platform and reconnect by following the steps outlined in the previous section.
¶ Syncing and Creating ZATCA-Compliant Invoices from Xero
To sync invoices from Xero to Marmin, you will need to ensure that the buyer/customer created on Xero have all the necessary details required for creating a compliance invoice.
- Ensure the following fields are provided for the customer on Xero to create compliant invoices. Below is the mapping between Marmin and Xero:
| Xero | Marmin Data Fields |
|---|---|
| Contact name | Company Name |
| Primary person (First name + Last name) | Name |
| Phone number | Phone Number |
| Business registration number | CR number In case of a non-Saudi customer, this will be considered for Other ID |
| Address line 1 | Address Put the entire address in Address line 1 |
| Address line 2 + Address line 3 + Address line 4 | - |
| City | City |
| State | State and District The same value is mapped to both State and District on Marmin side since Xero doesn't provide the option for two separate fields |
| Zip code | Postal Code |
| Country | Country |
| Tax ID number | VAT number (needs to follow KSA VAT guidelines) Leave this blank for a B2C customer |
¶ Creating Different Invoices Based on Different Types of Customers
The table below represents the types of customers and how Marmin will interpret the customer.
|
Saudi Customer Saudi Phone Number |
Non-Saudi Customer Non-Saudi Phone Number |
|
|---|---|---|
| VAT and Other ID (business registration) both are present | B2B customer | NA |
| No VAT, only Other ID (business registration) is present | B2B customer | B2B Export customer |
| VAT and Other ID (business registration) both are NOT present | B2C customer | NA B2C export is not allowed with ZATCA |
Notes
- The phone number is used to identify a Saudi or non-Saudi customer.
- For example, when a customer created on Xero doesn't have a VAT and/or CR number and the phone number is a non-Saudi phone number, then the customer will be an export customer and the invoice will be an export invoice.
- If the customer is a local Saudi customer and the VAT rate is zero, it can be Z, E, or O. However, we default the VAT category to O while creating the invoice in Marmin, as Xero doesn't provide an option to add the VAT exemption code, which is mandated by ZATCA.
Here are the various combinations of different data points and what invoices will be created along with Tax categories
| Phone Number | VAT | Other ID | Customer | Invoice type | Invoice Transaction Code | Tax received from Xero | Tax received from Xero |
|---|---|---|---|---|---|---|---|
| 15% | 0% | ||||||
| SA | No | No | B2C | B2C with local address | 0200000 | S | O |
| SA | Yes | No | B2B | B2B normal with local address | 0100000 | S | O |
| SA | No | Yes | B2B | B2B normal with local address | 0100000 | S | O |
| Non-SA | NA | No | B2C | B2C with foreign address | 0200000 | S | O |
| Non-SA | NA | Yes | B2B | B2B export | 0100100 | S | Z |
¶ Syncing Invoices to Marmin
Creating an invoice:
- Create a new VAT rate for Standard VAT of 15% for Saudi Arabia if required.
- Save the invoice to sync with Marmin.
- Check the progress using the logs.
Phase 2 Implementation:
- If phase 2 has been enabled for your account, the invoice synced from Xero will be automatically sent to ZATCA for invoice validation.
¶ VAT Categories
When creating invoices in Marmin, it is crucial to select the appropriate VAT rate to ensure accurate tax application. Follow these guidelines to align the VAT rates set in Xero with those applied in Marmin:
- Standard VAT Rate: Assign a VAT percentage of 15% for standard transactions. The label or name you assign to this VAT rate in Xero does not affect its application in Marmin, as long as the percentage is correctly set.
- Export Invoices: For invoices intended for export, use a VAT rate of 0%. This ensures that no VAT is charged on goods or services sold outside the domestic market.
¶ Creating Export Invoices
To properly generate export invoices in Marmin, you need to consider the following steps:
- Select an Export Customer: Begin by ensuring that the customer for the invoice is designated as an export customer. For guidance on how to set up export customers in Marmin, refer to the section titled Creating Different Types of Customers.
- Apply the Correct VAT Rate: Always select a VAT rate of 0% for export invoices to comply with tax regulations for goods and services sold internationally.