Skip to main content
POST
/
tax
/
platform
/
calculations
curl -X POST https://api.numeralhq.com/tax/platform/calculations \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "address": {
        "address_line_1": "100 Market St",
        "address_city": "San Francisco",
        "address_province": "CA",
        "address_postal_code": "94105",
        "address_country": "US"
      }
    },
    "merchant": {
      "merchant_id": "my-seller-123"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "amount": 2500,
          "quantity": 3,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["marketplace_provider"]
  }'

{
  "id": "calc_platform_123456789",
  "object": "tax.calculation",
  "testmode": true,
  "customer_currency_code": "USD",
  "line_items": [
    {
      "product": {
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0875,
          "rate_type": "SALES TAX",
          "jurisdiction_name": "California",
          "tax_authority_name": "California State",
          "tax_authority_type": "STATE",
          "tax_type": "SALES",
          "fee_amount": 0
        }
      ],
      "quantity": 3,
      "tax_amount": 656,
      "amount_excluding_tax": 7500,
      "amount_including_tax": 8156
    }
  ],
  "totals": {
    "order": {
      "tax_amount": 656,
      "amount_excluding_tax": 7500,
      "amount_including_tax": 8156
    }
  },
  "merchant": {
    "id": "merch_abc123",
    "reference_merchant_id": "my-seller-123"
  },
  "roles": ["marketplace_provider"],
  "expires_at": 1735690200
}
Calculate taxes for marketplace/platform transactions where a merchant (seller) is involved. This endpoint is designed for marketplaces, payment processors, and other platforms that facilitate transactions between buyers and sellers.
Important: Amount is Per-UnitIn platform calculations, the amount field represents the per-unit price. The taxable base is calculated as:
taxable_base = amount × quantity
This is different from the standard /calculations endpoint where amount is the total line item value.

​
Headers

​
Authorization
string
required
Bearer token authentication.
​
X-API-Version
string
required
Must be 2026-03-01 for platform calculations.

​
Request Body

​
customer
object
required
The customer (buyer) information.
​
merchant
object
required
The merchant (seller) involved in this transaction.
​
order_details
object
required
Order details including line items.
​
roles
array
required
Your role(s) in this transaction. One or more of:
  • marketplace_provider - You operate a marketplace connecting buyers and sellers
  • payment_processor - You process payments for the transaction
  • merchant_of_record - You are the legal seller of record
​
fee_details
object
Optional: Details for platform fees to be taxed separately. Same structure as order_details.

​
Line Item Properties

​
amount
integer
required
Per-unit price in the smallest currency unit (e.g., cents for USD).For a $25.00 item: amount: 2500
​
quantity
integer
required
Number of units. The taxable base = amount × quantity.
​
product_category
string
Tax category code (e.g., GENERAL_MERCHANDISE, SAAS_GENERAL).
​
reference_product_id
string
Reference to a pre-created product.
​
reference_line_item_id
string
Your ID for this line item.

​
Response

​
id
string
The calculation ID.
​
object
string
Always tax.calculation.
​
line_items
array
Tax calculations for order line items.
​
fee_line_items
array
Tax calculations for fee line items (only present when fee_details provided).
​
totals
object
Summary totals for order and fees.
​
merchant
object
The merchant used in this calculation.
​
roles
array
The roles you specified.

​
Enhanced Response Fields

Platform calculations include additional tax jurisdiction details:
​
tax_authority_name
string
Name of the tax authority (e.g., “California State”).
​
tax_authority_type
string
Type of authority: STATE, COUNTY, CITY, or DISTRICT.
​
tax_type
string
Type of tax: SALES, USE, VAT, or GST.

​
IP Resolution Response Fields

​
location_source
string
"address" or "ip" — indicates which input was used for tax determination.
​
resolution_precision
string
Precision of the resolved location: STREET, POSTAL_PLUS, POSTAL, PROVINCE, COUNTRY, or APPROXIMATED.
​
address_used
object
The address actually used for tax calculation, populated even when using IP-based resolution.
curl -X POST https://api.numeralhq.com/tax/platform/calculations \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "address": {
        "address_line_1": "100 Market St",
        "address_city": "San Francisco",
        "address_province": "CA",
        "address_postal_code": "94105",
        "address_country": "US"
      }
    },
    "merchant": {
      "merchant_id": "my-seller-123"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "amount": 2500,
          "quantity": 3,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["marketplace_provider"]
  }'

{
  "id": "calc_platform_123456789",
  "object": "tax.calculation",
  "testmode": true,
  "customer_currency_code": "USD",
  "line_items": [
    {
      "product": {
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0875,
          "rate_type": "SALES TAX",
          "jurisdiction_name": "California",
          "tax_authority_name": "California State",
          "tax_authority_type": "STATE",
          "tax_type": "SALES",
          "fee_amount": 0
        }
      ],
      "quantity": 3,
      "tax_amount": 656,
      "amount_excluding_tax": 7500,
      "amount_including_tax": 8156
    }
  ],
  "totals": {
    "order": {
      "tax_amount": 656,
      "amount_excluding_tax": 7500,
      "amount_including_tax": 8156
    }
  },
  "merchant": {
    "id": "merch_abc123",
    "reference_merchant_id": "my-seller-123"
  },
  "roles": ["marketplace_provider"],
  "expires_at": 1735690200
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-API-Version
enum<string>
required

API version. Must be 2026-01-01 for platform calculations.

Available options:
2026-01-01

Body

application/json

Request body for platform/marketplace tax calculations

​
customer
object
required
​
merchant
object
required

The merchant (seller) involved in this platform transaction

​
order_details
object
required
​
roles
enum<string>[]
required

Your role(s) in this transaction

Available options:
marketplace_provider,
payment_processor,
merchant_of_record
Example:
["marketplace_provider"]
​
fee_details
object

Optional: Details for platform fees to be taxed separately

Response

Platform calculation response

​
id
string
Example:

"calc_platform_123456789"

​
object
string
Example:

"tax.calculation"

​
testmode
boolean
​
customer_currency_code
string
​
line_items
object[]
​
fee_line_items
object[]

Tax calculations for platform fees (only present when fee_details provided)

​
totals
object
​
merchant
object
​
roles
string[]
​
expires_at
number