> ## Documentation Index > Fetch the complete documentation index at: https://docs.numeral.com/llms.txt > Use this file to discover all available pages before exploring further. # Platform Calculations > Calculate taxes for marketplace and platform transactions 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. > [!NOTE] > > **New in 2026-11-01:** > > * Every `tax_jurisdictions` row in `line_items` and `fee_line_items` has a [`note`](https://docs.numeral.com/v2026-11-01/objects/calculations#notes) that says why it came out the way it did. > * `totals.order.effective_tax_rate`, and `totals.fees.effective_tax_rate` when `fee_details` is sent. Each is that bucket's `tax_amount / amount_excluding_tax`. There's no combined order-plus-fees rate. > > The order and the fees are taxed separately, so their rows can come from different states. In the "With Fees" example below, the order is taxed where the customer is (Colorado) and the fee where the merchant is (California). ## Headers **Authorization** `string` *required* Bearer token authentication. **X-API-Version** `string` *required* API version, e.g. `2026-11-01`. Overrides your account's default version for this request. ## Request Body **customer** `object` *required* The customer (buyer) information. **Customer Properties** **id** `string` The customer (buyer) ID: the `cust_xxx` ID or your own reference ID of a customer created in Numeral. When provided, the customer's exemption status is applied to the order: a globally tax-exempt customer returns zero tax, and exemption certificates on file for the customer are applied for the destination jurisdiction. Not applied to `fee_details`, whose buyer is the merchant. If no customer matches, the request returns `404 customer_not_found` unless `default_customer_type` is set. **type** `string` (default: CONSUMER) Either `CONSUMER` or `BUSINESS`. **tax\_ids** `array` Array of customer tax IDs (for B2B transactions). **address** `object` Customer's address including `address_type` (shipping or billing). At least one of `address` or `ip` must be provided. **ip** `object` Customer IP address for geo-based tax resolution. At least one of `address` or `ip` must be provided. **IP Properties** **value** `string` *required* A valid IPv4 or IPv6 address. **resolution** `string` (default: strict) Resolution strategy: `strict`, `zero`, `approximate`, or `best_effort`. Numeral strongly recommends `strict` mode to stay as compliant as possible. **merchant** `object` *required* The merchant (seller) involved in this transaction. **Merchant Properties** **merchant\_id** `string` *required* The merchant ID (`merch_xxx`) or your `reference_merchant_id`. **type** `string` (default: BUSINESS) Either `BUSINESS` or `INDIVIDUAL`. **tax\_ids** `array` Override merchant's stored tax IDs for this calculation. **order\_details** `object` *required* Order details including line items. **Order Details Properties** **customer\_currency\_code** `string` *required* ISO 4217 currency code (e.g., `USD`, `EUR`). **tax\_included\_in\_amount** `boolean` *required* Whether the amount includes tax. **automatic\_tax** `string` *required* One of `auto`, `disabled`, or `forced`. **Required from API version 2025-05-12+**. * `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. > [!NOTE] > > For US customer addresses, `automatic_tax` must be `auto` or `forced` — `disabled` is rejected because US addresses must always compute tax. **line\_items** `array` *required* Array of line items. **Remember: amount is per-unit!** **roles** `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 **fee\_details** `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. **transacted\_at** `integer` Optional. 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 a sales tax holiday). If omitted, the calculation uses the current time. **default\_customer\_type** `string` Optional. `CONSUMER` or `BUSINESS`. Used when `customer.id` is provided but no matching customer exists in Numeral: the order is priced with this customer type instead of failing with `customer_not_found`. Lets you always pass a customer ID without first ensuring the customer has been created. If the customer is found, its exemptions apply as normal. ## Line Item Properties **amount** `integer` *required* **Per-unit price** in the smallest currency unit (e.g., cents for USD). For a \$25.00 item: `amount: 2500` **quantity** `integer` *required* Number of units. The taxable base = `amount × quantity`. **product\_category** `string` Tax category code (e.g., `GENERAL_MERCHANDISE`, `SAAS_GENERAL`). **reference\_product\_id** `string` Reference to a pre-created product. **reference\_line\_item\_id** `string` Your ID for this line item. ## Response **id** `string` The calculation ID. **object** `string` Always `tax.calculation`. **line\_items** `array` Tax calculations for order line items. **fee\_line\_items** `array` Tax calculations for fee line items (only present when `fee_details` provided). **totals** `object` Summary totals for order and fees. **Totals Properties** **order** `object` Order totals: `tax_amount`, `amount_excluding_tax`, `amount_including_tax`, `currency`, and `effective_tax_rate` (new in 2026-11-01: `tax_amount / amount_excluding_tax` as a decimal fraction, up to 6 decimal places, including flat fees; `0` when nothing is taxed). **fees** `object` Fee totals, same fields as `order` (only present when `fee_details` provided). **merchant** `object` The merchant used in this calculation. **roles** `array` The roles you specified. ### Enhanced Response Fields Platform calculations include additional tax jurisdiction details: **tax\_authority\_name** `string` Name of the tax authority (e.g., "California State"). **tax\_authority\_type** `string` Type of authority: `STATE`, `COUNTY`, `CITY`, or `DISTRICT`. **tax\_type** `string` Type of tax: `SALES`, `USE`, `VAT`, or `GST`. **note** `string` New in 2026-11-01. Why the row came out the way it did. Empty string for normally calculated tax. See [Notes](https://docs.numeral.com/v2026-11-01/objects/calculations.md#notes) for every value. ### IP Resolution Response Fields **location\_source** `string` `"address"` or `"ip"` -- indicates which input was used for tax determination. **resolution\_precision** `string` Precision of the resolved location: `STREET`, `POSTAL_PLUS`, `POSTAL`, `PROVINCE`, `COUNTRY`, or `APPROXIMATED`. **address\_used** `object` The address actually used for tax calculation, populated even when using IP-based resolution. > [!WARNING] > > **Caution about simply summing `tax_rate` values.** Each `tax_rate` in `tax_jurisdictions` is the statutory rate for that jurisdiction, and in some jurisdictions a rate applies to only part of the line item amount. Tennessee's single article rules are the common example: local rates apply only to the first \$1,600 of an item, and the 2.75% state single article rate applies only to the portion between \$1,600 and \$3,200. For a \$10,000 item the returned rates sum to 12.25%, but the tax due is \$788, an effective rate of 7.88%. > > Always charge the returned `tax_amount` (or `total_tax_amount`). If you need an effective rate, compute `tax_amount / amount_excluding_tax` from the response rather than adding up `tax_rate` values. The per-jurisdiction `tax_due_decimal` field shows how much each jurisdiction actually contributed. ```bash Basic Marketplace theme={null} curl -X POST https://api.numeralhq.com/tax/platform/calculations \ -H "Authorization: Bearer sk_test_xxx" \ -H "X-API-Version: 2026-11-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"] }' ``` ```bash IP-Based Resolution theme={null} curl -X POST https://api.numeralhq.com/tax/platform/calculations \ -H "Authorization: Bearer sk_test_xxx" \ -H "X-API-Version: 2026-11-01" \ -H "Content-Type: application/json" \ -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"] }' ``` ```bash With Platform Fees theme={null} curl -X POST https://api.numeralhq.com/tax/platform/calculations \ -H "Authorization: Bearer sk_test_xxx" \ -H "X-API-Version: 2026-11-01" \ -H "Content-Type: application/json" \ -d '{ "customer": { "type": "CONSUMER", "address": { "address_line_1": "9500 Civic Center Drive", "address_city": "Thornton", "address_province": "CO", "address_postal_code": "80229", "address_country": "US" } }, "merchant": { "merchant_id": "mer_1781234567890", "type": "BUSINESS" }, "order_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "reference_line_item_id": "goods", "product_category": "GENERAL_MERCHANDISE", "amount": 10000, "quantity": 1 } ] }, "roles": ["marketplace_provider"], "fee_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "reference_line_item_id": "fee", "product_category": "SAAS_GENERAL", "amount": 1000, "quantity": 1 } ] } }' ``` ```bash Payment Processor — Forced Rates theme={null} # 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-11-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"] }' ``` ```bash Exempt Customer theme={null} # customer.id applies the customer's exemptions (global tax-exempt flag or # exemption certificates on file) to the order. default_customer_type prices # the order as a CONSUMER if the ID has not been created in Numeral yet. curl -X POST https://api.numeralhq.com/tax/platform/calculations \ -H "Authorization: Bearer sk_test_xxx" \ -H "X-API-Version: 2026-11-01" \ -H "Content-Type: application/json" \ -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" }' ``` ```json 200 - Basic Response theme={null} { "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, "note": "" } ], "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, "effective_tax_rate": 0.087467 } }, "merchant": { "id": "merch_abc123", "reference_merchant_id": "my-seller-123" }, "roles": ["marketplace_provider"], "expires_at": 1735690200 } ``` ```json 200 - With Fees theme={null} { "testmode": true, "id": "plat_calc_1793039301789", "object": "tax.platform_calculation", "customer_currency_code": "USD", "customer": { "type": "CONSUMER" }, "merchant": { "merchant_id": "mer_1781234567890" }, "roles": ["marketplace_provider"], "line_items": [ { "line_item_id": "li_1793039301701", "product": { "reference_line_item_id": "goods", "reference_product_id": "default-general-merchandise", "reference_product_name": "Default GENERAL_MERCHANDISE Product", "product_tax_code": "GENERAL_MERCHANDISE" }, "tax_jurisdictions": [ { "tax_rate": 0.029, "tax_due_decimal": 290, "fee_amount": 0, "rate_type": "GENERAL STATE SALES TAX", "tax_authority_name": "Colorado", "tax_authority_type": "", "tax_type": "SALES", "note": "" }, { "tax_rate": 0.0075, "tax_due_decimal": 75, "fee_amount": 0, "rate_type": "GENERAL COUNTY LOCAL SALES TAX", "tax_authority_name": "Adams", "tax_authority_type": "", "tax_type": "SALES", "note": "" }, { "tax_rate": 0.0375, "tax_due_decimal": 375, "fee_amount": 0, "rate_type": "GENERAL CITY LOCAL SALES TAX", "tax_authority_name": "Thornton", "tax_authority_type": "", "tax_type": "SALES", "note": "" }, { "tax_rate": 0.01, "tax_due_decimal": 100, "fee_amount": 0, "rate_type": "GENERAL DISTRICT LOCAL SALES TAX", "tax_authority_name": "Colorado Regional Transportation District", "tax_authority_type": "", "tax_type": "SALES", "note": "" }, { "tax_rate": 0.001, "tax_due_decimal": 10, "fee_amount": 0, "rate_type": "GENERAL DISTRICT LOCAL SALES TAX", "tax_authority_name": "Colorado Scientific and Cultural Facilities District", "tax_authority_type": "", "tax_type": "SALES", "note": "" } ], "tax_amount": 850, "amount_excluding_tax": 10000, "amount_including_tax": 10850, "quantity": 1 } ], "fee_line_items": [ { "line_item_id": "li_1793039301702", "product": { "reference_line_item_id": "fee", "reference_product_id": "default-saas-general", "reference_product_name": "Default SAAS_GENERAL Product", "product_tax_code": "SAAS_GENERAL" }, "tax_jurisdictions": [ { "tax_rate": 0, "tax_due_decimal": 0, "fee_amount": 0, "rate_type": "EXEMPT STATE SALES TAX", "tax_authority_name": "California", "tax_authority_type": "", "tax_type": "SALES", "note": "" }, { "tax_rate": 0, "tax_due_decimal": 0, "fee_amount": 0, "rate_type": "EXEMPT COUNTY LOCAL SALES TAX", "tax_authority_name": "Sacramento", "tax_authority_type": "", "tax_type": "SALES", "note": "" }, { "tax_rate": 0, "tax_due_decimal": 0, "fee_amount": 0, "rate_type": "EXEMPT CITY LOCAL SALES TAX", "tax_authority_name": "Sacramento", "tax_authority_type": "", "tax_type": "SALES", "note": "" } ], "tax_amount": 0, "amount_excluding_tax": 1000, "amount_including_tax": 1000, "quantity": 1 } ], "totals": { "order": { "tax_amount": 850, "amount_excluding_tax": 10000, "amount_including_tax": 10850, "currency": "USD", "effective_tax_rate": 0.085 }, "fees": { "tax_amount": 0, "amount_excluding_tax": 1000, "amount_including_tax": 1000, "currency": "USD", "effective_tax_rate": 0 } }, "location_source": "address", "resolution_precision": "STREET", "address_used": { "address_line_1": "9500 Civic Center Drive", "address_city": "Thornton", "address_province": "CO", "address_postal_code": "80229", "address_country": "US" } } ``` ```json 404 - Merchant Not Found theme={null} { "error": { "error_code": "merchant_not_found", "error_message": "Merchant not found or belongs to different testmode" } } ``` ```json 404 - Customer Not Found theme={null} { "code": 404, "type": "CUSTOMER_NOT_FOUND", "message": "Unable to find customer with ID: my-buyer-456 in test environment." } ``` ## OpenAPI ````yaml api-reference/v2026-11-01/openapi.json POST /tax/platform/calculations openapi: 3.0.1 info: title: Numeral API description: >- API for sales tax calculations - Version 2026-11-01. This version adds a `note` to every tax jurisdiction row and an `effective_tax_rate` to calculations and platform calculation totals. license: name: MIT version: '2026-11-01' servers: - url: https://api.numeralhq.com/ security: - bearerAuth: [] paths: /tax/platform/calculations: post: summary: Platform Calculation description: >- 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`.** operationId: platformCalculation_v20261101 parameters: - name: X-API-Version in: header required: true schema: type: string enum: - '2026-11-01' description: API version. Must be 2026-11-01 for platform calculations. requestBody: content: application/json: schema: $ref: '#/components/schemas/PlatformCalculationRequest' examples: marketplace_basic: summary: Basic marketplace calculation description: >- A marketplace facilitating a sale. Note: amount (2500) × quantity (3) = $75.00 taxable base value: 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 with_fees: summary: Platform with fee calculation description: >- Payment processor collecting both order tax and platform fee tax value: 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 business_customer: summary: B2B platform transaction value: customer: type: BUSINESS tax_ids: - type: gb_vat value: GB123456789 address: address_line_1: 10 Business Park address_city: London address_province: LND address_postal_code: EC1A 1BB address_country: GB address_type: billing merchant: merchant_id: eu-seller-456 type: BUSINESS tax_ids: - type: de_vat value: DE987654321 order_details: customer_currency_code: EUR tax_included_in_amount: false automatic_tax: auto line_items: - amount: 10000 quantity: 5 product_category: SAAS_GENERAL roles: - marketplace_provider ip_based: summary: IP-based platform calculation value: 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 required: true responses: '200': description: Platform calculation response content: application/json: schema: $ref: '#/components/schemas/PlatformCalculationResponse' examples: basic_response: summary: Basic platform calculation response value: 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 note: '' 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 effective_tax_rate: 0.087467 merchant: id: merch_abc123 reference_merchant_id: my-seller-123 roles: - marketplace_provider with_fees_response: summary: Response with fee calculations value: 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 note: '' 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 note: '' 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 effective_tax_rate: 0.0875 fees: tax_amount: 26 amount_excluding_tax: 299 amount_including_tax: 325 effective_tax_rate: 0.086957 merchant: id: merch_abc123 reference_merchant_id: my-seller-123 roles: - payment_processor '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Merchant or customer not found content: application/json: schema: oneOf: - $ref: '#/components/schemas/MerchantNotFoundError' - $ref: '#/components/schemas/CustomerNotFoundError' '422': description: >- IP resolution error - the IP address could not be resolved to sufficient detail content: application/json: schema: oneOf: - $ref: '#/components/schemas/IpResolutionFailedError' - $ref: '#/components/schemas/IpResolutionInsufficientUsError' - $ref: '#/components/schemas/IpResolutionInsufficientCaError' components: schemas: PlatformCalculationRequest: type: object description: Request body for platform/marketplace tax calculations properties: customer: $ref: '#/components/schemas/PlatformCustomer' merchant: $ref: '#/components/schemas/PlatformMerchant' order_details: $ref: '#/components/schemas/PlatformOrderDetails' roles: type: array description: Your role(s) in this transaction items: type: string enum: - marketplace_provider - payment_processor - merchant_of_record example: - marketplace_provider fee_details: $ref: '#/components/schemas/PlatformFeeDetails' description: 'Optional: Details for platform fees to be taxed separately' transacted_at: type: integer description: >- 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. example: 1772323200 default_customer_type: type: string enum: - CONSUMER - BUSINESS description: >- 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: CONSUMER required: - customer - merchant - order_details - roles PlatformCalculationResponse: type: object properties: id: type: string example: calc_platform_123456789 object: type: string example: tax.calculation testmode: type: boolean customer_currency_code: type: string line_items: type: array items: $ref: '#/components/schemas/PlatformCalculationLineItem' fee_line_items: type: array description: >- Tax calculations for platform fees (only present when fee_details provided) items: $ref: '#/components/schemas/PlatformCalculationLineItem' totals: type: object properties: order: $ref: '#/components/schemas/TotalsSummary' fees: $ref: '#/components/schemas/TotalsSummary' description: Only present when fee_details provided merchant: type: object properties: id: type: string reference_merchant_id: type: string roles: type: array items: type: string expires_at: type: number location_source: type: string enum: - address - ip description: Which input was used for tax determination. example: address resolution_precision: type: string enum: - STREET - POSTAL_PLUS - POSTAL - PROVINCE - COUNTRY - APPROXIMATED description: The precision level of the resolved location. example: POSTAL address_used: $ref: '#/components/schemas/Address' description: >- The address actually used for tax calculation, populated even for IP-based requests. Error: type: object description: Standard error response format for API version 2026-01-01 properties: code: type: integer description: HTTP status code example: 400 type: type: string description: Machine-readable error type example: MISSING_FIELD message: type: string description: Human-readable error message example: Required field 'address_country' is missing required: - code - type - message MerchantNotFoundError: type: object properties: code: type: integer example: 404 type: type: string example: MERCHANT_NOT_FOUND message: type: string example: Merchant not found or belongs to different testmode CustomerNotFoundError: type: object properties: code: type: integer example: 404 type: type: string example: CUSTOMER_NOT_FOUND message: type: string example: Customer not found IpResolutionFailedError: type: object properties: code: type: integer example: 422 type: type: string example: IP_RESOLUTION_FAILED message: type: string example: >- Unable to resolve IP address to a country. Please provide a full address in customer.address. IpResolutionInsufficientUsError: type: object properties: code: type: integer example: 422 type: type: string example: IP_RESOLUTION_INSUFFICIENT_US message: type: string example: >- IP address resolved to a US state but could not determine a postal code. Please provide customer.address with address_postal_code and address_province. IpResolutionInsufficientCaError: type: object properties: code: type: integer example: 422 type: type: string example: IP_RESOLUTION_INSUFFICIENT_CA message: type: string example: >- IP address resolved to CA but could not determine a province. Please provide customer.address with address_province. PlatformCustomer: type: object properties: id: type: string description: >- The ID of the customer (buyer) that you created in Numeral, either the `cust_` ID or your own reference ID. When provided, the customer's exemption status is applied to the order: a globally tax-exempt customer returns zero tax, and exemption certificates on file for the customer are applied for the destination jurisdiction. Not applied to `fee_details`, whose buyer is the merchant. If no matching customer exists the request returns 404 `customer_not_found` unless the top-level `default_customer_type` is set. example: cust_123456789 type: type: string enum: - CONSUMER - BUSINESS description: The type of customer default: CONSUMER tax_ids: type: array items: $ref: '#/components/schemas/TaxId' address: allOf: - $ref: '#/components/schemas/Address' - type: object properties: address_type: type: string enum: - shipping - billing ip: type: object description: >- IP address for geo-based tax resolution. Either address or ip (or both) must be provided. properties: value: type: string description: A valid IPv4 or IPv6 address. example: 217.217.113.167 resolution: type: string enum: - strict - zero - approximate - best_effort description: >- How to handle insufficient IP resolution. strict (default): error if insufficient. zero: return zero-rate. approximate: attempt to resolve using heuristics. best_effort: try approximate, fall back to zero. default: strict required: - value description: Customer details. At least one of address or ip must be provided. PlatformMerchant: type: object description: The merchant (seller) involved in this platform transaction properties: merchant_id: type: string description: The merchant ID (merch_xxx) or your reference_merchant_id example: my-seller-123 type: type: string enum: - BUSINESS - INDIVIDUAL description: The merchant's business type default: BUSINESS tax_ids: type: array description: Override merchant's stored tax IDs for this calculation items: $ref: '#/components/schemas/TaxId' required: - merchant_id PlatformOrderDetails: type: object properties: customer_currency_code: type: string example: USD tax_included_in_amount: type: boolean default: false automatic_tax: type: string enum: - auto - disabled - forced default: auto description: >- 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: type: array items: $ref: '#/components/schemas/PlatformLineItem' required: - customer_currency_code - tax_included_in_amount - automatic_tax - line_items PlatformFeeDetails: type: object description: >- 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. properties: customer_currency_code: type: string example: USD tax_included_in_amount: type: boolean default: false automatic_tax: type: string enum: - auto - disabled default: auto description: >- 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: type: array items: $ref: '#/components/schemas/PlatformLineItem' required: - customer_currency_code - tax_included_in_amount - automatic_tax - line_items PlatformCalculationLineItem: type: object properties: product: type: object properties: reference_product_id: type: string reference_line_item_id: type: string product_tax_code: type: string tax_jurisdictions: type: array items: type: object properties: tax_rate: type: number rate_type: type: string jurisdiction_name: type: string tax_authority_name: type: string description: Name of the tax authority tax_authority_type: type: string description: Type of authority (STATE, COUNTY, CITY, DISTRICT) tax_type: type: string description: Type of tax (SALES, USE, VAT, GST) fee_amount: type: number note: type: string description: >- Why this row came out the way it did. Empty string for normally calculated tax. Otherwise one of `no_collection_exempt_customer`, `no_collection_no_state_nexus`, `no_collection_no_vat_registration`, `no_collection_no_gst_registration`, `collection_manually_deactivated`, `automatic_tax_disabled`, `b2b_reverse_charge`, `shipping_follows_highest_taxed_item`, `canary_islands_zero_rate`. example: '' quantity: type: integer tax_amount: type: integer amount_excluding_tax: type: integer amount_including_tax: type: integer TotalsSummary: type: object properties: tax_amount: type: integer description: Total tax in smallest currency unit amount_excluding_tax: type: integer description: Total before tax amount_including_tax: type: integer description: Total including tax effective_tax_rate: type: number description: >- `tax_amount / amount_excluding_tax` for this bucket, as a decimal fraction (0.085 = 8.5%). Up to 6 decimal places. Includes flat fees. `0` when `amount_excluding_tax` is 0. example: 0.085 Address: type: object properties: address_line_1: type: string example: 3990 N County Rd 300 E address_line_2: type: string example: Unit 2 address_city: type: string example: Danville address_province: type: string description: >- The state, province, or region of the transaction. Must be a valid 2 digit ISO 3166-2 subdivision code. example: IN address_postal_code: type: string example: '46122' address_country: type: string description: >- The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code. example: US required: - address_line_1 - address_city - address_province - address_postal_code - address_country TaxId: type: object properties: type: type: string description: >- 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. example: us_ein value: type: string minLength: 1 maxLength: 100 description: The tax ID value (1-100 characters). example: 12-3456789 required: - type - value PlatformLineItem: type: object description: >- Line item for platform calculations. **Important: amount is PER-UNIT. Total = amount × quantity.** properties: reference_line_item_id: type: string description: Your ID for this line item reference_product_id: type: string description: Reference to a pre-created product product_category: type: string description: Tax category code example: GENERAL_MERCHANDISE amount: type: integer description: >- **PER-UNIT price** in smallest currency unit. For $25.00 items, use 2500. Total taxable = amount × quantity. example: 2500 quantity: type: integer description: Number of units. Taxable base = amount × quantity. example: 3 minimum: 0 required: - amount - quantity securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.