Platform Calculations

Calculate taxes for marketplace and platform transactions

POST /tax/platform/calculations

Basic Marketplace

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"]
  }'

200 - Basic Response

{
  "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.

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.

Show Customer Properties

id · string

The customer (buyer) ID: the cust_xxx ID or your own reference ID of a customer created in Numeral. When provided, the customer’s exemption status is applied to the order: a globally tax-exempt customer returns zero tax, and exemption certificates on file for the customer are applied for the destination jurisdiction. Not applied to fee_details, whose buyer is the merchant.

If no customer matches, the request returns 404 customer_not_found unless default_customer_type is set.

type · string · default: "CONSUMER"

Either CONSUMER or BUSINESS.

tax_ids · array

Array of customer tax IDs (for B2B transactions).

address · object

Customer’s address including address_type (shipping or billing). At least one of address or ip must be provided.

ip · object

Customer IP address for geo-based tax resolution. At least one of address or ip must be provided.

Show IP Properties

value · string · required

A valid IPv4 or IPv6 address.

resolution · string · default: "strict"

Resolution strategy: strict, zero, approximate, or best_effort. Numeral strongly recommends strict mode to stay as compliant as possible.

merchant · object · required

The merchant (seller) involved in this transaction.

Show Merchant Properties

merchant_id · string · required

The merchant ID (merch_xxx) or your reference_merchant_id.

type · string · default: "BUSINESS"

Either BUSINESS or INDIVIDUAL.

tax_ids · array

Override merchant’s stored tax IDs for this calculation.

order_details · object · required

Order details including line items.

Show Order Details Properties

customer_currency_code · string · required

ISO 4217 currency code (e.g., USD, EUR).

tax_included_in_amount · boolean · required

Whether the amount includes tax.

automatic_tax · string · required

One of auto, disabled, or forced. Required from API version 2025-05-12+.

• auto - Return real rates only in jurisdictions where you have an active tax registration. Returns 0 elsewhere.
• disabled - Always return 0 tax rates regardless of registration status.
• forced - Return real destination-based rates regardless of your own nexus/registration status. Useful for payment processors that need to surface the rates a merchant would owe without their own collection configuration gating the response. Only valid when roles is exactly ["payment_processor"]. Customer-level rules (exemptions, reverse-charge, B2B logic) still apply.

For US customer addresses, automatic_tax must be auto or forced — disabled is rejected because US addresses must always compute tax.

line_items · array · required

Array of line items. Remember: amount is per-unit!

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, except automatic_tax only accepts auto or disabled — fees represent the platform’s own tax event toward the merchant and must honor the platform’s own nexus configuration.

transacted_at · integer

Optional. The time the transaction occurred, as a Unix timestamp in seconds. Used to determine which tax rates and rules apply at the time of the transaction (for example, during a sales tax holiday). If omitted, the calculation uses the current time.

default_customer_type · string

Optional. CONSUMER or BUSINESS. Used when customer.id is provided but no matching customer exists in Numeral: the order is priced with this customer type instead of failing with customer_not_found. Lets you always pass a customer ID without first ensuring the customer has been created. If the customer is found, its exemptions apply as normal.

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.

Show Totals Properties

order · object

Order totals: tax_amount, amount_excluding_tax, amount_including_tax.

fees · object

Fee totals (only present when fee_details provided).

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.

Caution about simply summing tax_rate values. Each tax_rate in tax_jurisdictions is the statutory rate for that jurisdiction, and in some jurisdictions a rate applies to only part of the line item amount. Tennessee’s single article rules are the common example: local rates apply only to the first $1,600 of an item, and the 2.75% state single article rate applies only to the portion between $1,600 and $3,200. For a $10,000 item the returned rates sum to 12.25%, but the tax due is $788, an effective rate of 7.88%.

Always charge the returned tax_amount (or total_tax_amount). If you need an effective rate, compute tax_amount / amount_excluding_tax from the response rather than adding up tax_rate values. The per-jurisdiction tax_due_decimal field shows how much each jurisdiction actually contributed.

Basic Marketplace

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"]
  }'

200 - Basic Response

{
  "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

Show child attributes

merchant · object · required

The merchant (seller) involved in this platform transaction

Show child attributes

order_details · object · required

Show child attributes

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

Show child attributes

default_customer_type · enum<string>

Optional fallback customer type used when customer.id is provided but no matching customer exists in Numeral. Lets platforms always pass a customer ID without first ensuring the customer has been created. When the lookup misses, this value is used as the customer type for the order instead of failing with customer_not_found. If a matching customer is found, the customer's exemptions apply as normal.

Available options: CONSUMER, BUSINESS

Example:

"CONSUMER"

Response

200

application/json

Platform calculation response

id · string

Example:

"calc_platform_123456789"

object · string

Example:

"tax.calculation"

testmode · boolean

customer_currency_code · string

line_items · object[]

Show child attributes

fee_line_items · object[]

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

Show child attributes

totals · object

Show child attributes

merchant · object

Show child attributes

roles · string[]

expires_at · number