Xero Contact Payment Terms Integration

Why

Enable Xero users to sync contact payment terms, tax types, and tracking categories between Xero and Coreloops Directory.

What

Implement Xero-specific contact fields with mapping to unified Coreloops schema.

Xero Fields → Coreloops Schema Mapping

Payment Terms (Sales & Bills)

• PaymentTerms.Sales.Day → sales_payment_days
• PaymentTerms.Sales.Type → sales_payment_terms_type (DAYSAFTERBILLDATE, DAYSAFTERBILLMONTH, OFCURRENTMONTH, OFFOLLOWINGMONTH)
• PaymentTerms.Bills.Day → purchase_payment_days
• PaymentTerms.Bills.Type → purchase_payment_terms_type

Tax Configuration

• AccountsReceivableTaxType → sales_tax_type
• AccountsPayableTaxType → purchase_tax_type
• TaxNumber → tax_number

Tracking Categories

• SalesTrackingCategories[].TrackingCategoryName → sales_tracking_category_name
• SalesTrackingCategories[].TrackingOptionName → sales_tracking_option_name
• PurchasesTrackingCategories[].TrackingCategoryName → purchase_tracking_category_name
• PurchasesTrackingCategories[].TrackingOptionName → purchase_tracking_option_name

Credit Management

• CreditLimit → credit_limit (UI feature, API support pending)
• AccountsReceivableTax → ar_tax_amount (read-only)
• AccountsPayableTax → ap_tax_amount (read-only)

Contact Classification

• IsSupplier → is_supplier
• IsCustomer → is_customer
• ContactStatus → contact_status (ACTIVE, ARCHIVED)

Unified Schema Fields

sales_payment_days: integer
sales_payment_terms_type: enum [days_after_invoice, days_after_month, current_month, following_month]
purchase_payment_days: integer
purchase_payment_terms_type: enum [days_after_invoice, days_after_month, current_month, following_month]
sales_tax_type: string
purchase_tax_type: string
tax_number: string
sales_tracking_category_name: string
sales_tracking_option_name: string
purchase_tracking_category_name: string
purchase_tracking_option_name: string
credit_limit: decimal
ar_tax_amount: decimal (read-only)
ap_tax_amount: decimal (read-only)
is_supplier: boolean
is_customer: boolean
contact_status: enum [active, archived]

Cross-Platform Unified Mapping

payment_days: integer (maps from sales_payment_days or purchase_payment_days)
payment_terms_type: enum (normalised across all platforms)
early_payment_discount_days: integer (not native in Xero)
early_payment_discount_percent: decimal (not native in Xero)
credit_limit: decimal
current_balance: decimal (read-only)
account_active: boolean (maps from contact_status)

How

1. Extend Directory contact model with unified schema fields
2. Implement Xero Contacts API integration
3. Map Xero payment terms for both Sales and Bills separately
4. Handle tracking categories as multi-value fields
5. Support tax type configuration per contact
6. Prepare for future credit limit API support from Xero
7. Display Xero-specific fields in UI when Xero integration is active

Dependencies

• COR-739: Parent issue
• Xero API authentication (OAuth 2.0)
• Directory contact infrastructure

Acceptance Criteria

• Sales payment terms sync from/to Xero
• Bills payment terms sync from/to Xero (note: API may have limitations on update)
• Tax types (AR and AP) sync correctly
• Sales and purchase tracking categories sync bidirectionally
• Credit limit field prepared for future API support
• Contact classification (customer/supplier) handled correctly
• UI shows only relevant Xero fields when Xero integration is active
• Bidirectional sync maintains data integrity