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 another platform that connects buyers and sellers. Your platform fees can be taxed separately from the order. Once the customer pays, record the sale with Create platform transactions.

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 + platform calculation id
└─ 2. Customer pays
      └─ POST /tax/platform/transactions
           send:    platform calculation id
           receive: list of transactions

Both endpoints need X-API-Version: 2026-03-01.

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 Effective tax rate.

string

Name of the tax.

string

Name of the jurisdiction, e.g. California.

string

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

string

Type of authority: 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.

enum

address or ip: which input set the location.

enum

STREET, POSTAL_PLUS, POSTAL, PROVINCE, COUNTRY, or APPROXIMATED.

object

The customer address the order was taxed for. Populated even when the location came from an IP.

string

ISO 3166-2 subdivision code.

string

ISO 3166-1 alpha-2 country code.

Always charge the returned tax_amount values. For an effective rate, divide totals.order.tax_amount by totals.order.amount_excluding_tax (or the same fields on totals.fees) rather than adding up tax_rate values.

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. Send X-API-Version: 2026-03-01. Try it in the API reference.

Parameters

object

required

Who is buying. At least one of customer.address or customer.ip is required.

object

The customer’s address.

string

ISO 3166-2 subdivision code.

string

ISO 3166-1 alpha-2 country code.

enum

shipping or billing.

object

IP address for location lookup when you don’t have a full address. See IP-based tax resolution.

string

required

A valid IPv4 or IPv6 address.

enum

default:"strict"

What to do when the IP can’t be resolved precisely enough: strict, zero, approximate, or best_effort. Numeral strongly recommends strict to stay as compliant as possible.

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

enum

default:"CONSUMER"

CONSUMER or BUSINESS.

array of objects

Tax IDs for business 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. See supported currencies.

boolean

required

Whether line item amounts already include tax.

enum

required

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 business rules still apply.

For US customer addresses, must be auto or forced. disabled is rejected because US addresses must always compute tax.

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. Taxable base is amount × quantity.

integer

required

Number of units.

string

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

string

Your product ID, as created in Numeral. See Products.

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

required

auto or disabled. forced isn’t allowed: the fee is your own sale to 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.

integer

When the sale happened, Unix seconds. Rates and rules, such as sales tax holidays, are evaluated as of this time. Defaults to now.

enum

CONSUMER or BUSINESS. Used when customer.id isn’t found in Numeral, 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-03-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-03-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": 2500, "quantity": 3, "product_category": "GENERAL_MERCHANDISE" }
      ]
    },
    "roles": ["marketplace_provider"]
  }'

curl https://api.numeralhq.com/tax/platform/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-03-01' \
  -d '{
    "customer": {
      "type": "CONSUMER",
      "ip": { "value": "217.217.113.167", "resolution": "strict" }
    },
    "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"]
  }'

# Payment processor: returns destination rates regardless of your own nexus.
curl https://api.numeralhq.com/tax/platform/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-03-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"]
  }'

# customer.id applies the customer's exemptions to the order.
# default_customer_type prices it as CONSUMER if the ID isn't in Numeral yet.
curl https://api.numeralhq.com/tax/platform/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-03-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"
  }'

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

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

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: one for the merchant’s sale, and one for the platform fee. This keeps the fee’s tax, which can be a different liability, separate from the order’s. Marketplace providers and merchants of record get one transaction with all the 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.

number

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.

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 the customer paid in.

string

Currency the tax will be filed in.

array of objects

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

timestamp

When the sale was processed.

boolean

true if made with a test API key.

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-03-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	`INVALID_IP_FORMAT`	`customer.ip.value` isn’t a valid IPv4 or IPv6 address.
404	`MERCHANT_NOT_FOUND`	`merchant.merchant_id` doesn’t exist 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.
422	`IP_RESOLUTION_FAILED`	IP couldn’t be resolved to a country (`strict` mode).
422	`IP_RESOLUTION_INSUFFICIENT_US`	IP resolved to a US state but no postal code.
422	`IP_RESOLUTION_INSUFFICIENT_CA`	IP resolved to Canada but no province.

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

{
  "code": 422,
  "type": "IP_RESOLUTION_FAILED",
  "message": "Unable to resolve IP address to a country. Please provide a full address in customer.address."
}

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