Younium Xero Integration

1. Overview

1.1 What This Integration Does

The Younium Xero Integration provides three core capabilities:

1.2 Key Features

• ✅ Bi-directional account sync - Keep customer data in sync between systems
• ✅ Incremental sync - Only syncs changed records after initial import
• ✅ Automatic invoice posting - Post invoices to Xero when posted in Younium
• ✅ Product catalog sync - Import Xero items as Younium products
• ✅ Multi-currency support - Handles different currencies with exchange rates
• ✅ Address synchronization - Syncs both invoice and delivery addresses
• ✅ Payment terms mapping - Automatically creates and maps payment terms
• ✅ Tax code mapping - Maps Xero tax codes to Younium custom fields
• ✅ Chart of accounts mapping - Maps Xero sales accounts to Younium custom fields

1.3 Prerequisites

Before setting up the integration, ensure you have:

• ✅ Younium Administrator Access - Required to configure integration settings
• ✅ Xero Organization Access - Must have access to the Xero organization you want to connect
• ✅ Xero Tenant Name - The exact name of your Xero organization (case-sensitive)
• ✅ Matching Currencies - Currencies used in Xero must exist in Younium

2. Authentication & Setup

2.1 Initial Configuration

Step 1: Navigate to Settings

1. Log into Younium
2. Go to Settings > Integrations > Xero

Step 2: Enter Xero Tenant Name

1. In the Xero settings page, enter your Xero Tenant Name

• This must match exactly with your Xero organization name (case-sensitive)
• Example: “My Company Ltd” or “ACME Corporation”

Step 3: Authenticate

1. Click Authenticate
2. You will be redirected to Xero’s login page
3. Log in with your Xero credentials
4. Authorize Younium to access your Xero organization
5. You will be redirected back to Younium

2.2 OAuth2 Scopes

The integration requests the following Xero permissions:

• accounting.transactions - Read and write invoices
• accounting.transactions.read - Read invoice data
• accounting.reports.read - Access to reports
• accounting.journals.read - Read journal entries
• accounting.settings - Read and write settings
• accounting.settings.read - Read settings
• accounting.contacts - Read and write contacts (accounts)
• accounting.contacts.read - Read contacts
• accounting.attachments - Read and write attachments
• accounting.attachments.read - Read attachments
• offline_access - Maintain connection without re-authentication

2.3 Automatic Token Refresh

The integration automatically refreshes access tokens when they expire. You don’t need to re-authenticate unless:

• The refresh token expires (typically after 60 days of inactivity)
• You manually disconnect the integration
• Xero revokes access

3. Account Synchronization

3.1 Account Import (Xero → Younium)

Purpose: Import customer contacts from Xero into Younium as accounts.

What Gets Imported:

• Active contacts from Xero (where ContactStatus == "ACTIVE")
• Only contacts where IsCustomer == true

How to Run:

1. Go to Settings > Integrations > Xero
2. In the Account Sync section, click Import Accounts
3. The system will import all active customer contacts from Xero

Incremental Sync:

• After the first import, only changed contacts are synced
• The system tracks the LastGetCustomersImport timestamp
• On subsequent imports, only contacts modified after this timestamp are processed

What Happens During Import:

Payment Terms Auto-Creation:

• If a Xero contact has payment terms with type DAYSAFTERBILLDATE, the integration will:

1. Look for an existing payment term in Younium with matching days
2. If not found, create a new payment term with format “NET{days}”
3. Example: 30 days becomes “NET30” with description “30 Day(s) after the invoice date”

Address Handling:

• POBOX address type → Invoice address in Younium
• STREET address type → Delivery address in Younium
• Countries are automatically activated in Younium if marked inactive

New vs. Update Logic:

• New Account: Created if ExternalERPId doesn’t match any existing account
• Update Account: Updated if ExternalERPId matches and data has changed
• No Change: Skipped if data is identical (performance optimization)

3.2 Account Export (Younium → Xero)

Purpose: Export Younium accounts to Xero as contacts.

What Gets Exported:

• Accounts modified since last export (Modified > LastGetCustomersExport)
• On first run, all accounts are exported
• Both new accounts and updates to existing accounts

How to Run:

1. Go to Settings > Integrations > Xero
2. In the Account Sync section, click Export Accounts
3. The system will export all modified accounts to Xero

Rate Limiting:

• Xero has API rate limits
• The integration adds a 1.5 second delay between each account export
• This ensures compliance with Xero’s API limits

What Happens During Export:

YourReference Splitting:

• Younium’s YourReference field is split into Xero’s FirstName and LastName
• Split occurs on the first space
• Example: “John Smith Doe” → FirstName: “John”, LastName: “Smith Doe”

New vs. Update Logic:

• New Contact: Created if ExternalERPId is not set or doesn’t exist in Xero
• Update Contact: Updated if ExternalERPId matches a Xero contact
• Change Detection: Only exports if account or address data has changed

3.3 Currency Handling

Requirements:

• The currency used in Xero must exist in Younium
• Currency codes must match exactly (e.g., “USD”, “EUR”, “GBP”)

Import Behavior:

• Uses DefaultCurrency from Xero contact
• If DefaultCurrency is “0” (not set), uses the organization’s BaseCurrency
• Throws error if currency doesn’t exist in Younium

Export Behavior:

• Maps Younium currency to Xero CurrencyCode enum
• Supported currencies are those available in Xero’s API

4. Product Synchronization

4.1 Product Import (Xero → Younium)

Purpose: Import items from Xero as products in Younium.

What Gets Imported:

• All items from Xero
• Each Xero item becomes a Younium product with one charge plan and one charge

How to Run:

1. Go to Settings > Integrations > Xero
2. In the Product Sync section, click Import Products
3. The system will import all items from Xero

Incremental Sync:

• After the first import, only modified items are synced
• The system tracks LastGetProductsImport timestamp
• On subsequent imports, only items modified after this timestamp are processed

Product Structure Created:

Product (from Xero Item)
└── Charge Plan (auto-created)
    └── Charge (from Xero Item)

Field Mapping:

Charge Configuration:

• Model: Set to Quantity (quantity-based pricing)
• End of New Sales Date: Set to null (no end date)

Validation:

• Xero item must have a Name (required)
• Xero item Code must be unique in Younium
• If duplicate Code exists in Younium, the import fails for that item

New vs. Update Logic:

• New Product: Created if ExternalERPId doesn’t match any existing product
• Update Product: Updated if ExternalERPId matches and data has changed
• No Change: Skipped if data is identical

5. Invoice Posting

5.1 Automatic Invoice Posting

Purpose: Automatically post invoices to Xero when they are posted in Younium.

How to Enable:

1. Go to Settings > Integrations > Xero
2. Enable the Post Invoices to Xero toggle
3. Invoices will now automatically post to Xero when posted in Younium

What Gets Posted:

• Invoice header information
• All invoice lines (with quantity and pricing)
• Tax codes (if configured on account)
• Currency and exchange rates

5.2 Invoice vs. Credit Note

The integration automatically determines whether to create an invoice or credit note:

• Debit Invoice: Total amount > 0 → Creates Xero Invoice
• Credit Invoice: Total amount < 0 → Creates Xero Credit Note

5.3 Invoice Field Mapping

Debit Invoice (Normal Invoice):

Credit Note (Negative Invoice):

5.4 Invoice Line Mapping

Line Item Fields:

Description Format:

[ChargeDescription]
[ServicePeriodStartDate] to [ServicePeriodEndDate]  (if recurring/subscription)
[Notes]  (if present)

Example:

Monthly Subscription - Premium Plan
2026-01-01 to 2026-01-31
Includes support package

Quantity and Price Calculation:

• Handles different charge types (quantity-based, usage-based, etc.)
• For credit notes, unit amount is negated (quantity stays positive)

5.4 Invoice Line Filtering

Settings Applied:

• Hide Zero Amount Recurring Lines: If enabled, recurring charges with 0 amount are excluded
• Hide Zero Amount Usage Lines: If enabled, usage/measurement charges with 0 amount are excluded

These settings are configured in Younium’s invoice settings and automatically applied during posting.

5.5 Post-Posting Update

After successful posting to Xero:

• Younium invoice’s ExternalERPId is updated with the Xero invoice/credit note number
• Success logged in integration event log

6. Field Mapping Reference

6.1 Custom Fields Created

The integration automatically creates two custom field lists in Younium:

Xero Tax Code

Field Name: Xero - Xero Tax Code

Object: Account

Type: List

Available Values:

Xero Sales Account

Field Name: Xero - Xero Sales Account

Object: Account

Type: List

Values: Dynamically populated from your Xero Chart of Accounts

• Lists all financial accounts from Xero
• Format: Code - Name (e.g., “200 - Sales Revenue”)
• Refreshed when settings are saved

6.2 Address Type Mapping

Xero Address Types:

• POBOX → Younium Invoice Address
• STREET → Younium Delivery Address

Address Fields Mapped:

6.3 Payment Terms Mapping

Xero to Younium:

• Only DAYSAFTERBILLDATE payment term type is supported
• Other types are ignored
• Days value is used to match or create payment term

Example Conversion:

• Xero: Type = DAYSAFTERBILLDATE, Days = 30
• Younium: Name = “NET30”, Days = 30, Description = “30 Day(s) after the invoice date”

Younium to Xero:

• Payment term days are converted to Xero payment terms
• Type is always set to DAYSAFTERBILLDATE

7. Sync Behavior & Logic

7.1 Change Detection

Account Import (Xero → Younium):

The system checks if any of these fields have changed:

• Name
• Domain (Website)
• TaxRegistrationNumber
• OrganizationNumber
• DefaultPaymentTermId
• CurrencyId
• YourReference

Additionally checks addresses:

• Invoice Address fields (Street, Street2, State, City, Zip, Country)
• Delivery Address fields (Street, Street2, State, City, Zip, Country)

Account Export (Younium → Xero):

Exports accounts where:

• Account Modified > LastGetCustomersExport, OR
• DefaultInvoiceAddress.Modified > LastGetCustomersExport, OR
• DefaultDeliveryAddress.Modified > LastGetCustomersExport

7.2 Matching Logic

Accounts:

• Xero ContactID ↔︎ Younium ExternalERPId
• If ExternalERPId matches, account is updated
• If no match, new account is created

Products:

• Xero Item Code ↔︎ Younium Product ExternalERPId
• If ExternalERPId matches, product is updated
• If no match, new product is created

Invoices:

• After posting to Xero, Younium ExternalERPId is set to Xero invoice/credit note number
• This field is for reference only (no reverse sync)

7.3 Pagination

Account Import:

• Loads accounts from Xero in pages
• Continues until no more accounts are returned
• Page count increments automatically
• Handles large account lists efficiently

Product Import:

• Uses Xero’s built-in pagination
• Ordered by “Name ASC”
• Handles ifModifiedSince for incremental sync

7.4 Error Handling

Per-Record Error Handling:

• If one account/product fails, others continue processing
• Failed records are logged with error details
• Success count, update count, and failure count are tracked separately

Integration Event Logging:

• Success events logged with counts (e.g., “50 new accounts and updated 25 accounts. 2 accounts failed”)
• Failure events logged with error message and full record JSON
• Events visible in Younium integration log

Common Errors:

• Currency not found in Younium
• Missing required fields
• Duplicate External ERP IDs

8. Troubleshooting

8.1 Authentication Issues

Problem: “Not Authenticated” status

Solutions:

1. Check that the Xero Tenant Name exactly matches your Xero organization name (case-sensitive)
2. Click Authenticate again to refresh the connection
3. Verify you have the necessary permissions in Xero
4. Check that the Xero organization is active

Problem: Token expired

Solution:

• The integration automatically refreshes tokens
• If automatic refresh fails, manually re-authenticate
• Check integration logs for token refresh errors

8.2 Account Sync Issues

Problem: “No currency exists in Younium”

Solution:

1. Check which currency the Xero contact uses
2. Add that currency to Younium if missing
3. Ensure currency codes match exactly (USD, EUR, GBP, etc.)

Problem: Accounts not syncing

Solutions:

1. Verify accounts have ContactStatus == "ACTIVE" in Xero
2. Check that IsCustomer is true (suppliers-only are skipped)
3. Look for error messages in the integration log
4. Verify ExternalERPId field is not corrupted

Problem: Addresses not syncing

Solutions:

1. Verify Xero address type is POBOX or STREET
2. Check that country name in Xero matches Younium country list
3. Ensure country is active in Younium
4. Check address fields for invalid characters

8.3 Product Sync Issues

Problem: “Xero product id/code: [code] has no name”

Solution:

• Add a name to the item in Xero
• All Xero items must have a name to sync

Problem: “Xero product id/code: [code] exist twice in Younium”

Solution:

• Fix the duplicate ExternalERPId in Younium
• Each product must have a unique External ERP ID

8.4 Invoice Posting Issues

Problem: “Could not post invoice to Xero”

Solutions:

1. Verify the account has a valid ExternalERPId (Xero ContactID)
2. Ensure the account exists in Xero
3. Check that invoice lines have valid product/charge references
4. Verify currency is supported in Xero
5. Check Xero API rate limits

Problem: Invoice posted but not showing in Xero

Solution:

• Check that invoice was created as DRAFT (as designed)
• Look for the invoice by reference number in Xero

9. Best Practices

9.1 Initial Setup

1. Test in Sandbox First
   • Connect to a Xero sandbox/demo organization first
   • Test account import/export with a few records
   • Verify field mappings are correct
   • Then connect to production
2. Data Preparation
   • Ensure all currencies in Xero exist in Younium before syncing
   • Clean up duplicate contacts in Xero
   • Verify all active contacts have required fields populated
3. Custom Field Setup
   • Configure “Xero Tax Code” custom field on accounts
   • Configure “Xero Sales Account” custom field on accounts
   • These fields are created automatically but need to be populated

9.2 Ongoing Operations

1. Incremental Sync
   • Use incremental sync for regular updates
   • Only do full sync when needed (initial setup, data cleanup)
   • Click “Remove Last Sync Date” to force full sync
2. Invoice Posting
   • Enable automatic invoice posting only after testing
   • Invoices are created as DRAFT in Xero (review before finalizing)
   • Monitor integration logs for posting failures
3. Data Quality
   • Keep ExternalERPId field clean (don’t manually edit)
   • Ensure accounts in Younium that sync to Xero have all required fields
   • Regularly check for sync errors in integration logs
4. Address Management
   • Use consistent country names between systems
   • Ensure countries are active in Younium
   • Update addresses in the system where they originated

10. Technical Specifications

10.1 Integration Architecture

Type: Server-side Integration

Protocol: OAuth2 with token refresh

API: Xero NetStandard OAuth2 SDK

Sync Type: Pull (from Xero) and Push (to Xero)

Event Handling: Younium event subscription for invoice posting

10.2 Error Codes

Common Integration Errors:

10.3 Logging & Monitoring

Integration Events:

• All sync operations logged
• Success/failure status recorded
• Record counts tracked (new, updated, failed)
• Error messages captured with full record details

Log Retention:

• Integration logs retained per Younium’s data retention policy
• View in Settings > Integrations > Xero > Event Log

Monitoring Points:

• Authentication status
• Last sync timestamps
• Record counts per sync
• Failed record count
• Error messages

Appendix A: Field Reference Tables

Complete Account Field Mapping

Complete Product Field Mapping

Complete Invoice Field Mapping

Invoice Line Field Mapping