0
# Airbyte Source Xero
1

2
An Airbyte source connector for extracting data from the Xero accounting API. This connector enables automated data synchronization from Xero's comprehensive accounting platform, supporting 21 different data streams including transactions, contacts, invoices, and financial records with incremental sync capabilities.
3

4
## Package Information
5

6
- **Package Name**: airbyte-source-xero
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install airbyte-source-xero`
10
- **Airbyte Framework**: Declarative low-code CDK v1
11
- **Python Version**: 3.9 - 3.11
12

13
## Core Imports
14

15
```python
16
from source_xero import SourceXero
17
from source_xero.run import run
18
```
19

20
For date processing utilities:
21

22
```python
23
from source_xero.components import ParseDates, CustomExtractor
24
```
25

26
## Basic Usage
27

28
### Command Line Usage
29

30
```bash
31
# Run as Airbyte connector
32
source-xero discover --config config.json
33
source-xero check --config config.json
34
source-xero read --config config.json --catalog catalog.json
35
```
36

37
### Programmatic Usage
38

39
```python
40
from source_xero import SourceXero
41
import json
42

43
# Load configuration
44
config = {
45
    "access_token": "your_xero_access_token",
46
    "tenant_id": "your_xero_tenant_id", 
47
    "start_date": "2023-01-01T00:00:00Z"
48
}
49

50
# Initialize source connector
51
source = SourceXero()
52

53
# Check connection
54
status, error = source.check_connection(logger, config)
55
if status:
56
    print("Connection successful")
57
    
58
    # Get available streams
59
    streams = source.streams(config)
60
    print(f"Available streams: {len(streams)}")
61
    
62
    # Stream names: bank_transactions, contacts, invoices, etc.
63
    for stream in streams:
64
        print(f"Stream: {stream.name}")
65
```
66

67
### Date Processing
68

69
```python
70
from source_xero.components import ParseDates
71

72
# Parse Xero .NET JSON date format
73
xero_date = "/Date(1419937200000+0000)/"
74
parsed_date = ParseDates.parse_date(xero_date)
75
print(parsed_date)  # 2014-12-30 07:00:00+00:00
76

77
# Convert dates in nested data structures
78
data = {"UpdatedDate": "/Date(1419937200000+0000)/", "Amount": 100.50}
79
ParseDates.convert_dates(data)
80
print(data)  # {"UpdatedDate": "2014-12-30T07:00:00+00:00", "Amount": 100.50}
81
```
82

83
## Architecture
84

85
The connector is built using Airbyte's declarative low-code framework with the following key components:
86

87
- **SourceXero**: Main connector class inheriting from YamlDeclarativeSource
88
- **Manifest Configuration**: YAML-based stream definitions with authentication, pagination, and incremental sync
89
- **Custom Components**: Date parsing and record extraction for Xero-specific data formats
90
- **Stream Processors**: 21 pre-configured data streams with automatic schema validation
91

92
## Capabilities
93

94
### Core Connector API
95

96
Main connector functionality including initialization, connection testing, and stream management. Provides the primary interface for Airbyte framework integration.
97

98
```python { .api }
99
class SourceXero(YamlDeclarativeSource):
100
    def __init__(self): ...
101
    def check_connection(self, logger, config: dict) -> tuple[bool, str]: ...
102
    def streams(self, config: dict) -> list: ...
103

104
def run(): ...
105
```
106

107
[Core Connector API](./core-connector.md)
108

109
### Data Processing Components
110

111
Specialized utilities for handling Xero-specific data formats, particularly .NET JSON date strings and custom record extraction with automatic date conversion.
112

113
```python { .api }
114
class ParseDates:
115
    @staticmethod
116
    def parse_date(value: str) -> datetime | None: ...
117
    @staticmethod
118
    def convert_dates(obj: dict | list) -> None: ...
119

120
@dataclass
121
class CustomExtractor(RecordExtractor):
122
    field_path: list[str | InterpolatedString]
123
    config: Config
124
    decoder: Decoder
125
    def extract_records(self, response: requests.Response) -> list[dict]: ...
126
```
127

128
[Data Processing](./data-processing.md)
129

130
### Configuration & Authentication  
131

132
Configuration specification and authentication setup for connecting to Xero API with proper credentials and tenant management.
133

134
```python { .api }
135
# Configuration Schema
136
{
137
    "access_token": str,  # Required, secret
138
    "tenant_id": str,     # Required, secret  
139
    "start_date": str     # Required, ISO 8601 format
140
}
141
```
142

143
[Configuration & Authentication](./configuration.md)
144

145
### Data Streams
146

147
Access to 21 different Xero data streams organized into transactional data (with incremental sync) and reference data (snapshot sync).
148

149
**Transactional Streams** (9 streams with incremental sync):
150
- bank_transactions, contacts, credit_notes, invoices, manual_journals, overpayments, prepayments, purchase_orders, payments
151

152
**Reference Streams** (12 streams with snapshot sync):
153
- accounts, bank_transfers, employees, items, users, branding_themes, contact_groups, currencies, organisations, repeating_invoices, tax_rates, tracking_categories
154

155
[Data Streams](./data-streams.md)
156

157
## Configuration
158

159
```python { .api }
160
# Required configuration fields
161
ConfigSpec = {
162
    "access_token": {
163
        "type": "string",
164
        "title": "Access Token", 
165
        "description": "Enter your Xero application's access token",
166
        "airbyte_secret": True
167
    },
168
    "tenant_id": {
169
        "type": "string",
170
        "title": "Tenant ID",
171
        "description": "Enter your Xero organization's Tenant ID", 
172
        "airbyte_secret": True
173
    },
174
    "start_date": {
175
        "type": "string",
176
        "title": "Start Date",
177
        "description": "UTC date and time in format YYYY-MM-DDTHH:mm:ssZ",
178
        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$",
179
        "format": "date-time"
180
    }
181
}
182
```
183

184
## Error Handling
185

186
The connector implements comprehensive error handling for common Xero API scenarios:
187

188
- **401 Unauthorized**: Authentication failures with clear error messages
189
- **403 Forbidden**: Permission issues (records ignored)
190
- **429 Rate Limited**: Automatic retry with 30-second backoff
191
- **Date Parsing Errors**: Graceful handling of malformed date strings
192
- **Network Issues**: Standard HTTP client error handling with retries