Tax
Preview taxes for a customer
Run the internal tax engine for a customer before invoicing to see jurisdiction, applied rates, and calculated tax line items.
Authorization
bearerAuth AuthorizationBearer <token>
Use your secret API key as the bearer token
In: header
Request Body
application/json
customerId*string
Customer ID to calculate tax for
Match
^cus_[A-Za-z0-9]{22}$amount*integer
Subtotal amount in cents after credits
Range
1 <= valuecurrency*string
3-letter currency code
Match
^[A-Za-z]{3}$lineItems?
Optional itemized lines to attribute taxes to. Defaults to a single line.
Response Body
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/tax/calculate-preview" \ -H "Content-Type: application/json" \ -d '{ "customerId": "cus_2NBfE7r9qWuZpA1DcVRsYh", "amount": 12000, "currency": "USD", "lineItems": [ { "type": "recurring", "description": "Pro plan", "subtotalCents": 12000, "priceId": "price_7sT59pRCb6UD3AXH2zWpNa", "billingPeriodStart": "2025-02-20T00:00:00.000Z", "billingPeriodEnd": "2025-03-20T00:00:00.000Z" } ] }'{
"taxableAmount": 12000,
"totalTaxCents": 1020,
"effectiveTaxRate": 0.085,
"jurisdiction": "US-CA",
"calculationMethod": "auto",
"taxBreakdown": {
"stateTax": 1020
},
"taxLineItems": [
{
"type": "tax",
"description": "CA sales tax (8.5%)",
"subtotalCents": 1020,
"taxMetadata": {
"taxAuthority": "US-CA",
"taxType": "sales_tax",
"jurisdiction": "US-CA",
"taxRate": 0.085,
"reasonCode": 7,
"fullDescription": "State sales tax applied"
},
"billingPeriodStart": "2025-02-20T00:00:00.000Z",
"billingPeriodEnd": "2025-03-20T00:00:00.000Z"
}
]
}{
"error": [
{
"code": "invalid_string",
"message": "Invalid public key format",
"path": [
"customerId"
]
}
]
}{
"error": "Internal server error"
}