Overview
BoxBilling supports integrations with external systems for accounting, CRM, and payment processing. Each organization can connect one integration per provider type.
Integration types
| Type | Description | Supported providers |
|---|
payment_provider | Payment processing | Stripe, Adyen, GoCardless |
accounting | Financial sync | NetSuite, Xero |
crm | Customer sync | HubSpot, Salesforce |
tax | Tax calculation | Anrok, Avalara |
Creating an integration
curl -X POST /v1/integrations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"integration_type": "accounting",
"provider_type": "xero",
"settings": {
"client_id": "...",
"client_secret": "...",
"tenant_id": "..."
}
}'
Only one integration per provider type is allowed per organization.
Testing a connection
POST /v1/integrations/{id}/test
{
"success": true,
"details": {
"connected": true,
"organization_name": "My Company"
}
}
Integration adapters
BoxBilling uses a strategy-based adapter pattern. Each provider implements the IntegrationAdapter interface:
| Method | Description |
|---|
sync_customer(customer_id) | Sync customer data to external system |
sync_invoice(invoice_id) | Sync invoice to external system |
sync_payment(payment_id) | Sync payment to external system |
process_webhook(payload) | Handle incoming webhooks |
test_connection() | Verify credentials and connectivity |
Sync result
All adapter methods return an IntegrationSyncResult:
{
"success": true,
"external_id": "EXT-12345",
"external_data": {"name": "Customer Inc"},
"error": null
}
Integration mappings
Integration mappings track the relationship between BoxBilling entities and their external counterparts:
| Field | Description |
|---|
integration_id | The integration this mapping belongs to |
mappable_type | Entity type (e.g. customer, invoice) |
mappable_id | BoxBilling entity UUID |
external_id | External system’s ID |
external_data | Cached data from external system |
last_synced_at | Last synchronization timestamp |
Integration customers
Direct customer-level mappings between BoxBilling customers and their external representations:
{
"integration_id": "integration-uuid",
"customer_id": "customer-uuid",
"external_customer_id": "EXT-CUST-001",
"settings": {}
}
Integration statuses
| Status | Description |
|---|
active | Integration is operational |
inactive | Integration is disabled |
error | Integration has encountered errors |
error_details JSON field contains diagnostic information.
API endpoints
| Method | Path | Description |
|---|
POST | /v1/integrations | Create integration |
GET | /v1/integrations | List integrations |
GET | /v1/integrations/{id} | Get integration details |
PUT | /v1/integrations/{id} | Update integration |
DELETE | /v1/integrations/{id} | Delete integration |
POST | /v1/integrations/{id}/test | Test connection |
