Tax Rates
Overview
📥 Direction: NetSuite → Zudello
🔄 Sync Type: Full sync
⏱️ Frequency: Daily or on-demand
Tax rate data flows from NetSuite to Zudello to maintain accurate sales tax calculations. This integration synchronizes sales tax items with their associated rates, converting NetSuite's decimal format to Zudello's percentage representation.
Key Benefits
✅ Accurate Tax Calculations - Precise rate synchronization
✅ Multi-Jurisdiction Support - Handle complex tax scenarios
✅ Automatic Conversion - Decimal to percentage transformation
✅ Compliance Ready - Up-to-date tax rates for reporting
Field Mappings
| Zudello Field | NetSuite Field | Data Type | Notes |
|---|---|---|---|
| code | itemId | String | Tax item code |
| name | displayName | String | Tax rate description |
| rate | rate | Percentage | Converted from decimal (e.g., 0.1 → 10%) |
| tax_type | taxType | Relation | Reference to tax type/solution |
| effective_date | effectiveFrom | Date | Rate effective date |
| status | isInactive | String | true = INACTIVE, false = ACTIVE |
| subsidiary | subsidiary | Relation | Applicable subsidiary |
API Configuration
SuiteQL Configuration
- Table: SalesTaxItem
- Join Tables: TaxType, Subsidiary
- Record Type: Tax items only (not tax groups)
- Filter: Both active and inactive rates
Query Optimization
- Filtered by item type = 'Tax Item'
- Ordered by subsidiary, then code
- Includes historical rates
- Excludes tax groups/codes
Sync Configuration
Full Sync Rationale
- Tax rates change infrequently
- Critical for calculation accuracy
- Ensures no orphaned rates
- Simplifies rate management
Processing Strategy
- Extract all tax items
- Convert rate format
- Validate relationships
- Replace entire dataset
Processing Logic
Rate Conversion
NetSuite Rate (Decimal) → Zudello Rate (Percentage)
- NetSuite: 0.1 → Zudello: 10%
- NetSuite: 0.075 → Zudello: 7.5%
- NetSuite: 0.0825 → Zudello: 8.25%
Status Mapping
- Active Rates:
isInactive = false→ Status = "ACTIVE" - Inactive Rates:
isInactive = true→ Status = "INACTIVE" - Expired Rates: May remain active with date restrictions
- Future Rates: Loaded but effective date controlled
Multi-Rate Handling
- Same tax type can have multiple rates
- Effective dating determines applicable rate
- Historical rates preserved for reporting
- Rate changes tracked over time
Special Features
Jurisdiction Management
- Federal/national rates
- State/provincial rates
- County/local rates
- Special district rates
Rate Components
- Base rate percentage
- Surtax additions
- Exemption thresholds
- Cap amounts
Subsidiary Assignment
- Rates linked to specific entities
- Multi-subsidiary rate sharing
- Entity-specific overrides
- Consolidated rate management
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Rate calculation errors | Decimal not converted | Verify rate conversion formula |
| Missing tax types | Tax type not synced | Run tax solutions sync first |
| Duplicate rates | Multiple effective dates | Review date-based filtering |
| Wrong percentage | Incorrect decimal places | Check decimal precision (0.1 = 10%) |
| Subsidiary mismatch | Entity restrictions | Verify subsidiary assignments |
Related Documentation
- Tax Solutions - Tax type configurations
- Subsidiaries - Entity-specific tax settings
- NetSuite Overview - General integration guidelines
- Purchase Invoice - Tax calculation in transactions