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-01-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-01-01 for platform calculations.

Request Body

customer · object · required

The customer (buyer) information.

Show Customer Properties

type · string · default: "CONSUMER"

Either CONSUMER or BUSINESS.

tax_ids · array

Array of customer tax IDs (for B2B transactions).

address · object · required

Customer’s address including address_type (shipping or billing).

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 · default: "auto"

One of auto, disabled, or forced.

• 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.

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.

Basic Marketplace

curl -X POST https://api.numeralhq.com/tax/platform/calculations \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-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

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