The calculation object contains tax rate information with enhanced support for business-to-business (B2B) transactions. A calculation also includes a calculation_id that you’ll use to record a transaction for filing.

​
When to create Calculations

Calculations should be used any time you need to calculate sales tax before charging a customer for a transaction. Most e-commerce clients will submit a POST to /tax/calculations during their checkout flow after the end customer has submitted their address, but before collecting payment. core flow

​
How to create Calculations

We return both the aggregate tax information as well as a detailed breakdown for each line item. Many users will just use the total_tax_amount to identify what to charge a user, but you will always have the details as you need them.

​
Request Parameters

​
Customer Object (Enhanced)

{
  "customer": {
    "id": "cus_123456789", // Optional customer ID
    "address": {
      "address_line_1": "10 Downing Street",
      "address_line_2": "", // Optional
      "address_city": "London",
      "address_province": "Greater London",
      "address_postal_code": "SW1A 2AA",
      "address_country": "GB",
      "address_type": "shipping" // "shipping" or "billing"
    },
    "type": "BUSINESS", // "BUSINESS" or "CONSUMER" (default if omitted)
    "tax_ids": [ // Required for BUSINESS, not allowed for CONSUMER
      {
        "type": "VAT", // "VAT" or "GST"
        "value": "GB123456789"
      }
    ]
  }
}
New Fields in 2025-05-12:
  • type (string): Customer type affecting tax calculation
    • CONSUMER (default) - Individual consumer, standard B2C tax calculations
    • BUSINESS - Business entity requiring tax IDs for B2B tax logic
  • tax_ids (array): Required for BUSINESS customers, not allowed for CONSUMER customers
    • type (string): Tax ID type (VAT or GST)
    • value (string): Valid tax identification number

​
Order Details (Enhanced)

{
  "order_details": {
    "customer_currency_code": "GBP", // Supports 32 currencies
    "tax_included_in_amount": false,
    "automatic_tax": "auto", // New field for tax control
    "line_items": [
      {
        "reference_line_item_id": "line_123456789", // Optional
        "reference_product_id": "p-1233543", // Required if no product_category
        "product_category": "SAAS_GENERAL", // Required if no reference_product_id
        "amount": 200, // In currency's smallest unit (e.g., cents for USD, whole units for JPY)
        "quantity": 2
      }
    ]
  }
}
New Fields in 2025-05-12:
  • automatic_tax (string): Controls tax collection and registration behavior
    • auto - Return tax rates everywhere you have an active registration
    • disabled - Always return 0 tax regardless of thresholds

​
Enhanced Features in 2025-05-12

​
Customer Types and B2B Logic

The 2025-05-12 version introduces business-to-business (B2B) tax logic through customer types:
  • BUSINESS customers: Must provide valid tax IDs, enabling B2B tax exemptions and reverse charge mechanisms in applicable jurisdictions
  • CONSUMER customers: Standard B2C tax calculations without tax ID requirements. This is the default if the type field is omitted.

​
Tax ID Validation

When using customer.type: "BUSINESS", tax IDs are validated in real-time:
  • VAT IDs: Validated against European VIES database
  • GST IDs: Validated for applicable countries
  • Invalid tax IDs will result in calculation errors

​
Automatic Tax Configuration

The automatic_tax setting provides granular control over tax collection:
SettingTax Rates ReturnedRegistration TriggeredUse Case
auto✅ Where you have active registration❌ NoStandard operation
disabled❌ Always 0❌ NoTax-exempt scenarios

​
Enhanced Currency Support

The 2025-05-12 version supports 32 currencies (22 additional beyond the original 10), enabling global tax calculations across major markets including GBP, AUD, JPY, SGD, and many others.

​
Further documentation

The full documentation for creating calculations is on this page.