Lumen Documentation

This guide explains Lumen’s tax model and how to configure it quickly. It covers B2B scope, the setup wizard, core API endpoints, previewing taxes, and how taxes apply during billing.

Key points:

B2B scope: If a customer lacks business identifiers (no taxId and no businessName), tax is 0% and no tax lines are added.
Two modes: automatic calculation or manual rates. Customer overrides and exemptions are supported.
Taxes are computed after credits and included on invoices automatically.

1) Quick setup (UI)

Go to /tax in the dashboard and complete the wizard.
Completion requires either:
- autoTaxCalculation = true, or
- a defaultTaxRate (e.g., 0.0875 for 8.75%).
For US merchants choosing automatic calculation, you should add state nexus as needed.

2) Configure via API

Get current config:

curl -X GET "https://api.getlumen.dev/v1/tax/config" \
  -H "Authorization: Bearer $LUMEN_API_KEY"

Update config (choose one mode):

# Automatic calculation
curl -X POST "https://api.getlumen.dev/v1/tax/config/update" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autoTaxCalculation": true,
    "defaultTaxRate": null
  }'

# Manual default rate (0–1 decimal string)
curl -X POST "https://api.getlumen.dev/v1/tax/config/update" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autoTaxCalculation": false,
    "defaultTaxRate": "0.0875"
  }'

US nexus (automatic mode):

# List nexus configs
curl -X GET "https://api.getlumen.dev/v1/tax/nexus" \
  -H "Authorization: Bearer $LUMEN_API_KEY"

# Upsert nexus for CA (use 2-letter codes)
curl -X POST "https://api.getlumen.dev/v1/tax/nexus/CA/update" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hasPhysicalPresence": true,
    "economicNexus": true
  }'

Manual rate definitions (manual mode):

# List definitions
curl -X GET "https://api.getlumen.dev/v1/tax/rate-definitions" \
  -H "Authorization: Bearer $LUMEN_API_KEY"

# Create a definition (taxRate is a decimal string in 0–1)
curl -X POST "https://api.getlumen.dev/v1/tax/rate-definitions/create" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EU Standard",
    "taxRate": "0.20",
    "jurisdiction": "EU"
  }'

Registrations (record-keeping):

# List registrations
curl -X GET "https://api.getlumen.dev/v1/tax/registrations" \
  -H "Authorization: Bearer $LUMEN_API_KEY"

# Create a registration
curl -X POST "https://api.getlumen.dev/v1/tax/registrations/create" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "DE",
    "registrationId": "DE123456789"
  }'

3) Preview taxes

Use the preview endpoint to test calculation for a specific customer and amount.

curl -X POST "https://api.getlumen.dev/v1/tax/calculate-preview" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_123",
    "amount": 10000,
    "currency": "USD",
    "lineItems": [
      {
        "type": "fixed",
        "description": "Base",
        "subtotalCents": 10000,
        "billingPeriodStart": "2024-01-01T00:00:00Z",
        "billingPeriodEnd": "2024-02-01T00:00:00Z"
      }
    ]
  }'

4) How billing applies tax

Credits are applied first, then tax is calculated on the remaining amount.
Automatic mode selects a jurisdiction and computes US/EU/UK/CA or cross‑border rules.
Manual mode uses the customer’s assigned rate definition if present, otherwise the merchant default rate.
If taxExempt is true for a customer, taxes are skipped with an exemption reason.
If a customer lacks business identifiers, taxes are 0% and no tax line items are added.

Taxes

1) Quick setup (UI)

2) Configure via API

3) Preview taxes

4) How billing applies tax

On this page