Customers

Overview

Customers are the central entity in BoxBilling. Every subscription, invoice, payment, and wallet belongs to a customer. Each customer has configurable billing settings (currency, timezone, payment terms) and can be linked to external systems via integration mappings.

Customer properties

Field	Type	Description
id	uuid	Unique customer identifier
external_id	string	Your system’s identifier for this customer
name	string	Customer display name
email	string?	Contact email address
currency	string	3-letter ISO currency code (default: USD)
timezone	string	IANA timezone (default: UTC)
billing_metadata	object	Arbitrary key-value metadata for billing
invoice_grace_period	integer	Days before an invoice is marked overdue (default: 0)
net_payment_term	integer	Payment term in days (default: 30)
billing_entity_id	uuid?	Associated billing entity
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create a customer

curl -X POST /v1/customers/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "cust_001",
    "name": "Acme Corp",
    "email": "[email protected]",
    "currency": "USD",
    "timezone": "America/New_York",
    "billing_metadata": {"segment": "enterprise"},
    "invoice_grace_period": 3,
    "net_payment_term": 30
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "cust_001",
  "name": "Acme Corp",
  "email": "[email protected]",
  "currency": "USD",
  "timezone": "America/New_York",
  "billing_metadata": {"segment": "enterprise"},
  "invoice_grace_period": 3,
  "net_payment_term": 30,
  "billing_entity_id": null,
  "created_at": "2026-03-08T10:00:00Z",
  "updated_at": "2026-03-08T10:00:00Z"
}

The external_id must be unique across all customers and serves as the primary key for API operations that reference customers by your system’s identifier (usage queries, portal URLs, entitlements).

Update a customer

curl -X PUT /v1/customers/{customer_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "email": "[email protected]",
    "net_payment_term": 45
  }'

All update fields are optional — only the fields you include are modified.

Delete a customer

DELETE /v1/customers/{customer_id}

Returns 204 No Content on success.

Customer health

The health endpoint provides a quick assessment of a customer’s payment history:

GET /v1/customers/{customer_id}/health

Response:

{
  "status": "warning",
  "total_invoices": 24,
  "paid_invoices": 20,
  "overdue_invoices": 2,
  "total_payments": 22,
  "failed_payments": 3,
  "overdue_amount": 15000
}

Health statuses

Status	Description
good	No overdue invoices, minimal failed payments
warning	Some overdue invoices or failed payments
critical	Significant overdue balance or repeated payment failures

Use health status to prioritize outreach, adjust credit limits, or trigger dunning campaigns.

Usage queries

BoxBilling provides three usage query endpoints, all keyed by the customer’s external_id:

Current usage

GET /v1/customers/{external_id}/current_usage?subscription_id={subscription_id}

Returns the current billing-period usage for all metered charges on the specified subscription.

Past usage

GET /v1/customers/{external_id}/past_usage?external_subscription_id={sub_id}&periods_count=3

Returns usage data for completed billing periods. Use periods_count to control how many past periods are returned (default: 1).

Projected usage

GET /v1/customers/{external_id}/projected_usage?subscription_id={subscription_id}

Returns projected usage through the end of the current billing period, based on current consumption trends.

Applied coupons and add-ons

List the coupons and add-ons currently applied to a customer:

# List applied coupons
GET /v1/customers/{customer_id}/applied_coupons

# List applied add-ons
GET /v1/customers/{customer_id}/applied_add_ons

Both endpoints support pagination with skip and limit query parameters (default limit: 100, max: 1000).

Integration mappings

Customers can be linked to external systems (accounting, CRM, etc.) through integration mappings:

GET /v1/customers/{customer_id}/integration_mappings

Response:

[
  {
    "id": "mapping-uuid",
    "integration_id": "integration-uuid",
    "integration_name": "QuickBooks",
    "integration_provider": "quickbooks",
    "external_customer_id": "QB-12345",
    "settings": null,
    "created_at": "2026-01-15T10:00:00Z"
  }
]

Each mapping links a BoxBilling customer to their corresponding record in an external system.

Customer portal

Generate a self-service portal URL for a customer:

GET /v1/customers/{external_id}/portal_url

The portal gives customers access to view their subscriptions, invoices, payment methods, and usage — without needing to build a custom UI.

Relationships

Customers are connected to most major entities in BoxBilling:

Entity	Relationship
Subscriptions	A customer can have multiple active subscriptions
Invoices	Invoices are generated for a customer based on their subscriptions
Payments	Payments are made by a customer against their invoices
Wallets	Each customer can have one or more prepaid wallets
Payment methods	Saved cards, bank accounts, etc. belong to a customer
Coupons & add-ons	Applied at the customer level
Integration mappings	Link customer to external systems

Dashboard metrics

GET /dashboard/customers?start_date=2026-01-01&end_date=2026-03-08

Response:

{
  "total": 1250,
  "new_this_month": 45,
  "churned_this_month": 8,
  "new_trend": "up",
  "churned_trend": "down"
}

API endpoints

Method	Path	Description
POST	/v1/customers/	Create a customer
GET	/v1/customers/	List customers
GET	/v1/customers/{customer_id}	Get customer details
PUT	/v1/customers/{customer_id}	Update a customer
DELETE	/v1/customers/{customer_id}	Delete a customer
GET	/v1/customers/{customer_id}/health	Get customer health
GET	/v1/customers/{customer_id}/applied_coupons	List applied coupons
GET	/v1/customers/{customer_id}/applied_add_ons	List applied add-ons
GET	/v1/customers/{customer_id}/integration_mappings	List integration mappings
GET	/v1/customers/{external_id}/current_usage	Get current usage
GET	/v1/customers/{external_id}/past_usage	Get past usage
GET	/v1/customers/{external_id}/projected_usage	Get projected usage
GET	/v1/customers/{external_id}/portal_url	Generate portal URL