Public
Calculate Tax
Calculate taxes for an upcoming checkout based on the merchant configuration and the prospect's address. Requires a publishable key and returns a tax breakdown that can be echoed back into /public/payment-init.
Request Body
application/json
lumenPublishableKey*string
Match
^pk_[A-Za-z0-9]+planId*string
Match
^plan_int_[A-Za-z0-9]{22}$priceId*string
Match
^price_[A-Za-z0-9]{22}$subtotalCents*integer
Range
0 <= valuecurrency*string
3-letter currency code
Match
^[A-Za-z]{3}$customerCountry?string|null
ISO 2-letter country code of the buyer
customerStateProvince?string|null
State/province for tax calculation (required for US addresses)
taxId?string|null
Tax identifier for B2B calculation
businessName?string|null
Business name for B2B calculation
Response Body
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/public/calculate-tax" \ -H "Content-Type: application/json" \ -d '{ "lumenPublishableKey": "pk_test_3yJQYvdr5X6b2F4T9aLk", "planId": "plan_int_6FJ7xXk8Qp9zR2tSa1BcDe", "priceId": "price_6FJ7xXk8Qp9zR2tSa1BcDe", "subtotalCents": 12000, "currency": "USD", "customerCountry": "US", "customerStateProvince": "CA", "taxId": "US123456789", "businessName": "Acme Inc." }'{
"success": true,
"taxCalculation": {
"subtotalCents": 12000,
"taxAmountCents": 1020,
"totalAmountCents": 13020,
"effectiveTaxRate": 0.085,
"jurisdiction": "US-CA",
"calculationMethod": "auto",
"taxLineItems": [
{
"type": "tax",
"description": "CA state tax (8.5%)",
"subtotalCents": 1020,
"taxMetadata": {
"taxAuthority": "CA FTB",
"taxType": "sales_tax",
"jurisdiction": "US-CA",
"taxRate": 0.085,
"rateSource": "auto",
"reasonCode": 1,
"fullDescription": "Automatic CA sales tax"
},
"billingPeriodStart": "2025-02-20T00:00:00.000Z",
"billingPeriodEnd": "2025-02-20T00:00:00.000Z"
}
]
}
}{
"error": "Invalid Lumen publishable key"
}{
"error": "Failed to calculate taxes",
"details": "Merchant not found"
}