Integrations

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

Integration properties

Field	Type	Description
id	uuid	Unique integration ID
organization_id	uuid	Owning organization
integration_type	string	Type category (e.g. accounting, crm)
provider_type	string	Provider name (e.g. xero, stripe)
status	string	Current status (active, inactive, error)
settings	object	Provider-specific configuration
last_sync_at	datetime	Last successful sync timestamp
error_details	object	Diagnostic info when status is error
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

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": "..."
    }
  }'

Caution

Only one integration per provider type is allowed per organization.

Updating an integration

Update status or settings of an existing integration:

curl -X PUT /v1/integrations/{integration_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive",
    "settings": { "tenant_id": "new-tenant" }
  }'

Updatable fields: status, settings, error_details.

Testing a connection

POST /v1/integrations/{id}/test

Returns:

{
  "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.

Mapping properties

Field	Type	Description
id	uuid	Mapping ID
integration_id	uuid	The integration this mapping belongs to
mappable_type	string	Entity type (e.g. customer, invoice)
mappable_id	uuid	BoxBilling entity UUID
external_id	string	External system’s ID
external_data	object	Cached data from external system
last_synced_at	datetime	Last synchronization timestamp
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

List mappings for an integration

curl /v1/integrations/{integration_id}/mappings \
  -H "Authorization: Bearer $API_KEY"

Supports skip and limit query parameters.

Integration customers

Direct customer-level mappings between BoxBilling customers and their external representations.

Customer mapping properties

Field	Type	Description
id	uuid	Mapping ID
integration_id	uuid	Parent integration
customer_id	uuid	BoxBilling customer UUID
external_customer_id	string	External system’s customer ID
settings	object	Customer-specific integration settings
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

List customer mappings for an integration

curl /v1/integrations/{integration_id}/customers \
  -H "Authorization: Bearer $API_KEY"

List integration mappings for a customer

View all integrations a specific customer is mapped to:

curl /v1/customers/{customer_id}/integration_mappings \
  -H "Authorization: Bearer $API_KEY"

Response fields:

Field	Type	Description
id	uuid	Mapping ID
integration_id	uuid	Integration UUID
integration_name	string	Integration display name
integration_provider	string	Provider type
external_customer_id	string	External customer ID
settings	object	Customer-specific settings
created_at	datetime	Creation timestamp

Sync history

Track synchronization activity for an integration, including successes and failures:

curl "/v1/integrations/{integration_id}/sync_history?status=failed" \
  -H "Authorization: Bearer $API_KEY"

Supports status, resource_type, skip, and limit query filters.

Sync history properties

Field	Type	Description
id	uuid	Sync record ID
integration_id	uuid	Parent integration
resource_type	string	Entity type synced (e.g. customer, invoice)
resource_id	uuid	BoxBilling entity ID
external_id	string	External system entity ID
action	string	Sync action performed
status	string	Sync result status
error_message	string	Error details if failed
details	object	Additional sync metadata
started_at	datetime	Sync start time
completed_at	datetime	Sync completion time
created_at	datetime	Record creation timestamp

Integration statuses

Status	Description
active	Integration is operational
inactive	Integration is disabled
error	Integration has encountered errors

When an integration encounters errors, the error_details JSON field contains diagnostic information.

API endpoints

Integration management

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

Integration data

Method	Path	Description
GET	/v1/integrations/{id}/customers	List customer mappings
GET	/v1/integrations/{id}/mappings	List field mappings
GET	/v1/integrations/{id}/sync_history	List sync history
GET	/v1/customers/{customer_id}/integration_mappings	List customer’s integration mappings