{ "openapi": "3.0.1", "info": { "title": "Numeral API", "description": "API for sales tax calculations - Version 2026-03-01. This version adds IP-based tax resolution for calculations and platform calculations, in addition to Merchant management and Platform Calculations.", "license": { "name": "MIT" }, "version": "2026-03-01" }, "servers": [ { "url": "https://api.numeralhq.com/" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/tax/merchants": { "post": { "summary": "Create Merchant", "description": "Creates a new merchant for platform/marketplace calculations. Merchants represent sellers on your platform.", "operationId": "createMerchant_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] }, "description": "API version. Must be 2026-03-01 for merchant endpoints." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantRequest" }, "examples": { "basic": { "summary": "Basic merchant creation", "value": { "reference_merchant_id": "my-seller-123", "name": "Test Seller", "email": "seller@example.com", "default_address": { "address_line_1": "123 Main St", "address_city": "San Francisco", "address_province": "CA", "address_postal_code": "94105", "address_country": "US" } } }, "with_tax_ids": { "summary": "Merchant with tax IDs", "value": { "reference_merchant_id": "eu-seller-456", "name": "European Seller", "email": "eu-seller@example.com", "default_address": { "address_line_1": "10 Rue de Commerce", "address_city": "Paris", "address_province": "75", "address_postal_code": "75001", "address_country": "FR" }, "tax_ids": [ { "type": "fr_vat", "value": "FR123456789" }, { "type": "de_vat", "value": "DE123456789" } ] } } } } }, "required": true }, "responses": { "200": { "description": "Merchant created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "duplicate_reference_id": { "summary": "Duplicate reference_merchant_id", "value": { "error": { "error_code": "duplicate_reference_id", "error_message": "A merchant with this reference_merchant_id already exists" } } } } } } } } }, "get": { "summary": "List Merchants", "description": "Retrieve a paginated list of all merchants for your account.", "operationId": "listMerchants_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "default": 10 }, "description": "Maximum number of merchants to return (max 100)" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "List of merchants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantListResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/merchants/{merchant_id}": { "get": { "summary": "Get Merchant", "description": "Retrieve a merchant by internal ID or reference_merchant_id.", "operationId": "getMerchant_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The merchant ID (merch_xxx) or your reference_merchant_id" } ], "responses": { "200": { "description": "Merchant details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponse" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantNotFoundError" } } } } } }, "post": { "summary": "Update Merchant", "description": "Update a merchant's information. Accepts same fields as create (except reference_merchant_id).", "operationId": "updateMerchant_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The merchant ID (merch_xxx) or your reference_merchant_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantUpdateRequest" }, "examples": { "update_name": { "summary": "Update merchant name", "value": { "name": "Updated Seller Name", "email": "new-email@example.com" } }, "update_address": { "summary": "Update address and tax IDs", "value": { "default_address": { "address_line_1": "456 New Street", "address_city": "Los Angeles", "address_province": "CA", "address_postal_code": "90001", "address_country": "US" }, "tax_ids": [ { "type": "us_ein", "value": "12-3456789" } ] } } } } }, "required": true }, "responses": { "200": { "description": "Merchant updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponse" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantNotFoundError" } } } } } }, "delete": { "summary": "Delete Merchant", "description": "Soft delete a merchant. The merchant will no longer appear in GET/LIST operations.", "operationId": "deleteMerchant_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "merchant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The merchant ID (merch_xxx) or your reference_merchant_id" } ], "responses": { "200": { "description": "Merchant deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantDeleteResponse" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantNotFoundError" } } } } } } }, "/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 \u00d7 quantity`.**", "operationId": "platformCalculation_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] }, "description": "API version. Must be 2026-03-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) \u00d7 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 } ], "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" ] } }, "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 } ], "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" ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantNotFoundError" } } } }, "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" } ] } } } } } } }, "/tax/platform/transactions": { "post": { "summary": "Create Platform Transaction", "description": "Record completed sales from a platform calculation. For payment processors, this creates two transactions: one for the order and one for the fee. For marketplace providers or merchants of record, only the order transaction is created.", "operationId": "createPlatformTransaction_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTransactionRequest" }, "example": { "platform_calculation_id": "plat_calc_abc123", "reference_order_id": "order_12345", "reference_payment_id": "pay_67890", "transaction_processed_at": 1736300000 } } }, "required": true }, "responses": { "200": { "description": "Platform transaction list response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTransactionListResponse" }, "examples": { "payment_processor": { "summary": "Payment Processor (creates order + fee transactions)", "value": { "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 } ] } }, "marketplace_provider": { "summary": "Marketplace Provider (creates order transaction only)", "value": { "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 } ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Platform calculation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformCalculationNotFoundError" } } } } } } }, "/tax/calculations": { "post": { "description": "Get tax information for a given product and address or IP", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ], "default": "2026-03-01" }, "description": "The API version for this request. Always set a version: pass this header explicitly (recommended), or configure a default API version on your account and omit the header. Accounts with no configured version fall back to `2024-09-01`, NOT this version.", "example": "2026-03-01" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationRequest" }, "examples": { "address_based": { "summary": "Address-based tax calculation", "value": { "customer": { "address": { "address_city": "Nashville", "address_country": "US", "address_line_1": "123 Broadway", "address_postal_code": "37203", "address_province": "TN", "address_type": "billing" } }, "metadata": { "payment_id": "68407cb7-e1fa-47fa-8244-bd9411d53c61" }, "order_details": { "automatic_tax": "auto", "customer_currency_code": "USD", "line_items": [ { "amount": 10000, "product_category": "BEVERAGES", "quantity": 1 }, { "amount": 10000, "product_category": "GENERAL_MERCHANDISE", "quantity": 1 } ], "tax_included_in_amount": false }, "origin_address": { "address_city": "Nashville", "address_country": "US", "address_line_1": "500 Church St", "address_line_2": "", "address_postal_code": "37219", "address_province": "TN" } } }, "ip_based": { "summary": "IP-based tax calculation", "value": { "customer": { "type": "CONSUMER", "ip": { "value": "217.217.113.167", "resolution": "strict" } }, "order_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "product_category": "SAAS_GENERAL", "reference_line_item_id": "ip-test-001", "amount": 10000, "quantity": 5 } ] } } }, "with_partner_fallbacks": { "summary": "Calculation with default_customer_type and fallback_product_category", "description": "Integration-partner pattern: always send customer_id and reference_product_id, and let Numeral fall back gracefully when either has not been created yet.", "value": { "customer": { "id": "cus_not_yet_in_numeral", "address": { "address_city": "Nashville", "address_country": "US", "address_line_1": "123 Broadway", "address_postal_code": "37203", "address_province": "TN", "address_type": "billing" } }, "default_customer_type": "CONSUMER", "order_details": { "automatic_tax": "auto", "customer_currency_code": "USD", "tax_included_in_amount": false, "line_items": [ { "reference_product_id": "product_not_yet_in_numeral", "fallback_product_category": "GENERAL_MERCHANDISE", "amount": 10000, "quantity": 1 } ] }, "origin_address": { "address_city": "Nashville", "address_country": "US", "address_line_1": "500 Church St", "address_postal_code": "37219", "address_province": "TN" } } } } } }, "required": true }, "responses": { "200": { "description": "Calculate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationResponse" }, "examples": { "address_based": { "summary": "Address-based calculation response", "value": { "testmode": true, "id": "calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3", "object": "tax.calculation", "customer_currency_code": "USD", "line_items": [ { "line_item_id": "li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f7f", "product": { "reference_line_item_id": "", "reference_product_id": "default-beverages", "reference_product_name": "Default BEVERAGES Product", "product_tax_code": "BEVERAGES" }, "tax_jurisdictions": [ { "tax_rate": 0.07, "tax_due_decimal": 700, "fee_amount": 0, "rate_type": "GENERAL STATE SALES TAX", "tax_authority_name": "Tennessee", "tax_authority_type": "", "tax_type": "SALES" }, { "tax_rate": 0.0225, "tax_due_decimal": 225, "fee_amount": 0, "rate_type": "GENERAL COUNTY LOCAL SALES TAX", "tax_authority_name": "DAVIDSON", "tax_authority_type": "", "tax_type": "SALES" } ], "tax_amount": 925, "amount_excluding_tax": 10000, "amount_including_tax": 10925, "quantity": 1 }, { "line_item_id": "li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f80", "product": { "reference_line_item_id": "", "reference_product_id": "default-general-merchandise", "reference_product_name": "Default GENERAL_MERCHANDISE Product", "product_tax_code": "GENERAL_MERCHANDISE" }, "tax_jurisdictions": [ { "tax_rate": 0.07, "tax_due_decimal": 700, "fee_amount": 0, "rate_type": "GENERAL STATE SALES TAX", "tax_authority_name": "Tennessee", "tax_authority_type": "", "tax_type": "SALES" }, { "tax_rate": 0.0225, "tax_due_decimal": 225, "fee_amount": 0, "rate_type": "GENERAL COUNTY LOCAL SALES TAX", "tax_authority_name": "DAVIDSON", "tax_authority_type": "", "tax_type": "SALES" } ], "tax_amount": 925, "amount_excluding_tax": 10000, "amount_including_tax": 10925, "quantity": 1 } ], "total_tax_amount": 1850, "tax_included_in_amount": false, "total_amount_excluding_tax": 20000, "total_amount_including_tax": 21850, "expires_at": 1783456061, "metadata": { "payment_id": "68407cb7-e1fa-47fa-8244-bd9411d53c61" }, "customer": { "type": "CONSUMER" }, "automatic_tax": "auto", "address_resolution_status": "EXACT", "address_used": { "address_line_1": "123 Broadway", "address_city": "Nashville", "address_province": "TN", "address_postal_code": "37203", "address_country": "US" }, "location_source": "address", "resolution_precision": "STREET" } }, "ip_based": { "summary": "IP-based calculation response", "value": { "testmode": true, "id": "calc_17725714816806a81b828-0757-4ec2-9307-3c1001733f73", "object": "tax.calculation", "customer_currency_code": "USD", "line_items": [ { "line_item_id": "li_1772571481680b3f8d264-9a15-4e72-bc48-05d6f2a81c93", "product": { "reference_line_item_id": "ip-test-001", "reference_product_id": "default-saas-general", "reference_product_name": "Default SAAS_GENERAL Product", "product_tax_code": "SAAS_GENERAL" }, "tax_jurisdictions": [ { "tax_rate": 0.06, "tax_due_decimal": 3000, "fee_amount": 0, "rate_type": "GENERAL STATE SALES TAX", "tax_authority_name": "Pennsylvania", "tax_authority_type": "", "tax_type": "SALES" }, { "tax_rate": 0.01, "tax_due_decimal": 500, "fee_amount": 0, "rate_type": "GENERAL COUNTY LOCAL SALES TAX", "tax_authority_name": "ALLEGHENY", "tax_authority_type": "", "tax_type": "SALES" } ], "tax_amount": 3500, "amount_excluding_tax": 50000, "amount_including_tax": 53500, "quantity": 5 } ], "total_tax_amount": 3500, "tax_included_in_amount": false, "total_amount_excluding_tax": 50000, "total_amount_including_tax": 53500, "expires_at": 1772657881, "customer": { "type": "CONSUMER" }, "automatic_tax": "auto", "address_resolution_status": "POSTAL_ONLY", "address_used": { "address_line_1": "", "address_line_2": "", "address_city": "", "address_province": "PA", "address_postal_code": "15212", "address_country": "US" }, "location_source": "ip", "resolution_precision": "POSTAL" } }, "with_partner_fallbacks": { "summary": "Response when default_customer_type and fallback_product_category were used", "value": { "testmode": true, "id": "calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d4", "object": "tax.calculation", "customer_currency_code": "USD", "line_items": [ { "line_item_id": "li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f81", "product": { "reference_line_item_id": "", "reference_product_id": "default-general-merchandise", "reference_product_name": "Default GENERAL_MERCHANDISE Product", "product_tax_code": "GENERAL_MERCHANDISE" }, "tax_jurisdictions": [ { "tax_rate": 0.07, "tax_due_decimal": 700, "fee_amount": 0, "rate_type": "GENERAL STATE SALES TAX", "tax_authority_name": "Tennessee", "tax_authority_type": "", "tax_type": "SALES" }, { "tax_rate": 0.0225, "tax_due_decimal": 225, "fee_amount": 0, "rate_type": "GENERAL COUNTY LOCAL SALES TAX", "tax_authority_name": "DAVIDSON", "tax_authority_type": "", "tax_type": "SALES" } ], "tax_amount": 925, "amount_excluding_tax": 10000, "amount_including_tax": 10925, "quantity": 1 } ], "total_tax_amount": 925, "tax_included_in_amount": false, "total_amount_excluding_tax": 10000, "total_amount_including_tax": 10925, "expires_at": 1783456061, "customer": { "type": "CONSUMER" }, "automatic_tax": "auto", "address_resolution_status": "EXACT", "address_used": { "address_line_1": "123 Broadway", "address_city": "Nashville", "address_province": "TN", "address_postal_code": "37203", "address_country": "US" }, "location_source": "address", "resolution_precision": "STREET" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductNotFoundError" } } } }, "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" } ] } } } } } } }, "/tax/transactions": { "post": { "summary": "Create Transaction", "description": "Record a completed sale", "operationId": "createTransaction_v20260301", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "Transaction response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Calculation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationNotFoundError" } } } } } } }, "/tax/refunds": { "post": { "summary": "Create Refund", "description": "Add a refund to a transaction", "operationId": "createRefund_v20260301", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } }, "required": true }, "responses": { "200": { "description": "Refund response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionNotFoundError" } } } } } } }, "/tax/refund_reversals": { "post": { "summary": "Reverse Refund", "description": "Reverse a refund you've previously created", "operationId": "reverseRefund_v20260301", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refund_id": { "type": "string", "description": "The ID of the refund to reverse" } }, "required": [ "refund_id" ] } } }, "required": true }, "responses": { "200": { "description": "Refund response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/transactions/{transaction_id}": { "get": { "summary": "Get Transaction", "description": "Retrieve the details of a specific transaction", "operationId": "getTransaction_v20260301", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete Transaction", "description": "Delete a specific transaction", "operationId": "deleteTransaction_v20260301", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction deletion response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTransactionResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/transactions/{transaction_id}/refunds": { "get": { "summary": "Get Transaction Refunds", "description": "Retrieve the refunds for a specific transaction", "operationId": "getTransactionRefunds_v20260301", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of refunds", "content": { "application/json": { "schema": { "type": "object", "properties": { "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/RefundForTransactionResponse" } } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/products/{reference_product_id}": { "get": { "summary": "Get Product", "description": "Retrieve the details of a specific product", "operationId": "getProduct_v20260301", "parameters": [ { "name": "reference_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete Product", "description": "Delete a specific product", "operationId": "deleteProduct_v20260301", "parameters": [ { "name": "reference_product_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product deletion response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteProductResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/products": { "get": { "summary": "List Products", "description": "Retrieve a list of up to 50 products", "operationId": "listProducts_v20260301", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "last_product_id": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductResponse" } } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create Product", "description": "Create and categorize a new product", "operationId": "createProduct_v20260301", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductRequest" } } }, "required": true }, "responses": { "200": { "description": "Product creation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/customers": { "get": { "summary": "List Customers", "description": "Retrieve a paginated list of all customers. Deleted customers are not included.", "operationId": "listCustomers_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor from previous response. Use the `last_customer_id` from the previous response." } ], "responses": { "200": { "description": "List of customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create Customer", "description": "Create a new customer", "operationId": "createCustomer_v20260301", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRequest" } } }, "required": true }, "responses": { "200": { "description": "Customer creation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/customers/{customer_id}": { "get": { "summary": "Get Customer", "description": "Retrieve the details of a specific customer", "operationId": "getCustomer_v20260301", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "reference_customer_id" ], "default": "id" }, "description": "The type of identifier provided in the path. Use `id` (the default) to look up by the Numeral customer ID, or `reference_customer_id` to look up by your own reference customer ID.", "example": "reference_customer_id" } ], "responses": { "200": { "description": "Customer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Update Customer", "description": "Update an existing customer's information. All fields are optional, but at least one must be provided. Only the fields you include are changed.", "operationId": "updateCustomer_v20260301", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Numeral customer ID (`cust_xxx`) or your `reference_customer_id`. Either identifier is accepted; no `id_type` query parameter is needed." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" }, "examples": { "mark_tax_exempt": { "summary": "Mark a customer as tax exempt", "value": { "is_tax_exempt": true } }, "update_contact_info": { "summary": "Update name and email", "value": { "name": "New Customer Name", "email": "new.email@example.com" } }, "update_reference_id": { "summary": "Change the reference customer ID", "value": { "reference_customer_id": "20507" } } } } }, "required": true }, "responses": { "200": { "description": "The updated customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Invalid request. Returned when no updatable field is provided (`INVALID_REQUEST`), the email is malformed (`INVALID_EMAIL`), the customer does not exist or has been deleted (`CUSTOMER_NOT_FOUND`), or another customer already uses the new `email` or `reference_customer_id` (`DUPLICATE_CUSTOMER`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete Customer", "description": "Delete a specific customer", "operationId": "deleteCustomer_v20260301", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer deletion response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCustomerResponse" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/ping": { "get": { "summary": "Health Check", "description": "Authenticated health check endpoint", "operationId": "pingHealthCheck_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-03-01" ] } } ], "responses": { "200": { "description": "Successful health check response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "401": { "description": "Authentication errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } } } } }, "/tax/certificate-requests": { "get": { "summary": "List Certificate Requests", "description": "Retrieve a paginated list of certificate requests. Filter by status, customer, certificate type, and time windows. Live-only \u2014 `sk_test_*` keys are rejected with `TESTMODE_NOT_SUPPORTED`.", "operationId": "listCertificateRequests_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CertificateRequestStatus" }, "description": "Filter by public status." }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by customer. Pair with `id_type` to choose Numeral id vs. reference id." }, { "name": "id_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "reference_customer_id" ], "default": "id" }, "description": "How to interpret `customer_id`. Use `id` (the default) for the Numeral `cust_*` id, or `reference_customer_id` for your own id. Validated whenever present \u2014 passing an unknown value returns `INVALID_REQUEST` (400) even if `customer_id` is not also supplied." }, { "name": "certificate_type_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by certificate type. Accepts either the stable identifier (e.g. `US-CA-CDTFA-230`) or the numeric type id (e.g. `12`)." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Max items per page (1\u2013100). Defaults to 10." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor \u2014 pass `next_cursor` from the previous response." } ], "responses": { "200": { "description": "Certificate request list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateRequestListResponse" }, "example": { "object": "list", "certificate_requests": [ { "id": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d", "object": "tax.certificate_request", "status": "fulfilled", "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "certificate_id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e", "certificate_type_id": "US-CA-CDTFA-230", "jurisdictions": [ "US-CA" ], "created_at": "2026-03-01T12:00:00Z", "updated_at": "2026-03-02T09:30:00Z", "expires_at": null, "livemode": true }, { "id": "cert_req_7d3c9e18-4a2b-4f6c-9e1d-8b0a5c2f3e4d", "object": "tax.certificate_request", "status": "pending", "customer": { "id": "cust_9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9", "reference_customer_id": "20507" }, "certificate_id": null, "certificate_type_id": "US-TX-01-339", "jurisdictions": [ "US-TX" ], "created_at": "2026-03-04T08:15:00Z", "updated_at": "2026-03-04T08:15:00Z", "expires_at": "2026-04-03T08:15:00Z", "livemode": true } ], "has_more": true, "next_cursor": "cert_req_7d3c9e18-4a2b-4f6c-9e1d-8b0a5c2f3e4d" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/certificate-requests/{request_id}": { "get": { "summary": "Get Certificate Request", "description": "Retrieve a single certificate request by id. Live-only.", "operationId": "getCertificateRequest_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateRequestResponse" }, "example": { "id": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d", "object": "tax.certificate_request", "status": "fulfilled", "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "certificate_id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e", "certificate_type_id": "US-CA-CDTFA-230", "jurisdictions": [ "US-CA" ], "created_at": "2026-03-01T12:00:00Z", "updated_at": "2026-03-02T09:30:00Z", "expires_at": null, "livemode": true } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Cancel Certificate Request", "description": "Cancel a pending certificate request. Terminal and idempotent \u2014 canceling an already-canceled request returns `200` with the same body. Canceling a fulfilled request returns `409` with `REQUEST_ALREADY_FULFILLED`. Live-only.", "operationId": "cancelCertificateRequest_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Canceled certificate request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateRequestResponse" }, "example": { "id": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d", "object": "tax.certificate_request", "status": "canceled", "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "certificate_id": null, "certificate_type_id": "US-CA-CDTFA-230", "jurisdictions": [ "US-CA" ], "created_at": "2026-03-01T12:00:00Z", "updated_at": "2026-03-03T15:45:00Z", "expires_at": null, "livemode": true } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "REQUEST_ALREADY_FULFILLED or REQUEST_INVALID \u2014 the request is in a terminal state and cannot be canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/certificates": { "get": { "summary": "List Certificates", "description": "Retrieve a paginated list of exemption certificates. Filter by customer, jurisdiction, status, certificate type, and time windows. Live-only.", "operationId": "listCertificates_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CertificateStatus" } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "id_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "reference_customer_id" ], "default": "id" }, "description": "How to interpret `customer_id`. Use `id` (the default) for the Numeral `cust_*` id, or `reference_customer_id` for your own id. Validated whenever present \u2014 passing an unknown value returns `INVALID_REQUEST` (400) even if `customer_id` is not also supplied." }, { "name": "jurisdiction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Jurisdiction identifier, e.g. `US-CA`." }, { "name": "certificate_type_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by certificate type. Accepts either the stable identifier (e.g. `US-CA-CDTFA-230`) or the numeric type id (e.g. `12`)." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateListResponse" }, "example": { "object": "list", "certificates": [ { "id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e", "object": "tax.exemption_certificate", "status": "active", "certificate_type": { "id": "12", "name": "California Resale Certificate (CDTFA-230)", "certificate_identifier": "US-CA-CDTFA-230" }, "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "jurisdictions": [ { "jurisdiction_id": "US-CA", "status": "active", "effective_date": "2026-01-01", "expiration_date": "2027-01-01" } ], "effective_date": "2026-01-01", "expiration_date": "2027-01-01", "created_at": "2026-03-01T12:00:00Z", "updated_at": "2026-03-01T12:00:00Z", "livemode": true } ], "has_more": false } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Submit Certificate", "description": "Submit a certificate document for asynchronous processing. Numeral downloads the document from the `https` URL you provide, stores it, and classifies the certificate type and jurisdiction from the document itself. Returns a `tax.certificate_upload` you can poll. Live-only \u2014 `sk_test_*` keys are rejected with `TESTMODE_NOT_SUPPORTED`.", "operationId": "submitCertificate_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] }, "description": "Must be `2026-03-01` or later. Older versions return `INVALID_REQUEST` (400)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateUploadRequest" }, "example": { "document_url": "https://your-bucket.s3.amazonaws.com/certs/resale.pdf?X-Amz-Signature=...", "file_name": "resale.pdf", "customer": { "reference_customer_id": "20506" } } } } }, "responses": { "201": { "description": "Upload accepted. `status` is `processing` or `duplicate`; `certificate_ids` is always empty at this point \u2014 poll `GET /tax/certificate-uploads/{upload_id}` for results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateUploadResponse" }, "example": { "id": "upl_4471", "object": "tax.certificate_upload", "status": "processing", "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "certificate_ids": [], "error_message": null, "created_at": "2026-09-15T17:04:11.000Z", "livemode": true } } } }, "400": { "description": "`INVALID_DOCUMENT_URL`, `DOCUMENT_FETCH_FAILED`, `UNSUPPORTED_FILE_TYPE`, `FILE_TOO_LARGE`, `TESTMODE_NOT_SUPPORTED`, or `INVALID_REQUEST` (schema violation or API version below 2026-03-01)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CUSTOMER_NOT_FOUND` \u2014 `customer.id` does not exist for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerNotFoundError" } } } }, "409": { "description": "`BUYER_IDENTITY_CONFLICT` \u2014 `customer.id` and `customer.reference_customer_id` resolve to different customers; nothing was written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`DOCUMENT_URL_UNAUTHORIZED` \u2014 the document host returned 401/403, most commonly an expired presigned URL. Mint a fresh URL and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`NUMERAL_ERROR` \u2014 the upload was stored but processing could not start. Retry the submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/certificates/{certificate_id}": { "get": { "summary": "Get Certificate", "description": "Retrieve a single certificate by id, including a short-lived `download_url`. Live-only.", "operationId": "getCertificate_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] } }, { "name": "certificate_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate detail (includes pre-signed `download_url`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateDetailResponse" }, "example": { "id": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e", "object": "tax.exemption_certificate", "status": "active", "certificate_type": { "id": "12", "name": "California Resale Certificate (CDTFA-230)", "certificate_identifier": "US-CA-CDTFA-230" }, "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "jurisdictions": [ { "jurisdiction_id": "US-CA", "status": "active", "effective_date": "2026-01-01", "expiration_date": "2027-01-01" } ], "effective_date": "2026-01-01", "expiration_date": "2027-01-01", "created_at": "2026-03-01T12:00:00Z", "updated_at": "2026-03-01T12:00:00Z", "livemode": true, "download_url": "https://numeral-ecm-documents.s3.amazonaws.com/certificates/cert_a8f3d2c1.pdf?X-Amz-Expires=3600&X-Amz-Signature=..." } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/certificate-uploads": { "get": { "summary": "List Certificate Uploads", "description": "Retrieve a paginated list of certificate uploads, ordered by id ascending. Filter by status and customer. List items omit `document_url` \u2014 fetch a single upload for the document link. Live-only.", "operationId": "listCertificateUploads_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] }, "description": "Must be `2026-03-01` or later. Older versions return `INVALID_REQUEST` (400)." }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CertificateUploadStatus" }, "description": "Filter by upload status. Any other value returns `INVALID_REQUEST` (400)." }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to one customer. Interpreted per `id_type`. Matches only live, live-mode customers." }, { "name": "id_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "id", "reference_customer_id" ], "default": "id" }, "description": "How to interpret `customer_id`. Use `id` (the default) for the Numeral customer id, or `reference_customer_id` for your own id. Any other value returns `INVALID_REQUEST` (400)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor \u2014 pass `next_cursor` from the previous response (an `upl_*` id; the bare numeric form is also accepted). Returns rows with an id greater than the cursor. Malformed values return `INVALID_REQUEST` (400)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Max items per page (1\u2013100). Defaults to 10." } ], "responses": { "200": { "description": "Certificate upload list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateUploadListResponse" }, "example": { "object": "list", "certificate_uploads": [ { "id": "upl_4469", "object": "tax.certificate_upload", "status": "failed", "customer": null, "certificate_ids": [], "error_message": "Document could not be classified as an exemption certificate.", "created_at": "2026-09-15T16:41:37.000Z", "livemode": true }, { "id": "upl_4470", "object": "tax.certificate_upload", "status": "completed", "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "certificate_ids": [ "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e" ], "error_message": null, "created_at": "2026-09-15T16:58:02.000Z", "livemode": true }, { "id": "upl_4471", "object": "tax.certificate_upload", "status": "processing", "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "certificate_ids": [], "error_message": null, "created_at": "2026-09-15T17:04:11.000Z", "livemode": true } ], "has_more": true, "next_cursor": "upl_4471" } } } }, "400": { "description": "`INVALID_REQUEST` (bad `status`, `id_type`, `cursor`, or API version below 2026-03-01) or `TESTMODE_NOT_SUPPORTED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tax/certificate-uploads/{upload_id}": { "get": { "summary": "Get Certificate Upload", "description": "Retrieve a single certificate upload by id, including a short-lived `document_url` for the originally submitted document. This is the polling endpoint \u2014 call it until `status` leaves `processing`. Live-only.", "operationId": "getCertificateUpload_v20260301", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01" ] }, "description": "Must be `2026-03-01` or later. Older versions return `INVALID_REQUEST` (400)." }, { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The upload id (`upl_4471`) or its bare numeric form (`4471`)." } ], "responses": { "200": { "description": "Certificate upload detail (includes pre-signed `document_url`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateUploadDetailResponse" }, "example": { "id": "upl_4470", "object": "tax.certificate_upload", "status": "completed", "customer": { "id": "cust_6126acaf-7379-411a-8ada-00005bac0715", "reference_customer_id": "20506" }, "certificate_ids": [ "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e" ], "error_message": null, "created_at": "2026-09-15T16:58:02.000Z", "livemode": true, "document_url": "https://numeral-ecm-documents.s3.amazonaws.com/uploads/upl_4470.pdf?X-Amz-Expires=3600&X-Amz-Signature=..." } } } }, "400": { "description": "`TESTMODE_NOT_SUPPORTED` or `INVALID_REQUEST` (API version below 2026-03-01)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`CERTIFICATE_UPLOAD_NOT_FOUND` \u2014 unknown id, malformed id, or an upload belonging to another account (indistinguishable by design)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateUploadNotFoundError" } } } } } } } }, "components": { "schemas": { "MerchantRequest": { "type": "object", "description": "Request body for creating a merchant", "properties": { "reference_merchant_id": { "type": "string", "description": "Your external ID for this merchant. Must be unique per client+testmode.", "example": "my-seller-123" }, "name": { "type": "string", "description": "The merchant's business name", "example": "Acme Seller Co" }, "email": { "type": "string", "description": "The merchant's email address", "example": "seller@example.com" }, "default_address": { "$ref": "#/components/schemas/MerchantAddress" }, "tax_ids": { "type": "array", "description": "Tax identification numbers for this merchant", "items": { "$ref": "#/components/schemas/TaxId" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "MerchantUpdateRequest": { "type": "object", "description": "Request body for updating a merchant. All fields are optional.", "properties": { "name": { "type": "string", "description": "The merchant's business name" }, "email": { "type": "string", "description": "The merchant's email address" }, "default_address": { "$ref": "#/components/schemas/MerchantAddress" }, "tax_ids": { "type": "array", "items": { "$ref": "#/components/schemas/TaxId" } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "MerchantResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The internal merchant ID", "example": "merch_1765503753979c37c5f24" }, "object": { "type": "string", "example": "tax.merchant" }, "reference_merchant_id": { "type": "string", "description": "Your external ID for this merchant", "example": "my-seller-123" }, "name": { "type": "string", "example": "Acme Seller Co" }, "email": { "type": "string", "example": "seller@example.com" }, "default_address": { "$ref": "#/components/schemas/MerchantAddress" }, "tax_ids": { "type": "array", "items": { "$ref": "#/components/schemas/TaxId" } }, "status": { "type": "string", "enum": [ "active", "deleted" ], "example": "active" }, "testmode": { "type": "boolean", "description": "Whether this merchant was created in test mode" }, "created_at": { "type": "number", "description": "Unix timestamp of creation" }, "updated_at": { "type": "number", "description": "Unix timestamp of last update" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "MerchantListResponse": { "type": "object", "properties": { "merchants": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantResponse" } }, "has_more": { "type": "boolean", "description": "Whether there are more merchants to fetch" }, "last_merchant_id": { "type": "string", "description": "Use as cursor for next page" } } }, "MerchantDeleteResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "merch_1765503753979c37c5f24" }, "object": { "type": "string", "example": "tax.merchant" }, "deleted": { "type": "boolean", "example": true }, "deleted_at": { "type": "number", "description": "Unix timestamp of deletion" } } }, "MerchantAddress": { "type": "object", "description": "Merchant's default business address. Uses address_ prefix for field names.", "properties": { "address_line_1": { "type": "string", "example": "123 Main St" }, "address_line_2": { "type": "string", "example": "Suite 100" }, "address_city": { "type": "string", "example": "San Francisco" }, "address_province": { "type": "string", "description": "State/province code (2-letter ISO 3166-2)", "example": "CA" }, "address_postal_code": { "type": "string", "example": "94105" }, "address_country": { "type": "string", "description": "Country code (2-letter ISO 3166-1)", "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" ] }, "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 } }, "required": [ "customer", "merchant", "order_details", "roles" ] }, "PlatformCustomer": { "type": "object", "properties": { "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 \u2014 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` \u2014 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" ] }, "PlatformLineItem": { "type": "object", "description": "Line item for platform calculations. **Important: amount is PER-UNIT. Total = amount \u00d7 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 \u00d7 quantity.", "example": 2500 }, "quantity": { "type": "integer", "description": "Number of units. Taxable base = amount \u00d7 quantity.", "example": 3, "minimum": 0 } }, "required": [ "amount", "quantity" ] }, "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": { "description": "The address actually used for tax calculation, populated even for IP-based requests.", "$ref": "#/components/schemas/Address" } } }, "PlatformTransactionRequest": { "type": "object", "description": "Request body for creating transactions from a platform calculation", "properties": { "platform_calculation_id": { "type": "string", "description": "The ID of the platform calculation to convert to transactions" }, "reference_order_id": { "type": "string", "description": "Your unique identifier for this order" }, "reference_payment_id": { "type": "string", "description": "Your unique identifier for the payment (optional)" }, "transaction_processed_at": { "type": "number", "description": "Unix timestamp when the transaction was processed" } }, "required": [ "platform_calculation_id", "reference_order_id" ] }, "PlatformTransactionListResponse": { "type": "object", "description": "Response containing the list of created transactions. Payment processors receive two transactions (order + fee), while marketplace providers and merchants of record receive one.", "properties": { "object": { "type": "string", "example": "list" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformTransactionItem" } } } }, "PlatformTransactionItem": { "type": "object", "description": "A transaction created from a platform calculation", "properties": { "id": { "type": "string", "description": "Unique identifier for the transaction" }, "object": { "type": "string", "example": "tax.transaction" }, "calculation_id": { "type": "string", "description": "The platform calculation ID this transaction was created from" }, "reference_order_id": { "type": "string", "description": "Your reference order ID" }, "reference_payment_id": { "type": "string", "description": "Your reference payment ID (if provided)" }, "type": { "type": "string", "enum": [ "order", "fee" ], "description": "Whether this is an order transaction or a fee transaction" }, "client_role": { "type": "array", "items": { "type": "string", "enum": [ "payment_processor", "marketplace_provider", "merchant_of_record" ] }, "description": "The platform role(s) for this transaction. Fee transactions have an empty array." }, "merchant": { "type": "object", "properties": { "id": { "type": "string", "description": "The merchant ID" }, "reference_merchant_id": { "type": "string", "description": "Your reference merchant ID" } } }, "customer_currency_code": { "type": "string" }, "filing_currency_code": { "type": "string" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItem" } }, "testmode": { "type": "boolean" }, "transaction_processed_at": { "type": "number" } } }, "PlatformCalculationNotFoundError": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "type": { "type": "string", "example": "CALCULATION_NOT_FOUND" }, "message": { "type": "string", "example": "Platform calculation not found" } } }, "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" } } } }, "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" } } }, "TransactionRequest": { "type": "object", "properties": { "calculation_id": { "type": "string", "description": "The ID of the `calculation` that you want to record as a sale", "example": "calc_123456789" }, "reference_order_id": { "type": "string", "description": "The ID of this order in your system. Must be unique among all your `transactions`", "example": "343-45836" }, "transaction_processed_at": { "type": "number", "description": "Unix timestamp in **seconds** representing the date and time your sale was made. If not provided, the current date and time will be used.", "example": 1714787673 }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "calculation_id", "reference_order_id" ] }, "TransactionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the `transaction`. We highly recommend you store this value. If you need to refund or query the data from this transaction, you will use this ID as a reference.", "example": "tr_123456789" }, "object": { "type": "string", "description": "The type of object: `tax.transaction`.", "example": "tax.transaction" }, "calculation_id": { "type": "string", "description": "The ID of the `calculation` that was used to create this transaction", "example": "calc_123456789" }, "reference_order_id": { "type": "string", "description": "The unique order ID you provided when creating the `transaction`", "example": "343-45836" }, "transaction_processed_at": { "type": "number", "description": "Unix timestamp in **seconds** representing the date and time your sale was made. If not provided, the date and time this `transaction` was created", "example": 1714787673 }, "customer_currency_code": { "type": "string", "description": "The ISO-4217 currency code of the transaction", "example": "USD" }, "filing_currency_code": { "type": "string", "description": "The currency code of the filing that will be used to remit taxes collected on this transaction", "example": "USD" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItem" } }, "testmode": { "type": "boolean", "description": "`True` if using a production API key. If `true`, Numeral will record this `transaction` towards your nexus totals. If you're registered and collecting in the relevant jurisdiction, we'll file the tax.", "example": false }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "RefundResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the `refund`. We recommend you store this value. If you need to reverse this refund, you will be required to reference this ID.", "example": "ref_tr_123456789" }, "object": { "type": "string", "description": "The type of object: `tax.refund`.", "example": "tax.refund" }, "refund_type": { "type": "string", "description": "This will be either `'full'` or `'partial'`.", "example": "partial" }, "testmode": { "type": "boolean", "description": "`True` if using a production API key. `False` if using a test API key.", "example": false }, "refund_processed_at": { "type": "number", "description": "Unix timestamp in **seconds** representing the date and time the refund was made. If not provided, the time the `refund` was created will be used.", "example": 1714787673 }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/RefundTransactionLineItem" } } } }, "RefundForTransactionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the `refund`", "example": "ref_tr_123456789" }, "object": { "type": "string", "description": "The type of object: `tax.refund`.", "example": "tax.refund" }, "testmode": { "type": "boolean", "description": "`True` if using a production API key. `False` if using a test API key.", "example": false }, "refund_processed_at": { "type": "number", "description": "Unix timestamp in **seconds** representing the date and time the refund was made. If not provided, the time the refund was created will be used.", "example": 1714787673 }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/RefundTransactionLineItem" } } } }, "RefundRequest": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "The ID of the `transaction` to refund. This is the `transaction_id` returned from the `/transactions` creation response.", "example": "tr_123456789" }, "type": { "type": "string", "enum": [ "full", "partial" ], "description": "This will be either `'full'` or `'partial'`. If `type='partial'`, you must also provide the line item(s) you wish to apply refunds against.", "example": "partial" }, "refund_processed_at": { "type": "number", "description": "Unix timestamp in **seconds** representing the date and time the refund was made. If not provided, the current date and time will be used.", "example": 1714787673 }, "line_items": { "type": "array", "description": "If the refund is `type=full`, line items aren't necessary. If the refund is `type=partial`, you must provide the line item(s) you wish to apply refunds against using a `reference_product_id`.", "items": { "type": "object", "properties": { "reference_product_id": { "type": "string", "description": "The ID of the product to apply refunds against. We will attempt to find the line item from the original transaction based on this `reference_product_id`.", "example": "p-1233543" }, "reference_line_item_id": { "type": "string", "description": "This **optional** attribute is the ID of the line item from your system. It will be used only for reporting.", "example": "line_123456789" }, "sales_amount_refunded": { "type": "number", "description": "The sale amount that was refunded to the customer on this line item, not inclusive of tax refunded.", "example": -200 }, "quantity": { "type": "number", "description": "The quantity of this product being refunded.", "example": 2 }, "tax_amount_refunded": { "type": "number", "description": "The amount of tax that was refunded to the customer.", "example": -14 } } } } }, "required": [ "transaction_id", "type" ] }, "CalculationRequest": { "type": "object", "properties": { "customer": { "description": "Customer details. At least one of `customer.address` or `customer.ip` must be provided. Optionally accepts a customer ID for order tracking and exemptions.", "$ref": "#/components/schemas/CustomerDetails" }, "origin_address": { "description": "The address that a product is shipped from. Required at calculation time unless a default origin address is configured for the destination jurisdiction on your account \u2014 omitting it with no default configured returns a 400.", "$ref": "#/components/schemas/Address" }, "order_details": { "$ref": "#/components/schemas/OrderDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "transacted_at": { "type": "integer", "description": "Optional. The time the transaction occurred, as a Unix timestamp in **seconds** (not milliseconds). Used to determine which tax rates and rules apply at the time of the transaction (for example, during sales tax holidays), as well as other time-dependent inputs such as out-of-state-seller status. 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 integration partners always pass a customer ID without first ensuring the customer has been created. When the lookup misses, this value drives tax-exemption logic and business tax-ID validation as if it were `customer.type`. If a matching customer is found, the stored `customer.type` takes precedence. Available in API version `2026-03-01` and later.", "example": "CONSUMER" }, "invalid_tax_id_customer_fallback_type": { "type": "string", "enum": [ "CONSUMER" ], "description": "Optional. When business tax ID validation fails, fall back to treating the customer as this type instead of returning a 400. `CONSUMER` is the only accepted value. Available in API version `2026-01-01` and later.", "example": "CONSUMER" } }, "required": [ "customer", "order_details" ] }, "Metadata": { "type": "object", "description": "You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).", "properties": { "example_key": { "type": "string", "description": "Storing things like an order number may be useful for reporting and reconciliation.", "example": "example_value" } } }, "CustomerDetails": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the customer that you created in our system. Can be used to log customer information or indicate that a purchaser is tax exempt. Pair with the top-level `default_customer_type` to avoid a 400 when the ID has not yet been created in Numeral.", "example": "cust_123456789" }, "type": { "type": "string", "enum": [ "CONSUMER", "BUSINESS" ], "default": "CONSUMER", "description": "`CONSUMER` are private individuals who are not registered for VAT/GST. `BUSINESS` are companies, sole-proprietors, or other legal entities registered for VAT/GST. Defaults to `CONSUMER` when omitted.", "example": "CONSUMER" }, "tax_ids": { "type": "array", "description": "Array of tax identification numbers. Required when `type` is `BUSINESS` and the address is outside the US (not enforced for IP-only requests).", "items": { "$ref": "#/components/schemas/TaxId" } }, "skip_tax_id_validation": { "type": "boolean", "default": false, "description": "When `true`, skips validation of the provided `tax_ids` (format and registry checks). Defaults to `false`.", "example": false }, "address": { "description": "The customer (destination) address. Optional when `ip` is provided \u2014 with an IP present, address-quality problems fall back to IP resolution instead of returning a 400. Supports 82 destination countries: US, CA, EU member states, plus CY, CH, NO, GB, AU, NZ, SG, ID, VN, PH, TH, KR, JP, IN, TR, SA, AE, AR, CL, EG, HK, MO, IL, AL, TW, MY, BD, ZA, KE, UG, MA, BH, OM, CI, CM, GH, NG, BJ, NE, CV, IS, RS, GE, MD, MK, ME, CO, PE, UY, BB, BS, LA, LI, KZ, TZ. For US and CA, `address_postal_code` is required and `address_province` is required \u2014 a valid uppercase USPS state code for US, province code for CA. Fallback only: if `address_province` is missing or empty on a US address, Thomas attempts to infer the state from a valid 5-digit ZIP; an unrecognized ZIP returns a 400 `MALFORMED_ADDRESS`. Do not rely on this \u2014 always send the state.", "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "address_type": { "type": "string", "enum": [ "shipping", "billing" ], "description": "The type of address. For physical goods, `shipping` should be used. For software and digital goods, `billing` is more appropriate. Only valid on `customer.address` \u2014 including it on `origin_address` returns a 400 `UNRECOGNIZED_FIELD` error.", "example": "shipping" } }, "required": [ "address_type" ] } ] }, "ip": { "type": "object", "description": "IP address for geo-based tax resolution. Either address or ip (or both) must be provided. If both are given, the address is used first and the IP acts as a fallback for address-quality errors. An invalid IP format returns a 400 `INVALID_IP_FORMAT`.", "properties": { "value": { "type": "string", "description": "A valid IPv4 or IPv6 address. Only required when an `ip` object is provided \u2014 omit `ip` entirely for address-only calculations.", "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." }, "OrderDetails": { "type": "object", "properties": { "customer_currency_code": { "type": "string", "description": "The ISO-4217 currency code of the transaction. Supports 126 currencies (the full Stripe-supported list): AED, ALL, AMD, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BIF, BMD, BND, BOB, BRL, BSD, BWP, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HTG, HUF, IDR, ILS, INR, ISK, JMD, JPY, KES, KGS, KHR, KMF, KRW, KYD, KZT, LAK, LKR, LRD, LSL, MAD, MDL, MGA, MKD, MNT, MOP, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RWF, SAR, SBD, SCR, SEK, SGD, SOS, SRD, SZL, THB, TJS, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VND, VUV, WST, XAF, XCD, XCG, XOF, XPF, YER, ZAR, ZMW.", "example": "USD" }, "tax_included_in_amount": { "type": "boolean", "description": "For the line items in this transaction, does the amount include tax? This should typically be `false` for most North American sales, but may vary by jurisdiction and business model.", "example": false }, "automatic_tax": { "type": "string", "enum": [ "auto", "disabled" ], "description": "Controls automatic tax behavior. `auto`: return real rates if client is registered/enabled in that jurisdiction. `disabled`: always return 0 tax rates regardless of registration status. Required, and must be `auto` when the customer address is in the US.", "example": "auto" }, "line_items": { "type": "array", "description": "Each line item should represent one type of product. For compliance, we require either a `reference_product_id` or a `product_category`.", "items": { "$ref": "#/components/schemas/LineItem" } } }, "required": [ "customer_currency_code", "tax_included_in_amount", "automatic_tax", "line_items" ] }, "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" ] }, "LineItem": { "type": "object", "properties": { "reference_line_item_id": { "type": "string", "description": "The ID of the line item from your system. This field is optional and will be primarily used for record keeping.", "example": "line_123456789" }, "reference_product_id": { "type": "string", "description": "The product ID is used to uniquely reference this product in your system as well as in Numeral. Required if no `product_category`.", "example": "p-1233543" }, "product_category": { "type": "string", "description": "A tax category from our category taxonomy. Required if no `reference_product_id`.", "example": "GENERAL_MERCHANDISE" }, "fallback_product_category": { "type": "string", "description": "Optional fallback product category used when `reference_product_id` is provided but no matching product exists in Numeral. Lets integration partners always pass a product ID without first ensuring the product has been created. Must be a valid product category from the Numeral taxonomy \u2014 an invalid value returns a 400. If a matching product is found, its stored category takes precedence.", "example": "GENERAL_MERCHANDISE" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9999999999999, "description": "The **per-unit price** in the currency's smallest unit. The taxable base is calculated as `amount x quantity`. (e.g., if USD then 2000 = $20.00 per unit; with `quantity: 3` the taxable base is $60.00.) Before 2026-01-01, `amount` was the total for the line.", "example": 2000 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "The quantity of this product being sold. The taxable base is `amount x quantity`.", "example": 1 } }, "required": [ "quantity", "amount" ] }, "CalculationResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the `calculation`. You will use this to create a `transaction`.", "example": "calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3" }, "object": { "type": "string", "description": "The type of object: `tax.calculation`.", "example": "tax.calculation" }, "customer_currency_code": { "type": "string", "description": "The ISO-4217 currency code of the transaction.", "example": "USD" }, "customer": { "type": "object", "description": "Customer information returned in the response. `type` reflects the effective customer type used for the calculation (e.g., after `default_customer_type` or `invalid_tax_id_customer_fallback_type` is applied).", "properties": { "type": { "type": "string", "enum": [ "CONSUMER", "BUSINESS" ], "description": "The type of customer. `CONSUMER` are private individuals. `BUSINESS` are companies or legal entities registered for VAT/GST.", "example": "CONSUMER" }, "tax_ids": { "type": "array", "description": "Echo of the `tax_ids` provided in the request, when present.", "items": { "$ref": "#/components/schemas/TaxId" } } } }, "automatic_tax": { "type": "string", "enum": [ "auto", "disabled" ], "description": "The automatic tax setting for this calculation.", "example": "auto" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItem" } }, "tax_included_in_amount": { "type": "boolean", "example": false }, "total_tax_amount": { "type": "integer", "description": "Total tax to charge on this `calculation`, in the currency's smallest unit (rounded to an integer).", "example": 140 }, "total_amount_excluding_tax": { "type": "integer", "description": "Total sale charge excluding tax, in the currency's smallest unit (rounded to an integer).", "example": 2000 }, "total_amount_including_tax": { "type": "integer", "description": "Total sale charge plus tax, in the currency's smallest unit (rounded to an integer). What you should charge your customer.", "example": 2140 }, "expires_at": { "type": "integer", "description": "Unix timestamp in **seconds** at which the quoted tax rates expire \u2014 24 hours after the calculation is created.", "example": 1714787673 }, "testmode": { "type": "boolean", "description": "`True` if using a production API key. `False` if using a test API key.", "example": false }, "address_resolution_status": { "type": "string", "enum": [ "EXACT", "POSTAL_FALLBACK_1", "POSTAL_ONLY" ], "description": "Status of address resolution for the customer address. `EXACT`: exact address match found, `POSTAL_FALLBACK_1`: used postal code fallback, `POSTAL_ONLY`: only postal code was used for tax calculation.", "example": "EXACT" }, "address_used": { "description": "The actual address used for tax calculation after resolution.", "$ref": "#/components/schemas/Address" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "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" } } }, "TransactionLineItem": { "type": "object", "properties": { "line_item_id": { "type": "string", "description": "Numeral-generated ID for this line item.", "example": "li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f7f" }, "product": { "type": "object", "description": "Product information for this line item.", "properties": { "reference_product_name": { "type": "string", "description": "The name of the product.", "example": "Red Shoes" }, "reference_line_item_id": { "type": "string", "description": "The ID of the line item from your system.", "example": "line_123456789" }, "reference_product_id": { "type": "string", "description": "The product ID in your system.", "example": "p-1233543" }, "product_tax_code": { "type": "string", "description": "The tax code applied to this product.", "example": "GENERAL_MERCHANDISE" } } }, "tax_jurisdictions": { "type": "array", "description": "Array of tax jurisdictions that apply to this line item.", "items": { "type": "object", "properties": { "tax_rate": { "type": "number", "description": "The tax rate for this jurisdiction, rounded to 6 decimal places. This is the statutory rate for the jurisdiction and may apply to only part of the line item amount (for example, Tennessee single article rules). Do not sum rates across jurisdictions to derive an effective rate; use `tax_amount / amount_excluding_tax` instead.", "example": 0.07 }, "tax_due_decimal": { "type": "number", "description": "The unrounded tax due for this jurisdiction, in the currency's smallest unit. May be fractional (it is not rounded to an integer). `0` for flat-fee jurisdictions \u2014 see `fee_amount` instead.", "example": 724.9275 }, "fee_amount": { "type": "number", "description": "Any fixed fee amount for this jurisdiction.", "example": 0 }, "rate_type": { "type": "string", "description": "Descriptive rate classification for this jurisdiction.", "example": "GENERAL STATE SALES TAX" }, "tax_authority_name": { "type": "string", "description": "Name of the tax authority.", "example": "Tennessee" }, "tax_authority_type": { "type": "string", "description": "Type of tax authority (e.g., STATE, COUNTY, CITY, DISTRICT).", "example": "" }, "tax_type": { "type": "string", "description": "Type of tax: SALES, USE, VAT, or GST.", "example": "SALES" } } } }, "quantity": { "type": "number", "description": "The quantity of this product.", "example": 2 }, "tax_amount": { "type": "number", "description": "The tax amount for this line item.", "example": 14 }, "amount_excluding_tax": { "type": "number", "description": "The line item amount excluding tax.", "example": 200 }, "amount_including_tax": { "type": "number", "description": "The line item amount including tax.", "example": 214 } } }, "RefundTransactionLineItem": { "allOf": [ { "$ref": "#/components/schemas/TransactionLineItem" } ] }, "ProductRequest": { "type": "object", "properties": { "reference_product_id": { "type": "string", "description": "The ID of the product", "example": "p-123456789" }, "reference_product_name": { "type": "string", "description": "The name of the product", "example": "Red Shoes" }, "product_category": { "type": "string", "description": "The category of the product", "example": "CLOTHING_GENERAL" } }, "required": [ "reference_product_id", "reference_product_name", "product_category" ] }, "ProductResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object: `tax.product`.", "example": "tax.product" }, "reference_product_id": { "type": "string", "description": "The ID of the created product", "example": "p-20506" }, "reference_product_name": { "type": "string", "description": "The name of the created product", "example": "Red Shoes" }, "product_category": { "type": "string", "description": "The category of the created product", "example": "CLOTHING_GENERAL" }, "created_at": { "type": "number", "description": "Epoch datetime representing the date and time the product was created", "example": 1721694425 }, "updated_at": { "type": "number", "description": "Epoch datetime representing the date and time the product was last updated", "example": 1721694425 }, "testmode": { "type": "boolean", "description": "`True` if using a production API key. `False` if using a test API key.", "example": true } } }, "CustomerRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The customer's name", "example": "Customer Name" }, "email": { "type": "string", "description": "The customer's email", "example": "customer@example.com" }, "is_tax_exempt": { "type": "boolean", "description": "If true, all `POST /tax/calculations` sold to this customer will return $0 in tax owed. The default value is `false`.", "example": true }, "reference_customer_id": { "type": "string", "description": "The ID of the customer in your system", "example": "20506" } }, "required": [ "email" ] }, "CustomerUpdateRequest": { "type": "object", "description": "Request body for updating a customer. All fields are optional, but at least one must be provided.", "properties": { "name": { "type": "string", "description": "The customer's name", "example": "New Customer Name" }, "email": { "type": "string", "description": "The customer's email. Must be unique across your customers.", "example": "new.email@example.com" }, "is_tax_exempt": { "type": "boolean", "description": "If true, all `POST /tax/calculations` sold to this customer will return $0 in tax owed.", "example": true }, "reference_customer_id": { "type": "string", "description": "The ID of the customer in your system. Must be unique across your customers.", "example": "20507" } } }, "CustomerResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the customer", "example": "cust_123456789" }, "object": { "type": "string", "description": "The type of object: `tax.customer`", "example": "tax.customer" }, "reference_customer_id": { "type": "string", "description": "The ID of the customer in your system", "example": "20506" }, "name": { "type": "string", "description": "The name of the created customer", "example": "Customer Name" }, "email": { "type": "string", "description": "The email of the created customer", "example": "customer@example.com" }, "is_tax_exempt": { "type": "boolean", "description": "If true, all `POST /tax/calculations` sold to this customer will return $0 in tax owed. The default value is `false`.", "example": true } } }, "DeleteTransactionResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object deleted", "example": "tax.transaction" }, "deleted_at": { "type": "number", "description": "Epoch datetime representing the date and time the object was deleted", "example": 1721782604 } } }, "DeleteProductResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object deleted", "example": "tax.product" }, "deleted_at": { "type": "number", "description": "Epoch datetime representing the date and time the object was deleted", "example": 1721782604 } } }, "CustomerListResponse": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerResponse" } }, "has_more": { "type": "boolean", "description": "Whether there are more customers to fetch" }, "last_customer_id": { "type": "string", "description": "Use as cursor for next page" } } }, "DeleteCustomerResponse": { "type": "object", "properties": { "object": { "type": "string", "description": "The type of object deleted", "example": "tax.customer" }, "deleted_at": { "type": "number", "description": "Epoch datetime representing the date and time the object was deleted", "example": 1721782604 } } }, "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" ] }, "ProductNotFoundError": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "type": { "type": "string", "example": "PRODUCT_NOT_FOUND" }, "message": { "type": "string", "example": "Product not found" } } }, "CalculationNotFoundError": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "type": { "type": "string", "example": "CALCULATION_NOT_FOUND" }, "message": { "type": "string", "example": "Calculation not found" } } }, "TransactionNotFoundError": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "type": { "type": "string", "example": "TRANSACTION_NOT_FOUND" }, "message": { "type": "string", "example": "Transaction not found" } } }, "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" } } }, "PingResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "env": { "type": "string", "enum": [ "test", "prod" ] }, "timestamp": { "type": "string", "format": "date-time" }, "api_version": { "type": "string" } } }, "AuthError": { "type": "object", "properties": { "code": { "type": "integer", "example": 401 }, "type": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Invalid or missing API key" } } }, "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." } } }, "InvalidIpFormatError": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "type": { "type": "string", "example": "INVALID_IP_FORMAT" }, "message": { "type": "string", "example": "ip.value must be a valid IPv4 or IPv6 address" } } }, "CertificateRequestStatus": { "type": "string", "enum": [ "pending", "fulfilled", "canceled", "invalid" ], "description": "Public lifecycle state of a certificate request. The internal status enum is narrower in the public vocabulary on purpose \u2014 `processing` collapses to `pending`, `failed` collapses to `invalid`." }, "CertificateStatus": { "type": "string", "enum": [ "processing", "needs_info", "active", "expiring", "expired", "invalid" ], "description": "Public lifecycle state of an exemption certificate. `expiring` and `expired` are distinct from `invalid` so a renewable lapse is distinguishable from a revoked or rejected certificate." }, "CustomerLink": { "type": "object", "description": "The customer this object is linked to. `id` is the Numeral `cust_*` id; `reference_customer_id` is the value you supplied when the customer was created (may be null); `name` is the customer's display name (falls back to the linked master buyer's legal name when the customer record has no name of its own).", "properties": { "id": { "type": "string", "example": "cust_6126acaf-7379-411a-8ada-00005bac0715" }, "reference_customer_id": { "type": "string", "nullable": true, "example": "20506" }, "name": { "type": "string", "nullable": true, "description": "Display name for the linked customer. Populated from `Customer.name`; falls back to the master buyer's `legal_name` if the customer record has no name of its own. `null` only when neither is set.", "example": "Acme Co" } }, "required": [ "id", "reference_customer_id", "name" ] }, "LinkedBuyer": { "type": "object", "description": "The master buyer entity that owns this certificate or request. Distinct from `customer` (which is a specific `Customer` record) \u2014 `linked_buyer` is populated whenever the object has a master-buyer reference, even when no `Customer` record has been linked yet. Clients rendering \"who owns this cert\" should prefer this field.", "properties": { "id": { "type": "string", "description": "Stable numeric id of the master buyer.", "example": "12345" }, "legal_name": { "type": "string", "nullable": true, "example": "Acme Co" } }, "required": [ "id", "legal_name" ] }, "CertificateRequestResponse": { "type": "object", "description": "A single certificate request.", "properties": { "id": { "type": "string", "description": "The ID of the certificate request", "example": "cert_req_b2f1e4a3-9c0d-4e7a-8b1f-2d5a6e7b8c9d" }, "object": { "type": "string", "description": "The type of object: `tax.certificate_request`", "example": "tax.certificate_request" }, "status": { "$ref": "#/components/schemas/CertificateRequestStatus" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerLink" } ], "nullable": true, "description": "The specific `Customer` record linked to this request. `null` when no live Customer has been associated yet (a master buyer may still be present \u2014 see `linked_buyer`)." }, "linked_buyer": { "allOf": [ { "$ref": "#/components/schemas/LinkedBuyer" } ], "nullable": true, "description": "The master buyer entity that owns this request. Populated whenever the request has a master-buyer reference, even when no `Customer` record has been linked yet. Prefer this over `customer` for rendering \"who owns this request\"." }, "certificate_id": { "type": "string", "nullable": true, "description": "Populated only when `status === \"fulfilled\"`. The `cert_*` id of the submitted certificate.", "example": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e" }, "certificate_type_id": { "type": "string", "nullable": true, "description": "Stable identifier of the requested certificate type, e.g. `US-CA-CDTFA-230`.", "example": "US-CA-CDTFA-230" }, "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "Jurisdiction identifiers covered by the request.", "example": [ "US-CA" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the request will auto-expire if not fulfilled. `null` if the request does not auto-expire." }, "livemode": { "type": "boolean", "enum": [ true ], "description": "Always `true` \u2014 these endpoints are live-only." } }, "required": [ "id", "object", "status", "customer", "linked_buyer", "certificate_id", "certificate_type_id", "jurisdictions", "created_at", "updated_at", "expires_at", "livemode" ] }, "CertificateRequestListResponse": { "type": "object", "description": "A paginated list of certificate requests.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "certificate_requests": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateRequestResponse" } }, "has_more": { "type": "boolean", "description": "Whether there are more certificate requests to fetch." }, "next_cursor": { "type": "string", "description": "Pass as `cursor` on the next request. Omitted (not `null`) on the final page." } }, "required": [ "object", "certificate_requests", "has_more" ] }, "CertificateType": { "type": "object", "description": "The type of an exemption certificate.", "properties": { "id": { "type": "string", "description": "Stable numeric identifier of the certificate type.", "example": "12" }, "name": { "type": "string", "example": "California Resale Certificate (CDTFA-230)" }, "certificate_identifier": { "type": "string", "description": "Stable, human-readable identifier \u2014 use this in filters and references.", "example": "US-CA-CDTFA-230" } }, "required": [ "id", "name", "certificate_identifier" ] }, "CertificateJurisdictionEntry": { "type": "object", "description": "Per-jurisdiction validity for a certificate.", "properties": { "jurisdiction_id": { "type": "string", "example": "US-CA" }, "status": { "$ref": "#/components/schemas/CertificateStatus" }, "effective_date": { "type": "string", "format": "date", "nullable": true }, "expiration_date": { "type": "string", "format": "date", "nullable": true } }, "required": [ "jurisdiction_id", "status", "effective_date", "expiration_date" ] }, "CertificateResponse": { "type": "object", "description": "A single exemption certificate.", "properties": { "id": { "type": "string", "example": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e" }, "object": { "type": "string", "description": "The type of object: `tax.exemption_certificate`", "example": "tax.exemption_certificate" }, "status": { "$ref": "#/components/schemas/CertificateStatus" }, "certificate_type": { "allOf": [ { "$ref": "#/components/schemas/CertificateType" } ], "nullable": true }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerLink" } ], "nullable": true, "description": "The specific `Customer` record linked to this certificate. `null` when no live Customer has been associated yet (a master buyer may still be present \u2014 see `linked_buyer`)." }, "linked_buyer": { "allOf": [ { "$ref": "#/components/schemas/LinkedBuyer" } ], "nullable": true, "description": "The master buyer entity that owns this certificate. Populated whenever the certificate has a master-buyer reference, even when no `Customer` record has been linked yet. Prefer this over `customer` for rendering \"who owns this certificate\"." }, "jurisdictions": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateJurisdictionEntry" } }, "effective_date": { "type": "string", "format": "date", "nullable": true }, "expiration_date": { "type": "string", "format": "date", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "livemode": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "status", "certificate_type", "customer", "linked_buyer", "jurisdictions", "effective_date", "expiration_date", "created_at", "updated_at", "livemode" ] }, "CertificateDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/CertificateResponse" }, { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri", "nullable": true, "description": "Pre-signed URL to download the original certificate document. Expires one hour after issuance \u2014 refetch the certificate to mint a new URL. `null` (response still `200`) when no document is attached yet. Treat as confidential." } }, "required": [ "download_url" ] } ] }, "CertificateListResponse": { "type": "object", "description": "A paginated list of exemption certificates.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "certificates": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateResponse" } }, "has_more": { "type": "boolean", "description": "Whether there are more certificates to fetch." }, "next_cursor": { "type": "string", "description": "Pass as `cursor` on the next request. Omitted (not `null`) on the final page." } }, "required": [ "object", "certificates", "has_more" ] }, "CertificateUploadStatus": { "type": "string", "enum": [ "processing", "completed", "failed", "duplicate" ], "description": "Processing state of a certificate upload. This is a separate vocabulary from certificate `status` \u2014 an upload is a processing job, a certificate is its output. `processing` is the only non-terminal state; `completed` (certificates produced), `failed` (see `error_message`), and `duplicate` (same document already submitted) are terminal." }, "CertificateUploadCustomerInput": { "type": "object", "description": "Pre-maps the resulting certificate to a customer. Supply at least one of `id` or `reference_customer_id`. Either alone is sufficient; if both are present and resolve to different customers the request fails with `BUYER_IDENTITY_CONFLICT` (409) and nothing is written.", "properties": { "id": { "type": "string", "description": "Existing Numeral customer id. An unknown id returns `CUSTOMER_NOT_FOUND` (404).", "example": "cust_6126acaf-7379-411a-8ada-00005bac0715" }, "reference_customer_id": { "type": "string", "description": "Your own identifier for the customer. An unknown value creates the customer, so pre-mapping works before the customer exists in Numeral.", "example": "20506" } }, "minProperties": 1 }, "CertificateUploadRequest": { "type": "object", "properties": { "document_url": { "type": "string", "format": "uri", "description": "An `https` URL that Numeral's servers can `GET` \u2014 typically a presigned URL to your own storage. Fetched server-side. The file must be a PDF, PNG, or JPEG (detected from content, not extension or `Content-Type`), at most 10 MB, reachable within 3 redirects (each hop must also be `https`).", "example": "https://your-bucket.s3.amazonaws.com/certs/resale.pdf?X-Amz-Signature=..." }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name for the document (1\u2013255 characters). Defaults to the URL's basename when it has an extension, otherwise to a generic name derived from the detected file type.", "example": "resale.pdf" }, "customer": { "$ref": "#/components/schemas/CertificateUploadCustomerInput" } }, "required": [ "document_url" ] }, "CertificateUploadCustomer": { "type": "object", "description": "The customer the upload was attributed to at submission.", "properties": { "id": { "type": "string", "example": "cust_6126acaf-7379-411a-8ada-00005bac0715" }, "reference_customer_id": { "type": "string", "nullable": true, "example": "20506" } }, "required": [ "id", "reference_customer_id" ] }, "CertificateUploadResponse": { "type": "object", "description": "A certificate upload \u2014 the asynchronous processing job created by `POST /tax/certificates`.", "properties": { "id": { "type": "string", "description": "Upload id, `upl_`. Endpoints that accept an upload id also accept the bare numeric form.", "example": "upl_4471" }, "object": { "type": "string", "description": "The type of object: `tax.certificate_upload`", "example": "tax.certificate_upload" }, "status": { "$ref": "#/components/schemas/CertificateUploadStatus" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CertificateUploadCustomer" } ], "nullable": true, "description": "The customer supplied at submission. `null` when the upload was submitted without a customer \u2014 attribution then happens during processing." }, "certificate_ids": { "type": "array", "items": { "type": "string", "example": "cert_a8f3d2c1-1b9a-4c5e-8d7e-6f4a3b2c1d0e" }, "description": "Certificates produced by this upload, usable with the certificate endpoints. Empty while `status` is `processing`; populated at `completed`. One document can yield multiple certificates." }, "error_message": { "type": "string", "nullable": true, "description": "Human-readable reason processing failed. Also set on `duplicate` uploads when the original upload had failed, so you can see why re-submitting the same bytes will not help." }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "livemode": { "type": "boolean", "enum": [ true ], "description": "Always `true` \u2014 these endpoints are live-only." } }, "required": [ "id", "object", "status", "customer", "certificate_ids", "error_message", "created_at", "livemode" ] }, "CertificateUploadDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/CertificateUploadResponse" }, { "type": "object", "properties": { "document_url": { "type": "string", "format": "uri", "nullable": true, "description": "Pre-signed URL to the originally submitted document. Valid for one hour \u2014 refetch the upload to mint a new URL. May be non-null while `status` is still `processing`. `null` (response still `200`) when no document is attached. Not returned by the list endpoint. Treat as confidential." } }, "required": [ "document_url" ] } ] }, "CertificateUploadListResponse": { "type": "object", "description": "A paginated list of certificate uploads.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "certificate_uploads": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateUploadResponse" } }, "has_more": { "type": "boolean", "description": "Whether there are more uploads to fetch." }, "next_cursor": { "type": "string", "description": "Pass as `cursor` on the next request. Present only when `has_more` is `true`.", "example": "upl_4471" } }, "required": [ "object", "certificate_uploads", "has_more" ] }, "CertificateUploadNotFoundError": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "type": { "type": "string", "example": "CERTIFICATE_UPLOAD_NOT_FOUND" }, "message": { "type": "string", "example": "Certificate upload not found" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }