Audit Logs & Data Exports

Overview

BoxBilling provides two operational features for visibility and data portability: audit logs record every change made to billing entities, and data exports let you extract billing data as CSV files for reporting, compliance, or migration.

Audit logs

Audit logs capture a trail of actions performed on billing resources. Every create, update, and delete operation is recorded with the actor, timestamp, and a snapshot of what changed.

Audit log properties

Field	Type	Description
id	uuid	Unique audit log entry identifier
organization_id	uuid	Organization this entry belongs to
resource_type	string	Type of resource (e.g., customer, invoice, subscription)
resource_id	uuid	ID of the affected resource
action	string	Action performed (e.g., create, update, delete)
changes	object	Snapshot of field changes
actor_type	string	Who performed the action (e.g., user, system, api)
actor_id	string?	ID of the actor, if applicable
metadata_	object?	Additional context about the action
created_at	datetime	When the action occurred

List audit logs

Query audit logs with optional filters to narrow results by resource, action, actor, or time range.

curl "/v1/audit_logs/?resource_type=invoice&action=update&start_date=2026-03-01T00:00:00Z&end_date=2026-03-08T23:59:59Z" \
  -H "Authorization: Bearer $API_KEY"

Response (200):

[
  {
    "id": "a10e8400-e29b-41d4-a716-446655440000",
    "organization_id": "org-uuid",
    "resource_type": "invoice",
    "resource_id": "inv-uuid-001",
    "action": "update",
    "changes": {
      "status": {"old": "draft", "new": "finalized"}
    },
    "actor_type": "api",
    "actor_id": "api-key-uuid",
    "metadata_": null,
    "created_at": "2026-03-05T14:30:00Z"
  }
]

Filter parameters:

Parameter	Type	Description
resource_type	string	Filter by resource type
resource_id	uuid	Filter by specific resource
action	string	Filter by action type
actor_type	string	Filter by actor type
start_date	datetime	Start of time range
end_date	datetime	End of time range
skip	integer	Pagination offset (default: 0)
limit	integer	Page size (default: 100, max: 1000)

Get audit trail for a resource

Retrieve the full audit history for a specific resource by type and ID.

curl /v1/audit_logs/customer/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $API_KEY"

This returns all audit log entries for that resource, ordered by time. Supports skip and limit for pagination.

Data exports

Data exports let you extract billing data as CSV files. Exports run as background jobs — you create an export, monitor its progress, and download the file when it completes.

Create export ──► Processing (background)
                       │
                       ▼
              Track progress (%)
                       │
                       ▼
              Download CSV file

Data export properties

Field	Type	Description
id	uuid	Unique export identifier
organization_id	uuid	Organization this export belongs to
export_type	string	Type of data being exported
status	string	Current status (e.g., pending, processing, completed, failed)
filters	object?	Optional filters applied to the export
file_path	string?	Path to the generated file (set on completion)
record_count	integer?	Number of records in the export
progress	integer?	Completion percentage (0–100)
error_message	string?	Error details if the export failed
started_at	datetime?	When processing began
completed_at	datetime?	When processing finished
created_at	datetime	When the export was requested

Export types

Type	Description
invoices	All invoices
customers	All customers
subscriptions	All subscriptions
events	Usage and billing events
fees	Individual fee line items
credit_notes	All credit notes
audit_logs	Audit log entries

Estimate export size

Before creating an export, you can estimate how many records it will include.

curl -X POST /v1/data_exports/estimate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "export_type": "invoices",
    "filters": {
      "start_date": "2026-01-01",
      "end_date": "2026-03-08"
    }
  }'

Response (200):

{
  "export_type": "invoices",
  "record_count": 1250
}

Create a data export

curl -X POST /v1/data_exports/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "export_type": "invoices",
    "filters": {
      "start_date": "2026-01-01",
      "end_date": "2026-03-08"
    }
  }'

Response (201):

{
  "id": "b20e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org-uuid",
  "export_type": "invoices",
  "status": "pending",
  "filters": {
    "start_date": "2026-01-01",
    "end_date": "2026-03-08"
  },
  "file_path": null,
  "record_count": null,
  "progress": 0,
  "error_message": null,
  "started_at": null,
  "completed_at": null,
  "created_at": "2026-03-08T10:00:00Z"
}

The export starts processing in the background. Poll the export by ID to check progress.

Check export status

curl /v1/data_exports/b20e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $API_KEY"

The progress field shows completion percentage and status transitions from pending → processing → completed (or failed).

Download export

Once the export status is completed, download the CSV file.

curl /v1/data_exports/b20e8400-e29b-41d4-a716-446655440000/download \
  -H "Authorization: Bearer $API_KEY" \
  -o invoices-export.csv

Returns 400 if the export has not yet completed.

List data exports

curl /v1/data_exports/ \
  -H "Authorization: Bearer $API_KEY"

Supports pagination with skip and limit query parameters (default: 100 items, max: 1000). Use order_by to sort results.

API endpoints

Method	Path	Description
GET	/v1/audit_logs/	List audit logs with filters
GET	/v1/audit_logs/{resource_type}/{resource_id}	Get audit trail for a resource
POST	/v1/data_exports/	Create a data export
GET	/v1/data_exports/	List data exports
POST	/v1/data_exports/estimate	Estimate export size
GET	/v1/data_exports/{export_id}	Get export status
GET	/v1/data_exports/{export_id}/download	Download export CSV