Platform Calculations

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

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": 5000,
          "quantity": 2,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["payment_processor"],
    "fee_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "amount": 299,
          "quantity": 1,
          "product_category": "ELECTRONIC_GOODS"
        }
      ]
    }
  }'

# Returns destination-based rates regardless of the caller's own nexus.
# Use this when you (the payment processor) need to surface the rates the
# merchant would owe, without your own registration footprint gating the response.
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": "forced",
      "line_items": [
        {
          "amount": 2500,
          "quantity": 3,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["payment_processor"]
  }'

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

{
  "id": "calc_platform_987654321",
  "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": 2,
      "tax_amount": 875,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10875
    }
  ],
  "fee_line_items": [
    {
      "product": {
        "product_tax_code": "ELECTRONIC_GOODS"
      },
      "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": 1,
      "tax_amount": 26,
      "amount_excluding_tax": 299,
      "amount_including_tax": 325
    }
  ],
  "totals": {
    "order": {
      "tax_amount": 875,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10875
    },
    "fees": {
      "tax_amount": 26,
      "amount_excluding_tax": 299,
      "amount_including_tax": 325
    }
  },
  "merchant": {
    "id": "merch_abc123",
    "reference_merchant_id": "my-seller-123"
  },
  "roles": ["payment_processor"],
  "expires_at": 1735690200
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

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

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": 5000,
          "quantity": 2,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["payment_processor"],
    "fee_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "amount": 299,
          "quantity": 1,
          "product_category": "ELECTRONIC_GOODS"
        }
      ]
    }
  }'

# Returns destination-based rates regardless of the caller's own nexus.
# Use this when you (the payment processor) need to surface the rates the
# merchant would owe, without your own registration footprint gating the response.
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": "forced",
      "line_items": [
        {
          "amount": 2500,
          "quantity": 3,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["payment_processor"]
  }'

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

{
  "id": "calc_platform_987654321",
  "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": 2,
      "tax_amount": 875,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10875
    }
  ],
  "fee_line_items": [
    {
      "product": {
        "product_tax_code": "ELECTRONIC_GOODS"
      },
      "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": 1,
      "tax_amount": 26,
      "amount_excluding_tax": 299,
      "amount_including_tax": 325
    }
  ],
  "totals": {
    "order": {
      "tax_amount": 875,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10875
    },
    "fees": {
      "tax_amount": 26,
      "amount_excluding_tax": 299,
      "amount_including_tax": 325
    }
  },
  "merchant": {
    "id": "merch_abc123",
    "reference_merchant_id": "my-seller-123"
  },
  "roles": ["payment_processor"],
  "expires_at": 1735690200
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

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

string

required

Bearer token authentication.

string

required

Must be 2026-01-01 for platform calculations.

Request Body

object

required

The customer (buyer) information.

Show Customer Properties

string

default:"CONSUMER"

Either CONSUMER or BUSINESS.

array

Array of customer tax IDs (for B2B transactions).

object

required

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

object

required

The merchant (seller) involved in this transaction.

Show Merchant Properties

string

required

The merchant ID (merch_xxx) or your reference_merchant_id.

string

default:"BUSINESS"

Either BUSINESS or INDIVIDUAL.

array

Override merchant’s stored tax IDs for this calculation.

object

required

Order details including line items.

Show Order Details Properties

string

required

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

boolean

required

Whether the amount includes 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.

array

required

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

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

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

integer

required

Per-unit price in the smallest currency unit (e.g., cents for USD).For a $25.00 item: amount: 2500

integer

required

Number of units. The taxable base = amount × quantity.

string

Tax category code (e.g., GENERAL_MERCHANDISE, SAAS_GENERAL).

string

Reference to a pre-created product.

string

Your ID for this line item.

Response

string

The calculation ID.

string

Always tax.calculation.

array

Tax calculations for order line items.

array

Tax calculations for fee line items (only present when fee_details provided).

object

Summary totals for order and fees.

Show Totals Properties

object

Order totals: tax_amount, amount_excluding_tax, amount_including_tax.

object

Fee totals (only present when fee_details provided).

object

The merchant used in this calculation.

array

The roles you specified.

Enhanced Response Fields

Platform calculations include additional tax jurisdiction details:

string

Name of the tax authority (e.g., “California State”).

string

Type of authority: STATE, COUNTY, CITY, or DISTRICT.

string

Type of tax: SALES, USE, VAT, or GST.

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

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": 5000,
          "quantity": 2,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["payment_processor"],
    "fee_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "amount": 299,
          "quantity": 1,
          "product_category": "ELECTRONIC_GOODS"
        }
      ]
    }
  }'

# Returns destination-based rates regardless of the caller's own nexus.
# Use this when you (the payment processor) need to surface the rates the
# merchant would owe, without your own registration footprint gating the response.
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": "forced",
      "line_items": [
        {
          "amount": 2500,
          "quantity": 3,
          "product_category": "GENERAL_MERCHANDISE"
        }
      ]
    },
    "roles": ["payment_processor"]
  }'

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

{
  "id": "calc_platform_987654321",
  "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": 2,
      "tax_amount": 875,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10875
    }
  ],
  "fee_line_items": [
    {
      "product": {
        "product_tax_code": "ELECTRONIC_GOODS"
      },
      "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": 1,
      "tax_amount": 26,
      "amount_excluding_tax": 299,
      "amount_including_tax": 325
    }
  ],
  "totals": {
    "order": {
      "tax_amount": 875,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10875
    },
    "fees": {
      "tax_amount": 26,
      "amount_excluding_tax": 299,
      "amount_including_tax": 325
    }
  },
  "merchant": {
    "id": "merch_abc123",
    "reference_merchant_id": "my-seller-123"
  },
  "roles": ["payment_processor"],
  "expires_at": 1735690200
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

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

Platform calculation response

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

⌘I

Get Started

AI help

Integration FAQs

Essentials

Objects

API Reference

Platform Calculations

Headers

Request Body

Line Item Properties

Response

Enhanced Response Fields

Authorizations

Headers

Body

Response

​Headers

​Request Body

​Line Item Properties

​Response

​Enhanced Response Fields

Authorizations

Headers

Body

Response

Headers

Request Body

Line Item Properties

Response

Enhanced Response Fields