{ "openapi": "3.0.1", "info": { "title": "Numeral API", "description": "API for sales tax calculations", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.numeralhq.com/" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/tax/calculations": { "post": { "description": "Get tax information for a given product and address", "parameters": [ { "name": "X-API-Version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-03-01", "2026-01-01", "2025-05-12", "2024-09-01" ] }, "description": "API version to use.", "example": "2026-03-01" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "API Version 2026-03-01", "$ref": "#/components/schemas/CalculationRequestV202603" }, { "title": "API Version 2026-01-01", "$ref": "#/components/schemas/CalculationRequestV2025" }, { "title": "API Version 2025-05-12", "$ref": "#/components/schemas/CalculationRequestV2025" }, { "title": "API Version 2024-09-01", "$ref": "#/components/schemas/CalculationRequest" } ] }, "examples": { "2024-09-01": { "summary": "Basic calculation (API version 2024-09-01)", "value": { "customer": { "address": { "address_line_1": "4 Privet Drive", "address_city": "Little Whining", "address_province": "CA", "address_postal_code": "90210", "address_country": "US", "address_type": "shipping" } }, "order_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "line_items": [ { "reference_product_id": "wand_elder_12", "amount": 10000, "quantity": 1 } ] } } }, "2026-03-01": { "summary": "IP-based calculation (API version 2026-03-01)", "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": [ { "reference_line_item_id": "line_123456789", "product_category": "SAAS_GENERAL", "amount": 10000, "quantity": 2 } ] } } }, "2026-01-01": { "summary": "Per-unit pricing calculation (API version 2026-01-01)", "value": { "customer": { "type": "CONSUMER", "address": { "address_line_1": "4 Privet Drive", "address_city": "Little Whinging", "address_province": "CA", "address_postal_code": "90210", "address_country": "US", "address_type": "shipping" } }, "origin_address": { "address_line_1": "3990 N County Rd 300 E", "address_line_2": "Unit 2", "address_city": "Danville", "address_province": "IN", "address_postal_code": "46122", "address_country": "US" }, "order_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "reference_line_item_id": "line_20260101", "product_category": "GENERAL_MERCHANDISE", "amount": 2500, "quantity": 3 } ] } } }, "2025-05-12-consumer": { "summary": "Enhanced consumer calculation (API version 2025-05-12)", "value": { "customer": { "type": "CONSUMER", "address": { "address_line_1": "4 Privet Drive", "address_city": "Little Whinging", "address_province": "CA", "address_postal_code": "90210", "address_country": "US", "address_type": "shipping" } }, "origin_address": { "address_line_1": "3990 N County Rd 300 E", "address_line_2": "Unit 2", "address_city": "Danville", "address_province": "IN", "address_postal_code": "46122", "address_country": "US" }, "order_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "reference_product_id": "wand_elder_12", "amount": 10000, "quantity": 1 } ] } } }, "2025-05-12-business": { "summary": "Business customer with tax IDs (API version 2025-05-12)", "value": { "customer": { "type": "BUSINESS", "tax_ids": [ { "type": "gb_vat", "value": "GB123456789" } ], "address": { "address_line_1": "123 Business St", "address_city": "Commerce City", "address_province": "NY", "address_postal_code": "10001", "address_country": "US", "address_type": "billing" } }, "origin_address": { "address_line_1": "Tech Park 1", "address_city": "Dublin", "address_province": "L", "address_postal_code": "D02 XY45", "address_country": "IE" }, "order_details": { "customer_currency_code": "EUR", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "reference_product_id": "business_software_license", "amount": 50000, "quantity": 5 } ] } } }, "2025-05-12-US-standard": { "summary": "US standard consumer sale (API version 2025-05-12)", "value": { "customer": { "address": { "address_line_1": "4 Privet Drive", "address_city": "Little Whinging", "address_province": "CA", "address_postal_code": "92037", "address_country": "US", "address_type": "shipping" } }, "origin_address": { "address_line_1": "3990 N County Rd 300 E", "address_line_2": "Unit 2", "address_city": "Danville", "address_province": "IN", "address_postal_code": "46122", "address_country": "US" }, "order_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "reference_line_item_id": "line_123456789", "product_category": "SAAS_GENERAL", "amount": 200, "quantity": 2 } ] } } }, "2025-05-12-US-business": { "summary": "US business sale (API version 2025-05-12)", "value": { "customer": { "type": "BUSINESS", "tax_ids": [ { "type": "us_ein", "value": "12-3456789" } ], "address": { "address_line_1": "4 Privet Drive", "address_city": "Little Whinging", "address_province": "CA", "address_postal_code": "92037", "address_country": "US", "address_type": "billing" } }, "origin_address": { "address_line_1": "3990 N County Rd 300 E", "address_line_2": "Unit 2", "address_city": "Danville", "address_province": "IN", "address_postal_code": "46122", "address_country": "US" }, "order_details": { "customer_currency_code": "USD", "tax_included_in_amount": false, "automatic_tax": "auto", "line_items": [ { "reference_line_item_id": "line_123456789", "product_category": "SAAS_GENERAL", "amount": 200, "quantity": 2 } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Calculate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationResponse" }, "examples": { "2024-09-01": { "summary": "Basic calculation response (API version 2024-09-01)", "value": { "id": "calc_1726683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9", "object": "tax.calculation", "customer_currency_code": "USD", "line_items": [ { "product": { "reference_product_name": "Elder Wand", "reference_product_id": "wand_elder_12", "product_tax_code": "GENERAL_MERCHANDISE" }, "tax_jurisdictions": [ { "tax_rate": 0.1, "rate_type": "SALES TAX", "jurisdiction_name": "California", "fee_amount": 0 } ], "quantity": 1, "tax_amount": 1000, "amount_excluding_tax": 10000, "amount_including_tax": 11000 } ], "tax_included_in_amount": false, "total_tax_amount": 1000, "total_amount_excluding_tax": 10000, "total_amount_including_tax": 11000, "expires_at": 1726683511, "testmode": true, "address_resolution_status": "EXACT", "address_used": { "address_line_1": "4 Privet Drive", "address_city": "Little Whinging", "address_province": "CA", "address_postal_code": "90210", "address_country": "US" } } }, "2026-03-01": { "summary": "IP-based calculation response (API version 2026-03-01)", "value": { "id": "calc_17725714816806a81b828-0757-4ec2-9307-3c1001733f73", "object": "tax.calculation", "customer_currency_code": "USD", "customer": { "type": "CONSUMER" }, "automatic_tax": "auto", "line_items": [ { "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" } ], "quantity": 5, "tax_amount": 3500, "amount_excluding_tax": 50000, "amount_including_tax": 53500 } ], "total_tax_amount": 3500, "tax_included_in_amount": false, "total_amount_excluding_tax": 50000, "total_amount_including_tax": 53500, "expires_at": 1772657881, "testmode": true, "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" } }, "2026-01-01": { "summary": "Per-unit pricing response (API version 2026-01-01)", "value": { "id": "calc_1762683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9", "object": "tax.calculation", "customer_currency_code": "USD", "customer": { "type": "CONSUMER" }, "automatic_tax": "auto", "line_items": [ { "product": { "reference_product_name": "Elder Wand", "reference_product_id": "wand_elder_12", "product_tax_code": "GENERAL_MERCHANDISE" }, "tax_jurisdictions": [ { "tax_rate": 0.1, "tax_due_decimal": 750, "fee_amount": 0, "rate_type": "GENERAL STATE SALES TAX", "tax_authority_name": "California", "tax_authority_type": "STATE", "tax_type": "SALES" } ], "quantity": 3, "tax_amount": 750, "amount_excluding_tax": 7500, "amount_including_tax": 8250 } ], "tax_included_in_amount": false, "total_tax_amount": 750, "total_amount_excluding_tax": 7500, "total_amount_including_tax": 8250, "expires_at": 1762683511, "testmode": true, "address_resolution_status": "EXACT", "address_used": { "address_line_1": "4 Privet Drive", "address_city": "Little Whinging", "address_province": "CA", "address_postal_code": "90210", "address_country": "US" } } }, "2025-05-12": { "summary": "Enhanced B2B calculation response (API version 2025-05-12)", "value": { "id": "calc_1726683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9", "object": "tax.calculation", "customer_currency_code": "USD", "customer": { "type": "CONSUMER" }, "automatic_tax": "auto", "line_items": [ { "product": { "reference_product_name": "Elder Wand", "reference_product_id": "wand_elder_12", "product_tax_code": "GENERAL_MERCHANDISE" }, "tax_jurisdictions": [ { "tax_rate": 0.1, "rate_type": "SALES TAX", "jurisdiction_name": "California", "fee_amount": 0, "note": "Standard consumer sale" } ], "quantity": 1, "tax_amount": 1000, "amount_excluding_tax": 10000, "amount_including_tax": 11000 } ], "tax_included_in_amount": false, "total_tax_amount": 1000, "total_amount_excluding_tax": 10000, "total_amount_including_tax": 11000, "expires_at": 1726683511, "testmode": true, "address_resolution_status": "EXACT", "address_used": { "address_line_1": "4 Privet Drive", "address_city": "Little Whinging", "address_province": "CA", "address_postal_code": "90210", "address_country": "US" } } }, "2025-05-12-business": { "summary": "Business customer calculation response (API version 2025-05-12)", "value": { "id": "calc_1726683504829b84b2ad6-a4c9-4e0e-986f-7bb3d1fb17c9", "object": "tax.calculation", "customer_currency_code": "EUR", "customer": { "type": "BUSINESS" }, "automatic_tax": "auto", "line_items": [ { "product": { "reference_product_name": "Business Software License", "reference_product_id": "business_software_license", "product_tax_code": "SOFTWARE" }, "tax_jurisdictions": [ { "tax_rate": 0.0, "rate_type": "REVERSE CHARGE", "jurisdiction_name": "Cross-border B2B", "fee_amount": 0, "note": "Cross-border B2B sale to VAT-registered business, reverse charge applies" } ], "quantity": 5, "tax_amount": 0, "amount_excluding_tax": 250000, "amount_including_tax": 250000 } ], "tax_included_in_amount": false, "total_tax_amount": 0, "total_amount_excluding_tax": 250000, "total_amount_including_tax": 250000, "expires_at": 1726683511, "testmode": true, "address_resolution_status": "POSTAL_ONLY", "address_used": { "address_line_1": "123 Business St", "address_city": "Commerce City", "address_province": "NY", "address_postal_code": "10001", "address_country": "US" } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/MissingOriginAddressError" } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductNotFoundError" } } } } } } }, "/tax/transactions": { "post": { "description": "Record a completed sale", "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": { "description": "Add a refund to a transaction", "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": { "description": "Reverse a refund you've previously created", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refund_id": { "type": "string", "description": "The ID of the refund to reverse", "example": "ref_tr_123456789" } } } } }, "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": { "description": "Retrieve the details of a specific transaction", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the transaction to retrieve", "example": "tr_172175669911564a621fc-ab56-441b-959f-7b2587cc72f2" } ], "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": { "description": "Delete a specific transaction using its ID", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the transaction to delete", "example": "tr_1721782517712b5926847-d313-4721-9ee2-f8bde575d80b" } ], "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": { "description": "Retrieve the refunds for a specific transaction", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The transaction ID used to fetch associated refunds" } ], "responses": { "200": { "description": "List of refunds for a specific transaction", "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": { "description": "Retrieve the details of a specific product", "parameters": [ { "name": "reference_product_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the product to retrieve", "example": "p-20506" } ], "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": { "description": "Delete a specific product using its ID", "parameters": [ { "name": "reference_product_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the product to delete", "example": "p-309" } ], "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": { "description": "Retrieve a list of up to 50 products. If you have more than 50, you can paginate this endpoint.", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The product ID to start pagination from. This is the last product ID retrieved from the previous list request. An example path looks like `/tax/products?cursor=p-20506`" } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "has_more": { "type": "boolean", "description": "This will be either `true` or `false` depending on if there are more products to be returned in the next request.", "example": "false" }, "last_product_id": { "type": "string", "description": "The ID of the last product returned in the response. This can be used as a cursor for pagination.", "example": "p-20507" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductResponse" } } } }, "examples": { "multipleProducts": { "summary": "Multiple products example", "value": { "last_product_id": "p-20507", "products": [ { "object": "tax.product", "reference_product_id": "p-20506", "reference_product_name": "Red T-Shirt", "product_category": "CLOTHING", "created_at": 1721951003, "updated_at": 1721951003, "testmode": true }, { "object": "tax.product", "reference_product_id": "p-20507", "reference_product_name": "Blue T-Shirt", "product_category": "CLOTHING", "created_at": 1721951003, "updated_at": 1721951003, "testmode": true } ], "has_more": false } } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "description": "Create and categorize a new product", "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": { "post": { "description": "Create a new customer, and optionally mark them as tax exempt", "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": { "description": "Retrieve the details of a specific customer", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer to retrieve", "example": "cus_1234-65423" }, { "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" } } } } } }, "delete": { "description": "Delete a specific customer using its ID", "parameters": [ { "name": "customer_Id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer to delete", "example": "cus_1234-65423" } ], "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": { "description": "Authenticated health check endpoint that returns status, environment, timestamp, and API version", "summary": "Health Check Ping", "operationId": "pingHealthCheck", "parameters": [ { "name": "X-API-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2025-05-12", "2024-09-01" ], "default": "2024-09-01" }, "description": "API version to use. Defaults to 2024-09-01 if not specified.", "example": "2025-05-12" } ], "responses": { "200": { "description": "Successful health check response", "headers": { "X-Request-ID": { "description": "Unique request identifier", "schema": { "type": "string", "example": "req_123456789" } }, "Cache-Control": { "description": "Cache control directives", "schema": { "type": "string", "example": "no-cache, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" }, "examples": { "testmode": { "summary": "Test environment response", "description": "Response when using a testmode API key", "value": { "status": "ok", "env": "test", "timestamp": "2025-09-12T17:30:00.000Z", "api_version": "2025-05-12" } }, "production": { "summary": "Production environment response", "description": "Response when using a production API key", "value": { "status": "ok", "env": "prod", "timestamp": "2025-09-12T17:30:00.000Z", "api_version": "2024-09-01" } } } } } }, "400": { "description": "Bearer token not provided", "content": { "text/plain": { "schema": { "type": "string", "example": "Bearer token not provided." } } } }, "401": { "description": "Authentication errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" }, "examples": { "invalid_format": { "summary": "Invalid API key format", "value": { "error": "Invalid API Key format." } }, "not_found": { "summary": "API key not found", "value": { "error": "API key not found." } }, "not_active": { "summary": "API key not active", "value": { "error": "API key is not active." } }, "public_key_not_supported": { "summary": "Public key not supported", "value": { "error": "No public API key support currently." } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "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", "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": { "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": [ "reference_product_id", "sales_amount_refunded", "tax_amount_refunded" ] } }, "required": [ "transaction_id", "type" ] }, "CalculationRequest": { "type": "object", "properties": { "customer": { "description": "Customer details. Address is required. Optionally accepts a customer ID for order tracking and exemptions.", "$ref": "#/components/schemas/CustomerDetails" }, "origin_address": { "description": "Required from API version 2025-05-12+. The address that a product is shipped from.", "$ref": "#/components/schemas/Address" }, "order_details": { "$ref": "#/components/schemas/OrderDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "customer", "origin_address", "order_details" ] }, "CalculationRequestV2025": { "type": "object", "properties": { "customer": { "description": "Customer details. Address is required. Optionally accepts a customer ID for order tracking and exemptions.", "$ref": "#/components/schemas/CustomerDetailsV2025" }, "origin_address": { "description": "Required for API version 2025-05-12. The address that a product is shipped from.", "$ref": "#/components/schemas/Address" }, "order_details": { "$ref": "#/components/schemas/OrderDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "customer", "origin_address", "order_details" ] }, "CalculationRequestV202603": { "type": "object", "properties": { "customer": { "description": "Customer details. At least one of address or ip must be provided.", "$ref": "#/components/schemas/CustomerDetailsV202603" }, "origin_address": { "description": "Required from API version 2025-05-12+. The address that a product is shipped from.", "$ref": "#/components/schemas/Address" }, "order_details": { "$ref": "#/components/schemas/OrderDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "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" } }, "required": [ "customer", "origin_address", "order_details" ] }, "Metadata": { "type": "object", "description": "You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.", "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. For more, see [Creating a Customer](/api-reference/endpoint/customers).", "example": "cus_123456789" }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "address_type": { "type": "string", "description": "The type of address. Must be one of: `shipping` or `billing`. For physical goods, `shipping` should be used. For software and digital goods, `billing` is more appropriate", "example": "shipping" } }, "required": [ "address_type" ] } ] } }, "required": [ "address" ] }, "CustomerDetailsV2025": { "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. For more, see [Creating a Customer](/api-reference/endpoint/customers).", "example": "cus_123456789" }, "type": { "type": "string", "enum": [ "CONSUMER", "BUSINESS" ], "description": "The type of customer. Available with API version 2025-05-12. `CONSUMER` are private individuals who are not registered for VAT/GST (or any other local indirect-tax scheme) in the country where the supply is taxed. `BUSINESS` are companies, sole-proprietors, or other legal entities registered for VAT/GST (or an equivalent local tax) in the country where the supply is taxed.", "example": "CONSUMER" }, "tax_ids": { "type": "array", "description": "Array of tax identification numbers. Available with API version 2025-05-12. Only available for `BUSINESS` customer types.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the full list of supported types.", "example": "us_ein" }, "value": { "type": "string", "description": "The tax ID value" } }, "required": [ "type", "value" ] } }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "address_type": { "type": "string", "description": "The type of address. Must be one of: `shipping` or `billing`. For physical goods, `shipping` should be used. For software and digital goods, `billing` is more appropriate", "example": "shipping" } }, "required": [ "address_type" ] } ] } }, "required": [ "address" ] }, "CustomerDetailsV202603": { "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. For more, see [Creating a Customer](/api-reference/endpoint/customers).", "example": "cus_123456789" }, "type": { "type": "string", "enum": [ "CONSUMER", "BUSINESS" ], "description": "The type of customer. `CONSUMER` are private individuals. `BUSINESS` are companies, sole-proprietors, or other legal entities registered for VAT/GST.", "example": "CONSUMER" }, "tax_ids": { "type": "array", "description": "Array of tax identification numbers. Only available for `BUSINESS` customer types.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the full list of supported types.", "example": "us_ein" }, "value": { "type": "string", "description": "The tax ID value" } }, "required": [ "type", "value" ] } }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "address_type": { "type": "string", "description": "The type of address. Must be one of: `shipping` or `billing`. Required if `ip` is not provided.", "example": "shipping" } }, "required": [ "address_type" ] } ] }, "ip": { "type": "object", "description": "IP address for geo-based tax resolution. Required if `address` is not 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" ], "default": "strict", "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." } }, "required": [ "value" ] } } }, "OrderDetails": { "type": "object", "properties": { "customer_currency_code": { "type": "string", "description": "The currency code of the transaction. For API version 2024-09-01: Must be either 'USD' or 'CAD'. For API version 2025-05-12: Supports 32 currencies including USD, CAD, EUR, GBP, AUD, CHF, JPY, and more.", "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. Available with API version 2025-05-12. `auto`: return real rates if client is registered/enabled in that jurisdiction, bypasses threshold checking. `disabled`: always return 0 tax rates regardless of registration status.", "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`. See [this guide](/essentials/integration-guides/products-and-categories) for more.", "items": { "$ref": "#/components/schemas/LineItem" } } }, "required": [ "customer_currency_code", "tax_included_in_amount", "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](/essentials/product-categories). 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": "number", "description": "The price of this line item in the currency's smallest unit. We will calculate tax against this value. (e.g., if USD then 2000 = $20.00, if JPY then 2000 = \u00a52000)", "example": 200 }, "quantity": { "type": "number", "description": "The quantity of this product being sold. Primarily used for record keeping.", "example": 2 } }, "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_123456789" }, "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.", "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" } } }, "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": "number", "description": "Total tax to charge on this `calculation`.", "example": 14 }, "total_amount_excluding_tax": { "type": "number", "description": "Total sale charge, excluding tax.", "example": 200 }, "total_amount_including_tax": { "type": "number", "description": "Total sale charge plus tax. What you should charge your customer.", "example": 214 }, "expires_at": { "type": "number", "description": "Epoch datetime representing the date and time the tax rates are valid until.", "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": { "type": "object", "description": "The actual address used for tax calculation after resolution.", "properties": { "address_line_1": { "type": "string", "example": "4 Privet Drive" }, "address_line_2": { "type": "string", "example": "Unit 2" }, "address_city": { "type": "string", "example": "Little Whinging" }, "address_province": { "type": "string", "example": "CA" }, "address_postal_code": { "type": "string", "example": "90210" }, "address_country": { "type": "string", "example": "US" } }, "required": [ "address_line_1", "address_city", "address_province", "address_postal_code", "address_country" ] }, "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": { "product": { "type": "object", "properties": { "reference_product_name": { "type": "string", "example": "Widget" }, "reference_line_item_id": { "type": "string", "example": "line_987654321" }, "reference_product_id": { "type": "string", "example": "p-1233543" }, "product_tax_code": { "type": "string", "example": "GENERAL_MERCHANDISE" } } }, "tax_jurisdictions": { "type": "array", "items": { "type": "object", "properties": { "tax_rate": { "description": "The tax rate percentage applied to this transaction.", "type": "number", "example": 0.07 }, "tax_due_decimal": { "type": "number", "description": "Tax amount due for this jurisdiction in the currency's smallest unit.", "example": 700 }, "rate_type": { "type": "string", "description": "Descriptive rate classification for this jurisdiction.", "example": "GENERAL STATE SALES TAX" }, "fee_amount": { "description": "The flat fee that is added to this transaction. Like all numeric values, this will be returned in cents and should be added directly to the tax amount independent of other percentages. For example, a $100 transaction taxed at 5% and with a `fee_amount: 50` will lead to `($100 * 5% + 0.50) = $5.50` in tax being charged ", "type": "number", "example": 0 }, "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" } }, "nullable": true } }, "quantity": { "type": "number", "format": "int32", "example": 2 }, "tax_amount": { "type": "number", "format": "int32", "example": 14 }, "amount_excluding_tax": { "type": "number", "format": "int32", "example": 200 }, "amount_including_tax": { "type": "number", "format": "int32", "example": 214 } } }, "RefundTransactionLineItem": { "allOf": [ { "$ref": "#/components/schemas/TransactionLineItem" }, { "type": "object", "properties": { "amount_including_tax": { "type": "number", "format": "int32", "example": -214, "description": "The amount including tax, which should be a negative number for refunds." }, "amount_excluding_tax": { "type": "number", "format": "int32", "example": -200, "description": "The amount excluding tax, which should be a negative number for refunds." }, "tax_amount": { "type": "number", "format": "int32", "example": -14, "description": "The tax amount, which should be a negative number for refunds." }, "quantity": { "type": "number", "format": "int32", "example": 2, "description": "The quantity of this product being refunded." } } } ] }, "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" ] }, "CustomerResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the customer", "example": "cus_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 } } }, "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", "properties": { "error": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" }, "error_meta": { "type": "object", "properties": { "field": { "type": "string" }, "expected": { "type": "string" }, "received": { "type": "string" } } } } }, "request_id": { "type": "string", "description": "The ID of the request", "example": "req_123456789" } }, "example": { "error": { "error_code": "missing_field", "error_message": "Field is required", "error_meta": { "field": "path.to.fieldname", "expected": "string", "received": "undefined" } } } }, "ProductNotFoundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" }, "error_meta": { "type": "object", "properties": { "field": { "type": "string" }, "expected": { "type": "string" }, "received": { "type": "string" } } } } } }, "example": { "error": { "error_code": "error", "error_message": "Unable to create calculation. Unable to find product {reference_product_id} in {environment} environment" } } }, "CalculationNotFoundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" }, "error_meta": { "type": "object", "properties": { "field": { "type": "string" }, "expected": { "type": "string" }, "received": { "type": "string" } } } } } }, "example": { "error": { "error_code": "calculation_not_found", "error_message": "Unable to find calculation {calculation_id}." } } }, "TransactionNotFoundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" }, "error_meta": { "type": "object", "properties": { "field": { "type": "string" }, "expected": { "type": "string" }, "received": { "type": "string" } } } } } }, "example": { "error": { "error_code": "transaction_not_found", "error_message": "Unable to find transaction with ID: {transaction_id}." } } }, "MissingOriginAddressError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" }, "error_meta": { "type": "object", "properties": { "field": { "type": "string" }, "expected": { "type": "string" }, "received": { "type": "string" } } } } } }, "example": { "error": { "error_code": "missing_origin_address", "error_message": "Origin address is required for API version 2025-05-12 but was not provided and no default origin address is configured." } } }, "PingResponse": { "type": "object", "description": "Health check response containing status, environment, timestamp, and API version information", "properties": { "status": { "type": "string", "description": "Always returns 'ok' for successful health checks", "enum": [ "ok" ], "example": "ok" }, "env": { "type": "string", "description": "Environment indicator based on API key type: 'test' for testmode keys, 'prod' for production keys", "enum": [ "test", "prod" ], "example": "test" }, "timestamp": { "type": "string", "format": "date-time", "description": "Current ISO 8601 timestamp when the request was processed", "example": "2025-09-12T17:30:00.000Z" }, "api_version": { "type": "string", "description": "API version from X-API-Version header, or falls back to 2024-09-01", "enum": [ "2024-09-01", "2025-05-12" ], "example": "2025-05-12" } }, "required": [ "status", "env", "timestamp", "api_version" ] }, "AuthError": { "type": "object", "description": "Authentication error response", "properties": { "error": { "type": "string", "description": "Authentication error message", "enum": [ "Invalid API Key format.", "API key not found.", "API key is not active.", "No public API key support currently." ], "example": "API key not found." } }, "required": [ "error" ] }, "RateLimitError": { "type": "object", "description": "Rate limit exceeded error response", "properties": { "error": { "type": "string", "description": "Rate limit error message", "enum": [ "Rate limit exceeded" ], "example": "Rate limit exceeded" } }, "required": [ "error" ] }, "InternalServerError": { "type": "object", "description": "Internal server error response", "properties": { "error_message": { "type": "string", "description": "Human-readable error description", "example": "Internal server error" }, "error_code": { "type": "string", "description": "Machine-readable error code", "example": "ERROR_ERROR" } }, "required": [ "error_message", "error_code" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }