---
title: "Platform Calculation"
method: POST
path: "/tax/platform/calculations"
---

# Platform Calculation

`POST /tax/platform/calculations`

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`.**

## Headers

- `X-API-Version` '2026-01-01', required

## Request body

- PlatformCalculationRequest — Request body for platform/marketplace tax calculations
  - `customer` PlatformCustomer, required
    - `type` 'CONSUMER' | 'BUSINESS' — The type of customer
    - `tax_ids` TaxId[]
      - `type` string, required — Country-specific Stripe-style tax ID type (e.g., `us_ein`, `eu_vat`, `gb_vat`, `au_abn`, `ca_gst_hst`). See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
      - `value` string, required — The tax ID value (1-100 characters).
    - `address` object, required
      - `address_line_1` string, required
      - `address_line_2` string
      - `address_city` string, required
      - `address_province` string, required — The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code.
      - `address_postal_code` string, required
      - `address_country` string, required — The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.
      - `address_type` 'shipping' | 'billing'
  - `merchant` PlatformMerchant, required — The merchant (seller) involved in this platform transaction
    - `merchant_id` string, required — The merchant ID (merch_xxx) or your reference_merchant_id
    - `type` 'BUSINESS' | 'INDIVIDUAL' — The merchant's business type
    - `tax_ids` TaxId[] — Override merchant's stored tax IDs for this calculation
      - `type` string, required — Country-specific Stripe-style tax ID type (e.g., `us_ein`, `eu_vat`, `gb_vat`, `au_abn`, `ca_gst_hst`). See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
      - `value` string, required — The tax ID value (1-100 characters).
  - `order_details` PlatformOrderDetails, required
    - `customer_currency_code` string, required
    - `tax_included_in_amount` boolean, required
    - `automatic_tax` 'auto' | 'disabled' | 'forced' — Controls automatic tax behavior for order line items. `auto`: return real rates only in jurisdictions where you have an active tax registration. `disabled`: always return 0 tax rates regardless of registration status. `forced`: return real destination-based rates regardless of your own nexus/registration status — for use by payment processors that need to surface merchant-applicable rates without their own collection configuration gating the response. `forced` is only valid when `roles` is exactly `["payment_processor"]`.
    - `line_items` PlatformLineItem[], required
      - `reference_line_item_id` string — Your ID for this line item
      - `reference_product_id` string — Reference to a pre-created product
      - `product_category` string — Tax category code
      - `amount` integer, required — **PER-UNIT price** in smallest currency unit. For $25.00 items, use 2500. Total taxable = amount × quantity.
      - `quantity` integer, required — Number of units. Taxable base = amount × quantity.
  - `roles` string[], required — Your role(s) in this transaction
  - `fee_details` PlatformFeeDetails — Details for platform fees to be taxed separately. Same shape as `order_details`, but `automatic_tax` cannot be `forced` — fees represent the platform's own tax event toward the merchant and must honor the platform's own nexus configuration.
    - `customer_currency_code` string, required
    - `tax_included_in_amount` boolean, required
    - `automatic_tax` 'auto' | 'disabled' — Controls automatic tax behavior for fee line items. `auto`: return real rates only in jurisdictions where you have an active tax registration. `disabled`: always return 0 tax rates regardless of registration status.
    - `line_items` PlatformLineItem[], required
      - `reference_line_item_id` string — Your ID for this line item
      - `reference_product_id` string — Reference to a pre-created product
      - `product_category` string — Tax category code
      - `amount` integer, required — **PER-UNIT price** in smallest currency unit. For $25.00 items, use 2500. Total taxable = amount × quantity.
      - `quantity` integer, required — Number of units. Taxable base = amount × quantity.

## Response `200`

Platform calculation response

- PlatformCalculationResponse
  - `id` string
  - `object` string
  - `testmode` boolean
  - `customer_currency_code` string
  - `line_items` PlatformCalculationLineItem[]
    - `product` object
      - `reference_product_id` string
      - `reference_line_item_id` string
      - `product_tax_code` string
    - `tax_jurisdictions` object[]
      - `tax_rate` number
      - `rate_type` string
      - `jurisdiction_name` string
      - `tax_authority_name` string — Name of the tax authority
      - `tax_authority_type` string — Type of authority (STATE, COUNTY, CITY, DISTRICT)
      - `tax_type` string — Type of tax (SALES, USE, VAT, GST)
      - `fee_amount` number
    - `quantity` integer
    - `tax_amount` integer
    - `amount_excluding_tax` integer
    - `amount_including_tax` integer
  - `fee_line_items` PlatformCalculationLineItem[] — Tax calculations for platform fees (only present when fee_details provided)
    - `product` object
      - `reference_product_id` string
      - `reference_line_item_id` string
      - `product_tax_code` string
    - `tax_jurisdictions` object[]
      - `tax_rate` number
      - `rate_type` string
      - `jurisdiction_name` string
      - `tax_authority_name` string — Name of the tax authority
      - `tax_authority_type` string — Type of authority (STATE, COUNTY, CITY, DISTRICT)
      - `tax_type` string — Type of tax (SALES, USE, VAT, GST)
      - `fee_amount` number
    - `quantity` integer
    - `tax_amount` integer
    - `amount_excluding_tax` integer
    - `amount_including_tax` integer
  - `totals` object
    - `order` TotalsSummary
      - `tax_amount` integer — Total tax in smallest currency unit
      - `amount_excluding_tax` integer — Total before tax
      - `amount_including_tax` integer — Total including tax
    - `fees` TotalsSummary
      - `tax_amount` integer — Total tax in smallest currency unit
      - `amount_excluding_tax` integer — Total before tax
      - `amount_including_tax` integer — Total including tax
  - `merchant` object
    - `id` string
    - `reference_merchant_id` string
  - `roles` string[]
  - `expires_at` number

## Other responses

- `400` — Validation error
- `404` — Merchant not found

---

[API](https://skmtc.net/numeral-com/apis/numeral-api.md) · [All operations](https://skmtc.net/numeral-com/apis/numeral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral-com/numeral-api/revisions/f0af51c3f9b9/schema)