Platform Calculation

Changed on Nov 3, 2026

Calculate taxes for marketplace/platform transactions where a merchant is involved. Important: In this endpoint, amount is per-unit. The taxable base is calculated as amount × quantity.

post/tax/platform/calculations

Request

Base URL
https://api.numeralhq.com
URL
https://api.numeralhq.com/tax/platform/calculations
Auth
HTTP bearer

Headers

X-API-Version'2026-03-01' required

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

Request body

rolesstring[] required

Your role(s) in this transaction

transacted_atinteger

Optional top-level field. 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 sales tax holidays). If omitted, the calculation uses the current time. Available in API version 2026-03-01 and later.

default_customer_type'CONSUMER' | 'BUSINESS'

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.

Example request

{
  "customer": {
    "id": "cust_123456789",
    "tax_ids": [
      {
        "type": "us_ein",
        "value": "12-3456789"
      }
    ],
    "address": {
      "address_line_1": "3990 N County Rd 300 E",
      "address_line_2": "Unit 2",
      "address_city": "Danville",
      "address_province": "IN",
      "address_postal_code": "46122",
      "address_country": "US"
    },
    "ip": {
      "value": "217.217.113.167"
    }
  },
  "merchant": {
    "merchant_id": "my-seller-123",
    "tax_ids": [
      {
        "type": "us_ein",
        "value": "12-3456789"
      }
    ]
  },
  "order_details": {
    "customer_currency_code": "USD",
    "line_items": [
      {
        "product_category": "GENERAL_MERCHANDISE",
        "amount": 2500,
        "quantity": 3
      }
    ]
  },
  "roles": [
    "marketplace_provider"
  ],
  "fee_details": {
    "customer_currency_code": "USD",
    "line_items": [
      {
        "product_category": "GENERAL_MERCHANDISE",
        "amount": 2500,
        "quantity": 3
      }
    ]
  },
  "transacted_at": 1772323200,
  "default_customer_type": "CONSUMER"
}

Response

Platform calculation response

idstring

objectstring

testmodeboolean

customer_currency_codestring

rolesstring[]

expires_atnumber

location_source'address' | 'ip'

Which input was used for tax determination.

The precision level of the resolved location.

Example response

{
  "id": "calc_platform_123456789",
  "object": "tax.calculation",
  "location_source": "address",
  "resolution_precision": "POSTAL",
  "address_used": {
    "address_line_1": "3990 N County Rd 300 E",
    "address_line_2": "Unit 2",
    "address_city": "Danville",
    "address_province": "IN",
    "address_postal_code": "46122",
    "address_country": "US"
  }
}

Changes

Nov 3, 2026f4650eaed11f Revision changes
- breaking
  removed the enum value 2026-01-01 from the header request parameter X-API-Version
- breaking
  added to the response body oneOf list for the response status
- breaking
  the response's body type changed from object to no type for status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- info
  api operation id platformCalculation_v20260101 removed and replaced with platformCalculation_v20260301
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new enum value 2026-03-01 to the header request parameter X-API-Version
- info
  the request property / became optional
- info
  the request property / with a default value became required
- info
  the request property / with a default value became required
- info
  added the non-success response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status

Operation history