Platform

A platform calculation quotes tax for a sale where a merchant is the seller and you facilitate it. Use it if you’re a marketplace, a payment processor, or a merchant of record. Your platform fees can be taxed separately from the order. Once the customer pays, record the sale with Create platform transactions.Platform endpoints are new in 2026-01-01 and require X-API-Version: 2026-01-01.

Where platform calculations fit

Sale on your platform
├─ 1. Customer enters address
│     └─ POST /tax/platform/calculations
│          send:    customer + merchant + order (+ fees)
│          receive: order tax + fee tax + calculation id
└─ 2. Customer pays
      └─ POST /tax/platform/transactions
           send:    platform calculation id
           receive: list of transactions

Endpoints

Create a platform calculationPOST/tax/platform/calculations Create platform transactionsPOST/tax/platform/transactions

The Platform calculation object

Attributes

string

The ID of the platform calculation. Use it to create platform transactions.

string, value is "tax.calculation"

String representing the object’s type.

boolean

true if made with a test API key.

string

ISO 4217 currency code of the calculation.

object

The merchant used in this calculation.

string

The merchant’s id.

string

Your reference ID for the merchant.

array of strings

Echo of the roles you sent.

array of objects

Tax on the order, one entry per line item in order_details.

object

Product information for this line item.

string

Echo of the reference_line_item_id you sent.

string

The product ID in your system.

string

The product category used to decide taxability.

array of objects

One row per taxing jurisdiction.

number

Statutory rate for the jurisdiction, as a decimal fraction (0.0875 = 8.75%). Some rates apply to only part of the amount, so don’t sum these. See Summing tax rates.

string

Descriptive rate classification, e.g. SALES TAX.

string

Name of the jurisdiction, e.g. California.

string

Name of the tax authority, e.g. California State.

enum

STATE, COUNTY, CITY, or DISTRICT.

enum

SALES, USE, VAT, or GST.

number

Fixed fee charged by this jurisdiction.

integer

Tax for this line item, in the currency’s smallest unit.

integer

Line amount before tax (amount × quantity).

integer

amount_excluding_tax + tax_amount.

integer

Echo of the quantity you sent.

array of objects

Tax on your platform fees, one entry per line item in fee_details. Same fields as line_items. Only present when fee_details is sent.

object

Totals for the order and for the fees, kept separate.

object

Totals for line_items.

integer

Total tax on the order, in the currency’s smallest unit.

integer

Order total excluding tax.

integer

Order total including tax.

object

Totals for fee_line_items, with the same fields as totals.order. Only present when fee_details is sent.

timestamp

Unix seconds when the quoted rates expire.

Always charge the returned tax_amount. For an effective rate, divide tax_amount by amount_excluding_tax instead of adding up tax_rate values. See Summing tax rates.

The Platform calculation object

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

Create a platform calculation

Quotes tax for an order and, optionally, your platform fees on it. Try it in the API reference.

amount on every line item is the per-unit price. The taxable base is amount × quantity. For 3 items at $25.00 each, send "amount": 2500, "quantity": 3: the taxable base is $75.00.

Parameters

object

required

The buyer.

object

required

The customer’s address.

string

required

string

required

string

required

ISO 3166-2 subdivision code.

string

required

string

required

ISO 3166-1 alpha-2 country code.

enum

shipping or billing.

string

The cust_… ID or your own reference ID of a customer you created in Numeral. Applies the customer’s exemptions to the order: a tax-exempt customer gets zero tax, and exemption certificates on file for the customer apply for the destination jurisdiction. Not applied to fee_details, whose buyer is the merchant. If no customer matches, returns CUSTOMER_NOT_FOUND unless default_customer_type is sent.

enum

default:"CONSUMER"

CONSUMER or BUSINESS.

array of objects

Tax IDs for B2B sales. Each has type (e.g. gb_vat) and value. See tax IDs.

object

required

The seller. See Merchants.

string

required

The merchant’s id (merch_…) or your reference_merchant_id.

enum

default:"BUSINESS"

BUSINESS or INDIVIDUAL.

array of objects

Overrides the merchant’s stored tax IDs for this calculation.

object

required

The order.

string

required

ISO 4217 currency code, e.g. USD or EUR.

boolean

required

Whether line item amounts already include tax.

enum

default:"auto"

auto returns real rates only where you have an active tax registration, and 0 elsewhere.
disabled always returns 0.
forced returns real destination rates whatever your own registrations are. Use it as a payment processor to show the rates the merchant would owe. Only valid when roles is exactly ["payment_processor"]. Customer exemptions, reverse charge and B2B rules still apply.

For US customer addresses, must be auto or forced: disabled is rejected.

array of objects

required

One entry per product.

integer

required

Per-unit price in the currency’s smallest unit. For a $25.00 item, send 2500.

integer

required

Number of units. Taxable base is amount × quantity.

string

Tax category from the category list, e.g. GENERAL_MERCHANDISE or SAAS_GENERAL.

string

Your product ID, as created in Numeral as a product.

string

Your line item ID.

array of enums

required

Your role in this sale. One or more of:

marketplace_provider: you run a marketplace that connects buyers and sellers.
payment_processor: you process the payment.
merchant_of_record: you’re the legal seller of record.

Roles also decide how many transactions Create platform transactions records.

object

Your platform fees, taxed separately from the order. Same shape as order_details.

string

required

ISO 4217 currency code.

boolean

required

Whether fee amounts already include tax.

enum

default:"auto"

auto or disabled. forced isn’t allowed: the fee is your own tax event toward the merchant, so your own registrations apply.

array of objects

required

One entry per fee, with the same fields as order_details.line_items. amount is per unit.

enum

CONSUMER or BUSINESS. Used when customer.id isn’t found in Numeral: the order is priced with this customer type instead of returning CUSTOMER_NOT_FOUND. Lets you always send a customer ID without creating the customer first. If the customer is found, its exemptions apply as normal.

Returns

A Platform calculation object.

curl https://api.numeralhq.com/tax/platform/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -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"
        }
      ]
    }
  }'

curl https://api.numeralhq.com/tax/platform/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -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"]
  }'

curl https://api.numeralhq.com/tax/platform/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{
    "customer": {
      "id": "my-buyer-456",
      "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"],
    "default_customer_type": "CONSUMER"
  }'

Response

{
  "id": "calc_platform_987654321",
  "object": "tax.calculation",
  "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
    }
  },
  "...": "see The Platform calculation object"
}

Create platform transactions

Records the sale from a platform calculation once the customer pays. Numeral uses it for reporting and filing. Try it in the API reference.How many transactions are created depends on the roles in the calculation:

Role	Order transaction	Fee transaction
`payment_processor`	Yes, `client_role: ["payment_processor"]`	Yes, separate, `client_role: []`
`marketplace_provider`	Yes, `client_role: ["marketplace_provider"]`	No
`merchant_of_record`	Yes, `client_role: ["merchant_of_record"]`	No

Payment processors get two transactions, so the fee’s tax liability is reported separately from the order’s. Marketplace providers and merchants of record get one transaction with all order items. Fee tax, if calculated, is included in it.

Parameters

string

required

The id of the platform calculation to record.

string

required

Your unique ID for this order.

string

Your ID for the payment.

integer

When the sale was processed, as a Unix timestamp.

Returns

An object with object: "list" and a transactions array: two transactions for payment processors, one otherwise.

array of objects

The transactions created.

string

The ID of the transaction, tr_….

string, value is "tax.transaction"

String representing the object’s type.

string

The platform calculation this transaction was created from.

string

Your order ID, as sent.

string

Your payment ID, if sent.

enum

order for the sale, or fee for the platform fee. fee transactions are created for payment processors only.

array of strings

Your role for this transaction. Empty on fee transactions.

object

The merchant on the sale.

string

The merchant’s id.

string

Your reference ID for the merchant.

string

ISO 4217 currency of the transaction.

string

Currency the tax will be filed in.

array of objects

The line items, with the same fields as a transaction’s line items.

boolean

true if made with a test API key.

timestamp

When the sale was processed.

POST /tax/platform/transactions

curl https://api.numeralhq.com/tax/platform/transactions \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{
    "platform_calculation_id": "plat_calc_abc123",
    "reference_order_id": "order_12345",
    "reference_payment_id": "pay_67890",
    "transaction_processed_at": 1736300000
  }'

{
  "object": "list",
  "transactions": [
    {
      "id": "tr_abc123",
      "object": "tax.transaction",
      "calculation_id": "plat_calc_abc123",
      "reference_order_id": "order_12345",
      "type": "order",
      "client_role": ["payment_processor"],
      "merchant": {
        "id": "merch_abc123",
        "reference_merchant_id": "my-seller-123"
      },
      "testmode": false
    },
    {
      "id": "tr_def456",
      "object": "tax.transaction",
      "calculation_id": "plat_calc_abc123",
      "reference_order_id": "order_12345",
      "type": "fee",
      "client_role": [],
      "merchant": {
        "id": "merch_abc123",
        "reference_merchant_id": "my-seller-123"
      },
      "testmode": false
    }
  ]
}

{
  "object": "list",
  "transactions": [
    {
      "id": "tr_abc123",
      "object": "tax.transaction",
      "calculation_id": "plat_calc_abc123",
      "reference_order_id": "order_12345",
      "type": "order",
      "client_role": ["marketplace_provider"],
      "merchant": {
        "id": "merch_abc123",
        "reference_merchant_id": "my-seller-123"
      },
      "testmode": false
    }
  ]
}

Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.

HTTP	`type`	When
400	`MISSING_FIELD`	A required field is missing.
400	`INCORRECT_TYPE`	A field has the wrong type.
400	`UNRECOGNIZED_FIELD`	An unknown field was sent.
400	`MISSING_ORIGIN_ADDRESS`	No origin address. Check the merchant’s `default_address`.
404	`MERCHANT_NOT_FOUND`	`merchant.merchant_id` doesn’t exist, was deleted, or belongs to the other mode (test or live).
404	`CUSTOMER_NOT_FOUND`	`customer.id` doesn’t exist and no `default_customer_type` was sent.
404	`CALCULATION_NOT_FOUND`	`platform_calculation_id` doesn’t exist.

{
  "code": 404,
  "type": "MERCHANT_NOT_FOUND",
  "message": "Merchant not found or belongs to different testmode"
}

{
  "code": 404,
  "type": "CUSTOMER_NOT_FOUND",
  "message": "Unable to find customer with ID: my-buyer-456 in test environment."
}

{
  "code": 404,
  "type": "CALCULATION_NOT_FOUND",
  "message": "Platform calculation not found"
}

Getting Started

API Reference

The Platform calculation object

Attributes

Create a platform calculation

Parameters

Returns

Create platform transactions

Parameters

Returns

Errors

​The Platform calculation object

​Attributes

​Create a platform calculation

​Parameters

​Returns

​Create platform transactions

​Parameters

​Returns

​Errors

The Platform calculation object

Attributes

Create a platform calculation

Parameters

Returns

Create platform transactions

Parameters

Returns

Errors