Numeral API supports multiple versions to ensure backward compatibility while introducing new features. This document explains how to specify API versions and the differences between them.
Your account also has a default API version. Requests without the header use the account default; the header overrides it for that request. Without either, requests use 2024-09-01.
Tax jurisdiction notes - Every tax_jurisdictions row has a note saying why it came out the way it did (exempt customer, no registration, reverse charge, and so on)
Effective tax rate - Calculations return effective_tax_rate for the order; platform calculations return one for the order and one for fees
No request, amount or error changes from 2026-03-01.
If you don’t send the header and your account has no default version set, your request will default to the 2024-09-01 version.This is the base API version with core functionality.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Numeral API","colors":{"primary":"#0D9373","light":"#07C983","dark":"#0D9373"},"logo":{"light":"https://mintcdn.com/numeralhq/w35K7dUKWBDiixfd/logo/logo.svg?fit=max\u0026auto=format\u0026n=w35K7dUKWBDiixfd\u0026q=85\u0026s=2330fe2568887c273331c4846f7a4d1e","dark":"https://mintcdn.com/numeralhq/w35K7dUKWBDiixfd/logo/logo-dark.svg?fit=max\u0026auto=format\u0026n=w35K7dUKWBDiixfd\u0026q=85\u0026s=3c46c5bdc314577d1ce3660b957c0ad8"},"favicon":"https://mintcdn.com/numeralhq/NAgHCHKl6ucev5Pu/favicon.ico?fit=max\u0026auto=format\u0026n=NAgHCHKl6ucev5Pu\u0026q=85\u0026s=a6ecac944d1933a8432a8b2234eed9a4","api":{"openapi":["api-reference/v2026-03-01/openapi.json","api-reference/v2026-01-01/openapi.json","api-reference/v2025-05-12/openapi.json","api-reference/v2024-09-01/openapi.json","api-reference/v2026-11-01/openapi.json"]},"navbar":{"links":[{"href":"mailto:hi@mintlify.com","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://dashboard.mintlify.com"}},"interaction":{"drilldown":false},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"numeralhq","hasAudioNarration":false,"actualSubdomain":"numeralhq","customDomains":["docs.numeral.com"],"gitSource":{"type":"github","owner":"numeralhq","repo":"tax-engine-documentation","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae262c0f4c828ffcb3710cb","collectionId":"53ebb60f-72e1-4035-bdd4-3abf4578f87d","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae262c0f4c828ffcb3710cb"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae266bc2d16dd113501a47b","clientVersion":"0.0.4006","searchFilterCounts":[{"language":"default","tag":"API Documentation","count":56},{"language":"default","tag":"Integrations","count":52},{"language":"default","tag":"Platform Integrations","count":47},{"language":"default","tag":"API Reference","count":46},{"language":"default","tag":"Getting Started","count":10},{"language":"default","tag":"Stripe","count":8},{"language":"default","tag":"Numeral for Stripe Checkout","count":6},{"language":"default","tag":"Integration Guides","count":5},{"language":"default","tag":"Shopify","count":5},{"language":"default","tag":"MCP","count":5}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"src/style.css","content":".text-gray-100{color:#c1c2c5}[class*=max-w-8xl]{max-width:112rem!important}#content-container{max-width:none!important}td:first-child code{white-space:nowrap}"},{"filePath":"src/resource-pages.css","content":".sx-section{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:3rem;padding:2.5rem 0;border-top:1px solid rgb(127 127 127/.2)}.sx-section:first-of-type{border-top:none;padding-top:0}.sx-right{position:sticky;top:8rem;align-self:start;max-height:calc(100vh - 9rem);overflow-y:auto}.sx-wide{grid-template-columns:minmax(0,1fr);gap:0}.sx-wide .sx-right{position:static;max-height:none}.sx-wide td code{white-space:nowrap}.sx-left>h2:first-child{margin-top:0}@media (max-width:1024px){.sx-section{grid-template-columns:minmax(0,1fr)}.sx-right{position:static;max-height:none}}.sx-endpoints{border:1px solid rgb(127 127 127/.25);border-radius:.75rem;padding:.75rem 1rem .25rem}.sx-endpoints-title{font-size:.75rem;font-weight:600;text-transform:uppercase;letter-spacing:.05em;opacity:.7;margin-bottom:.5rem}div.sx-endpoints a{display:block;position:relative;font-family:inherit;font-size:inherit;padding:.6rem 1.5rem .6rem 0;border-top:1px solid rgb(127 127 127/.2);border-bottom:none!important;text-decoration:none}.sx-endpoints a::after{content:\"›\";position:absolute;right:.25rem;top:50%;transform:translateY(-50%);font-size:1.25rem;opacity:.5}.sx-endpoints a:hover::after{opacity:1}.sx-ep-name{display:block;font-weight:600;font-size:.9rem}.sx-ep-path{display:block;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.8rem;margin-top:.15rem}.sx-ep-url{opacity:.65}.sx-endpoints .sx-method{display:inline-block;min-width:3.75rem;margin-right:0;font-weight:700}.sx-endpoints .sx-get{color:#3b82f6}.sx-endpoints .sx-post{color:#16a34a}.sx-endpoints .sx-delete{color:#ef4444}.sx-nav-sub{list-style:none;margin:.15rem 0 .5rem;padding:0 0 0 1.75rem}.sx-nav-sub a{display:flex;align-items:baseline;gap:.5rem;padding:.3rem .5rem;border-radius:.5rem;font-size:.8125rem;line-height:1.3;opacity:.7}.sx-nav-sub a.sx-current,.sx-nav-sub a:hover{opacity:1;background:rgb(127 127 127/.1)}.sx-nav-sub a:focus{outline:0}.sx-nav-sub a:focus-visible{outline:2px solid rgb(127 127 127/.5)}.sx-nav-method.sx-nav-spacer{visibility:hidden}.sx-nav-method{flex:none;min-width:2.4rem;padding:.05rem .3rem;border-radius:.3rem;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.625rem;font-weight:700;text-align:center}.sx-nav-method.sx-get{color:#3b82f6;background:rgb(59 130 246/.15)}.sx-nav-method.sx-post{color:#16a34a;background:rgb(22 163 74/.15)}.sx-nav-method.sx-delete{color:#ef4444;background:rgb(239 68 68/.15)}.sx-page-end{height:4rem}.sx-children,.sx-toggle{border:1px solid rgb(127 127 127/.3)}.sx-toggle{margin-top:.75rem;border-radius:9999px;padding:.3rem .9rem;font-size:.85rem;font-weight:500;white-space:pre;cursor:pointer}.sx-toggle.sx-open{border-radius:.75rem .75rem 0 0;border-bottom:none}.sx-children{border-radius:0 .75rem .75rem .75rem;padding:0 1rem .5rem}.sx-children[hidden]{border:0;padding:0}"}],"page":{"pagePath":"api-reference/versioning","slug":"/api-reference/versioning","pageMetadata":{"title":"API Versioning","description":"Understanding and using different versions of the Numeral API","icon":"code-branch","href":"/api-reference/versioning"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Understanding and using different versions of the Numeral API\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`1`,id:`api-versioning`,children:`API Versioning`}),`\n`,_jsx(_components.p,{children:`Numeral API supports multiple versions to ensure backward compatibility while introducing new features. This document explains how to specify API versions and the differences between them.`}),`\n`,_jsx(Heading,{level:`2`,id:`specifying-an-api-version`,children:`Specifying an API Version`}),`\n`,_jsxs(_components.p,{children:[`To specify which API version you want to use, include the `,_jsx(_components.code,{children:`X-API-Version`}),` header in your request:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`6`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --request`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --url`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://api.numeralhq.com/tax/calculations`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --header`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Authorization: Bearer YOUR_API_KEY'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --header`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Content-Type: application/json'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --header`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'X-API-Version: 2026-11-01'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --data`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{ ... }'`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Your account also has a default API version. Requests without the header use the account default; the header overrides it for that request. Without either, requests use `,_jsx(_components.code,{children:`2024-09-01`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`available-versions`,children:`Available Versions`}),`\n`,_jsx(Heading,{level:`3`,id:`2026-11-01-latest`,children:`2026-11-01 (Latest)`}),`\n`,_jsx(_components.p,{children:`Explains every tax result:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`--header`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'X-API-Version: 2026-11-01'`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`New features:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Tax jurisdiction notes`}),` - Every `,_jsx(_components.code,{children:`tax_jurisdictions`}),` row has a `,_jsx(_components.code,{children:`note`}),` saying why it came out the way it did (exempt customer, no registration, reverse charge, and so on)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Effective tax rate`}),` - Calculations return `,_jsx(_components.code,{children:`effective_tax_rate`}),` for the order; platform calculations return one for the order and one for fees`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`No request, amount or error changes from `,_jsx(_components.code,{children:`2026-03-01`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`2026-03-01`,children:`2026-03-01`}),`\n`,_jsx(_components.p,{children:`IP-based tax resolution:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`--header`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'X-API-Version: 2026-03-01'`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`New features:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`IP-Based Tax Resolution`}),` - Calculate taxes using customer IP address instead of full address`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Resolution Modes`}),` - `,_jsx(_components.code,{children:`strict`}),`, `,_jsx(_components.code,{children:`zero`}),`, `,_jsx(_components.code,{children:`approximate`}),`, `,_jsx(_components.code,{children:`best_effort`}),` strategies for handling insufficient IP data`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Enhanced Response`}),` - Includes `,_jsx(_components.code,{children:`location_source`}),`, `,_jsx(_components.code,{children:`resolution_precision`}),`, `,_jsx(_components.code,{children:`address_used`}),` fields`]}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`2026-01-01`,children:`2026-01-01`}),`\n`,_jsx(_components.p,{children:`Marketplace and platform support:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`--header`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'X-API-Version: 2026-01-01'`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`New features:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Merchant Management`}),` - Full CRUD for marketplace sellers`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Platform Calculations`}),` - Tax calculations for marketplace/platform transactions`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Per-Unit Pricing`}),` - In platform calculations, `,_jsx(_components.code,{children:`amount`}),` is per-unit (total = amount × quantity)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Platform Roles`}),` - Specify your role (marketplace_provider, payment_processor, merchant_of_record)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Fee Calculations`}),` - Separate tax calculation for platform fees`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Enhanced Response`}),` - Includes tax_authority_name, tax_authority_type, tax_type`]}),`\n`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Important:`}),` In `,_jsx(_components.code,{children:`/platform/calculations`}),`, the `,_jsx(_components.code,{children:`amount`}),` field is `,_jsx(_components.strong,{children:`per-unit`}),`, not total.\nThe taxable base = `,_jsx(_components.code,{children:`amount × quantity`}),`.`]})}),`\n`,_jsx(Heading,{level:`3`,id:`2025-05-12`,children:`2025-05-12`}),`\n`,_jsx(_components.p,{children:`Enhanced version with B2B support:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`--header`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'X-API-Version: 2025-05-12'`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`This version includes:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Customer Types`}),` - Support for business-to-business (B2B) and consumer transactions`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Tax IDs`}),` - VAT and GST identification support`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Automatic Tax Settings`}),` - Control over tax collection and registration (field is `,_jsx(_components.strong,{children:`required`}),`)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Expanded Currency Support`}),` - 32 currencies supported`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Required Fields`}),` - `,_jsx(_components.code,{children:`origin_address`}),` and `,_jsx(_components.code,{children:`automatic_tax`}),` are now required fields`]}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`2024-09-01-default`,children:`2024-09-01 (Default)`}),`\n`,_jsxs(_components.p,{children:[`If you don’t send the header and your account has no default version set, your request will default to the `,_jsx(_components.code,{children:`2024-09-01`}),` version.`]}),`\n`,_jsx(_components.p,{children:`This is the base API version with core functionality.`}),`\n`,_jsx(Heading,{level:`2`,id:`version-differences`,children:`Version Differences`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Feature`}),_jsx(_components.th,{children:`2024-09-01`}),_jsx(_components.th,{children:`2025-05-12`}),_jsx(_components.th,{children:`2026-01-01`}),_jsx(_components.th,{children:`2026-03-01`}),_jsx(_components.th,{children:`2026-11-01`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Customer Types`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`BUSINESS/CONSUMER`}),_jsx(_components.td,{children:`BUSINESS/CONSUMER`}),_jsx(_components.td,{children:`BUSINESS/CONSUMER`}),_jsx(_components.td,{children:`BUSINESS/CONSUMER`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Tax IDs`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`VAT, GST, EIN`}),_jsx(_components.td,{children:`VAT, GST, EIN`}),_jsx(_components.td,{children:`VAT, GST, EIN`}),_jsx(_components.td,{children:`VAT, GST, EIN`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Automatic Tax`}),_jsx(_components.td,{children:`Not configurable`}),_jsx(_components.td,{children:`auto/disabled (required)`}),_jsx(_components.td,{children:`auto/disabled (required)`}),_jsx(_components.td,{children:`auto/disabled (required)`}),_jsx(_components.td,{children:`auto/disabled (required)`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Origin Address`}),_jsx(_components.td,{children:`Optional`}),_jsx(_components.td,{children:`Required`}),_jsx(_components.td,{children:`Required`}),_jsx(_components.td,{children:`Required`}),_jsx(_components.td,{children:`Required`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Supported Currencies`}),_jsx(_components.td,{\"data-numeric\":`true`,children:`10`}),_jsx(_components.td,{\"data-numeric\":`true`,children:`32`}),_jsx(_components.td,{\"data-numeric\":`true`,children:`32`}),_jsx(_components.td,{\"data-numeric\":`true`,children:`32`}),_jsx(_components.td,{\"data-numeric\":`true`,children:`32`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Merchants`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Full CRUD`}),_jsx(_components.td,{children:`Full CRUD`}),_jsx(_components.td,{children:`Full CRUD`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Platform Calculations`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Supported`}),_jsx(_components.td,{children:`Supported`}),_jsx(_components.td,{children:`Supported`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Per-Unit Pricing`}),_jsx(_components.td,{children:`N/A`}),_jsx(_components.td,{children:`N/A`}),_jsx(_components.td,{children:`In platform calcs`}),_jsx(_components.td,{children:`In platform calcs`}),_jsx(_components.td,{children:`In platform calcs`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Fee Calculations`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Supported`}),_jsx(_components.td,{children:`Supported`}),_jsx(_components.td,{children:`Supported`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`IP-Based Tax Resolution`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Not supported`}),_jsx(_components.td,{children:`Supported`}),_jsx(_components.td,{children:`Supported`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Resolution Modes`}),_jsx(_components.td,{children:`N/A`}),_jsx(_components.td,{children:`N/A`}),_jsx(_components.td,{children:`N/A`}),_jsx(_components.td,{children:`strict, zero, approximate, best_effort`}),_jsx(_components.td,{children:`strict, zero, approximate, best_effort`})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`Tax jurisdiction `,_jsx(_components.code,{children:`note`})]}),_jsx(_components.td,{children:`Internal method values`}),_jsx(_components.td,{children:`Internal method values`}),_jsx(_components.td,{children:`Not returned`}),_jsx(_components.td,{children:`Not returned`}),_jsx(_components.td,{children:`Reason codes`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`effective_tax_rate`})}),_jsx(_components.td,{children:`Not returned`}),_jsx(_components.td,{children:`Not returned`}),_jsx(_components.td,{children:`Not returned`}),_jsx(_components.td,{children:`Not returned`}),_jsx(_components.td,{children:`Calculations and platform totals`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`new-in-2026-11-01`,children:`New in 2026-11-01`}),`\n`,_jsx(Heading,{level:`3`,id:`tax-jurisdiction-notes-and-effective-tax-rate`,children:`Tax jurisdiction notes and effective tax rate`}),`\n`,_jsxs(_components.p,{children:[`Every `,_jsx(_components.code,{children:`tax_jurisdictions`}),` row has a `,_jsx(_components.code,{children:`note`}),`, and calculations return `,_jsx(_components.code,{children:`effective_tax_rate`}),`:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`17`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`17`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"line_items\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"tax_jurisdictions\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"tax_rate\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"rate_type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"VAT\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"tax_authority_name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"FR\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"tax_type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"VAT\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"note\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"b2b_reverse_charge\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ],`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"total_tax_amount\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"effective_tax_rate\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`See `,_jsx(_components.a,{href:`/v2026-11-01/objects/calculations#notes`,children:`Calculations`}),` for every `,_jsx(_components.code,{children:`note`}),` value.`]}),`\n`,_jsx(Heading,{level:`2`,id:`new-in-2026-03-01`,children:`New in 2026-03-01`}),`\n`,_jsx(Heading,{level:`3`,id:`ip-based-tax-resolution`,children:`IP-Based Tax Resolution`}),`\n`,_jsx(_components.p,{children:`Pass a customer IP address instead of a full address for tax calculations:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"customer\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"ip\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"value\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"217.217.113.167\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"resolution\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"strict\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Works with both `,_jsx(_components.code,{children:`/tax/calculations`}),` and `,_jsx(_components.code,{children:`/tax/platform/calculations`}),`. Supports IPv4 and IPv6 addresses.`]}),`\n`,_jsx(Heading,{level:`2`,id:`new-in-2026-01-01`,children:`New in 2026-01-01`}),`\n`,_jsx(Heading,{level:`3`,id:`merchant-endpoints`,children:`Merchant Endpoints`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Endpoint`}),_jsx(_components.th,{children:`Method`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`/tax/merchants`})}),_jsx(_components.td,{children:`POST`}),_jsx(_components.td,{children:`Create a merchant`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`/tax/merchants`})}),_jsx(_components.td,{children:`GET`}),_jsx(_components.td,{children:`List merchants`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`/tax/merchants/:id`})}),_jsx(_components.td,{children:`GET`}),_jsx(_components.td,{children:`Get a merchant`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`/tax/merchants/:id`})}),_jsx(_components.td,{children:`POST`}),_jsx(_components.td,{children:`Update a merchant`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`/tax/merchants/:id`})}),_jsx(_components.td,{children:`DELETE`}),_jsx(_components.td,{children:`Delete a merchant`})]})]})]}),`\n`,_jsx(Heading,{level:`3`,id:`platform-calculations`,children:`Platform Calculations`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Endpoint`}),_jsx(_components.th,{children:`Method`}),_jsx(_components.th,{children:`Description`})]})}),_jsx(_components.tbody,{children:_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`/tax/platform/calculations`})}),_jsx(_components.td,{children:`POST`}),_jsx(_components.td,{children:`Calculate taxes for platform transactions`})]})})]}),`\n`,_jsx(Heading,{level:`2`,id:`version-migration`,children:`Version Migration`}),`\n`,_jsx(_components.p,{children:`All API versions will be maintained in parallel. We recommend:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`New integrations`}),`: Use `,_jsx(_components.code,{children:`2026-11-01`}),` for access to all features, including tax jurisdiction notes and the effective tax rate`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Marketplace/platforms`}),`: Use `,_jsx(_components.code,{children:`2026-11-01`}),` for merchant, platform calculation, IP resolution, and per-bucket effective rate support`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Existing integrations`}),`: Can continue using current version; upgrade when needed`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`For detailed changelog, see the `,_jsx(_components.a,{href:`/api-reference/v2026-11-01/changelog`,children:`Changelog`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"API Versioning","description":"Understanding and using different versions of the Numeral API","icon":"code-branch","href":"/api-reference/versioning"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"API Versioning","slug":"api-versioning","depth":1,"children":[]},{"title":"Specifying an API Version","slug":"specifying-an-api-version","depth":2,"children":[]},{"title":"Available Versions","slug":"available-versions","depth":2,"children":[{"title":"2026-11-01 (Latest)","slug":"2026-11-01-latest","depth":3,"children":[]},{"title":"2026-03-01","slug":"2026-03-01","depth":3,"children":[]},{"title":"2026-01-01","slug":"2026-01-01","depth":3,"children":[]},{"title":"2025-05-12","slug":"2025-05-12","depth":3,"children":[]},{"title":"2024-09-01 (Default)","slug":"2024-09-01-default","depth":3,"children":[]}]},{"title":"Version Differences","slug":"version-differences","depth":2,"children":[]},{"title":"New in 2026-11-01","slug":"new-in-2026-11-01","depth":2,"children":[{"title":"Tax jurisdiction notes and effective tax rate","slug":"tax-jurisdiction-notes-and-effective-tax-rate","depth":3,"children":[]}]},{"title":"New in 2026-03-01","slug":"new-in-2026-03-01","depth":2,"children":[{"title":"IP-Based Tax Resolution","slug":"ip-based-tax-resolution","depth":3,"children":[]}]},{"title":"New in 2026-01-01","slug":"new-in-2026-01-01","depth":2,"children":[{"title":"Merchant Endpoints","slug":"merchant-endpoints","depth":3,"children":[]},{"title":"Platform Calculations","slug":"platform-calculations","depth":3,"children":[]}]},{"title":"Version Migration","slug":"version-migration","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/numeralhq/f4a41b99b7afe396/src/version-refresh.js","/_mintlify/custom/numeralhq/4721c15820461e09/src/resource-pages.js"],"subdomain":"numeralhq","siteName":"Numeral API","title":"API Versioning - Numeral API","navMaps":{"firstHrefInVersion":{"2026-11-01":{"href":"/api-reference/versioning","matchLevel":0},"2026-03-01":{"href":"/api-reference/versioning","matchLevel":0},"2026-01-01":{"href":"/api-reference/versioning","matchLevel":0},"2025-05-12":{"href":"/api-reference/versioning","matchLevel":0},"2024-09-01":{"href":"/api-reference/versioning","matchLevel":0}},"firstHrefInLanguage":{}},"lastModified":"2026-10-28T21:02:43.098Z","originalFileLocation":"api-reference/versioning.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Understanding and using different versions of the Numeral API\">\u003cmeta data-mint-head name=\"application-name\" content=\"Numeral API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"API Versioning - Numeral API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Understanding and using different versions of the Numeral API\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Numeral API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.numeral.com/api-reference/versioning\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://numeralhq.mintlify.app/_mintlify/api/og/v2?division=Getting+Started\u0026amp;title=API+Versioning\u0026amp;description=Understanding+and+using+different+versions+of+the+Numeral+API\u0026amp;theme=db0aa42568482bdcbfb10a73\u0026amp;signature=d12482e35b5e1109e32f7f127412361af0befe55964d3cb30d61d59057577022\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"API Versioning - Numeral API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Understanding and using different versions of the Numeral API\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://numeralhq.mintlify.app/_mintlify/api/og/v2?division=Getting+Started\u0026amp;title=API+Versioning\u0026amp;description=Understanding+and+using+different+versions+of+the+Numeral+API\u0026amp;theme=db0aa42568482bdcbfb10a73\u0026amp;signature=d12482e35b5e1109e32f7f127412361af0befe55964d3cb30d61d59057577022\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/numeralhq/T60dQ7B6WxiReCVN/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Numeral API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0D9373\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.numeral.com/api-reference/versioning\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/versioning.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.numeral.com/#organization\",\"name\":\"Numeral API\",\"url\":\"https://docs.numeral.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/numeralhq/w35K7dUKWBDiixfd/logo/logo.svg?fit=max\u0026auto=format\u0026n=w35K7dUKWBDiixfd\u0026q=85\u0026s=2330fe2568887c273331c4846f7a4d1e\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.numeral.com#website\",\"name\":\"Numeral API\",\"url\":\"https://docs.numeral.com\",\"publisher\":{\"@id\":\"https://docs.numeral.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.numeral.com/api-reference/versioning#webpage\",\"url\":\"https://docs.numeral.com/api-reference/versioning\",\"name\":\"API Versioning\",\"description\":\"Understanding and using different versions of the Numeral API\",\"dateModified\":\"2026-10-28T21:02:43.098Z\",\"isPartOf\":{\"@id\":\"https://docs.numeral.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.numeral.com/api-reference/versioning#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.numeral.com/api-reference/versioning#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Getting Started\",\"item\":\"https://docs.numeral.com/introduction\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"API Versioning\",\"item\":\"https://docs.numeral.com/api-reference/versioning\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.numeral.com/api-reference/versioning#article\",\"headline\":\"API Versioning\",\"name\":\"API Versioning\",\"description\":\"Understanding and using different versions of the Numeral API\",\"url\":\"https://docs.numeral.com/api-reference/versioning\",\"mainEntityOfPage\":{\"@id\":\"https://docs.numeral.com/api-reference/versioning#webpage\"},\"dateModified\":\"2026-10-28T21:02:43.098Z\",\"publisher\":{\"@id\":\"https://docs.numeral.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.numeral.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Numeral API\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Numeral API","nav":{"global":null,"versions":[{"version":"2026-11-01","tabs":[{"tab":"API Documentation","groups":[{"group":"Getting Started","pages":[{"title":"Introduction","icon":"hand-wave","href":"/introduction"},{"title":"Quickstart","icon":"rabbit","href":"/essentials/quickstart/quickstart"},{"title":"Changelog","icon":"wind","href":"/api-reference/v2026-11-01/changelog"},{"title":"API Keys","icon":"key","description":null,"href":"/essentials/api-keys"},{"title":"API Versioning","icon":"code-branch","href":"/api-reference/versioning"},{"title":"Currencies","icon":"money-bill","description":null,"href":"/essentials/currencies"},{"title":"Product Categories","icon":"tag","href":"/essentials/product-categories"},{"title":"Tax IDs","icon":"id-card","href":"/essentials/tax-ids"},{"title":"FAQs","icon":"question","href":"/essentials/faqs"},{"title":"AI help","icon":"robot","href":"/ai-help/overview"}]},{"group":"API Reference","pages":[{"title":"Introduction v2026-11-01","href":"/api-reference/v2026-11-01/introduction"},{"title":"Error Codes","icon":"triangle-exclamation","href":"/api-reference/v2026-11-01/error-codes"},{"title":"Calculations","icon":"calculator","mode":"wide","href":"/v2026-11-01/objects/calculations"},{"title":"Transactions","icon":"cash-register","mode":"wide","href":"/v2026-11-01/objects/transactions"},{"title":"Platform","icon":"store","mode":"wide","href":"/v2026-11-01/objects/platform"},{"title":"Merchants","icon":"store","mode":"wide","href":"/v2026-11-01/objects/merchants"},{"title":"Products","icon":"boxes-stacked","mode":"wide","href":"/v2026-11-01/objects/products"},{"title":"Customers","icon":"person","mode":"wide","href":"/v2026-11-01/objects/customers"},{"title":"Exemption (Resale) Certificates","icon":"file-certificate","mode":"wide","href":"/v2026-11-01/objects/exemption-certificates"},{"title":"Exchange Rates","icon":"money-bill-transfer","mode":"wide","href":"/v2026-11-01/objects/exchange-rates"},{"title":"Health Check","openapi":"api-reference/v2026-11-01/openapi.json GET /tax/ping","href":"/api-reference/v2026-11-01/endpoint/ping"}]}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/essentials/integration-guides/reference-objects-faq"}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/mcp/overview"}]}]},{"version":"2026-03-01","tabs":[{"tab":"API Documentation","groups":[{"group":"Getting Started","pages":[{"title":"Introduction","icon":"hand-wave","href":"/introduction"},{"title":"Quickstart","icon":"rabbit","href":"/essentials/quickstart/quickstart"},{"title":"Changelog","icon":"wind","href":"/api-reference/v2026-11-01/changelog"},{"title":"API Keys","icon":"key","description":null,"href":"/essentials/api-keys"},{"title":"API Versioning","icon":"code-branch","href":"/api-reference/versioning"},{"title":"Currencies","icon":"money-bill","description":null,"href":"/essentials/currencies"},{"title":"Product Categories","icon":"tag","href":"/essentials/product-categories"},{"title":"Tax IDs","icon":"id-card","href":"/essentials/tax-ids"},{"title":"FAQs","icon":"question","href":"/essentials/faqs"},{"title":"AI help","icon":"robot","href":"/ai-help/overview"}]},{"group":"API Reference","pages":[{"title":"Introduction v2026-03-01","href":"/api-reference/v2026-03-01/introduction"},{"title":"Error Codes","icon":"triangle-exclamation","href":"/api-reference/v2026-03-01/error-codes"},{"title":"Calculations","icon":"calculator","mode":"wide","href":"/v2026-03-01/objects/calculations"},{"title":"Transactions","icon":"cash-register","mode":"wide","href":"/v2026-03-01/objects/transactions"},{"title":"Platform","icon":"store","mode":"wide","href":"/v2026-03-01/objects/platform"},{"title":"Merchants","icon":"store","mode":"wide","href":"/v2026-03-01/objects/merchants"},{"title":"Products","icon":"boxes-stacked","mode":"wide","href":"/v2026-03-01/objects/products"},{"title":"Customers","icon":"person","mode":"wide","href":"/v2026-03-01/objects/customers"},{"title":"Exemption (Resale) Certificates","icon":"file-certificate","mode":"wide","href":"/v2026-03-01/objects/exemption-certificates"},{"title":"Exchange Rates","icon":"money-bill-transfer","mode":"wide","href":"/v2026-03-01/objects/exchange-rates"},{"title":"Health Check","openapi":"GET /tax/ping","href":"/api-reference/v2026-03-01/endpoint/ping"}]}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/essentials/integration-guides/reference-objects-faq"}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/mcp/overview"}]}]},{"version":"2026-01-01","tabs":[{"tab":"API Documentation","groups":[{"group":"Getting Started","pages":[{"title":"Introduction","icon":"hand-wave","href":"/introduction"},{"title":"Quickstart","icon":"rabbit","href":"/essentials/quickstart/quickstart"},{"title":"Changelog","icon":"wind","href":"/api-reference/v2026-11-01/changelog"},{"title":"API Keys","icon":"key","description":null,"href":"/essentials/api-keys"},{"title":"API Versioning","icon":"code-branch","href":"/api-reference/versioning"},{"title":"Currencies","icon":"money-bill","description":null,"href":"/essentials/currencies"},{"title":"Product Categories","icon":"tag","href":"/essentials/product-categories"},{"title":"Tax IDs","icon":"id-card","href":"/essentials/tax-ids"},{"title":"FAQs","icon":"question","href":"/essentials/faqs"},{"title":"AI help","icon":"robot","href":"/ai-help/overview"}]},{"group":"API Reference","pages":[{"title":"Introduction v2026-01-01","href":"/api-reference/v2026-01-01/introduction"},{"title":"Error Codes","icon":"triangle-exclamation","href":"/api-reference/v2026-01-01/error-codes"},{"title":"Calculations","icon":"calculator","mode":"wide","href":"/v2026-01-01/objects/calculations"},{"title":"Transactions","icon":"cash-register","mode":"wide","href":"/v2026-01-01/objects/transactions"},{"title":"Platform","icon":"store","mode":"wide","href":"/v2026-01-01/objects/platform"},{"title":"Merchants","icon":"store","mode":"wide","href":"/v2026-01-01/objects/merchants"},{"title":"Products","icon":"boxes-stacked","mode":"wide","href":"/v2026-01-01/objects/products"},{"title":"Customers","icon":"person","mode":"wide","href":"/v2026-01-01/objects/customers"},{"title":"Exchange Rates","icon":"money-bill-transfer","mode":"wide","href":"/v2026-01-01/objects/exchange-rates"},{"title":"Health Check","openapi":"GET /tax/ping","href":"/api-reference/v2026-01-01/endpoint/ping"}]}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/essentials/integration-guides/reference-objects-faq"}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/mcp/overview"}]}]},{"version":"2025-05-12","tabs":[{"tab":"API Documentation","groups":[{"group":"Getting Started","pages":[{"title":"Introduction","icon":"hand-wave","href":"/introduction"},{"title":"Quickstart","icon":"rabbit","href":"/essentials/quickstart/quickstart"},{"title":"Changelog","icon":"wind","href":"/api-reference/v2026-11-01/changelog"},{"title":"API Keys","icon":"key","description":null,"href":"/essentials/api-keys"},{"title":"API Versioning","icon":"code-branch","href":"/api-reference/versioning"},{"title":"Currencies","icon":"money-bill","description":null,"href":"/essentials/currencies"},{"title":"Product Categories","icon":"tag","href":"/essentials/product-categories"},{"title":"Tax IDs","icon":"id-card","href":"/essentials/tax-ids"},{"title":"FAQs","icon":"question","href":"/essentials/faqs"},{"title":"AI help","icon":"robot","href":"/ai-help/overview"}]},{"group":"API Reference","pages":[{"title":"Introduction v2025-05-12","href":"/api-reference/v2025-05-12/introduction"},{"title":"Calculations","icon":"calculator","mode":"wide","href":"/v2025-05-12/objects/calculations"},{"title":"Transactions","icon":"cash-register","mode":"wide","href":"/v2025-05-12/objects/transactions"},{"title":"Products","icon":"boxes-stacked","mode":"wide","href":"/v2025-05-12/objects/products"},{"title":"Customers","icon":"person","mode":"wide","href":"/v2025-05-12/objects/customers"},{"title":"Exchange Rates","icon":"money-bill-transfer","mode":"wide","href":"/v2025-05-12/objects/exchange-rates"},{"title":"Health Check Ping","openapi":"GET /tax/ping","href":"/api-reference/v2025-05-12/endpoint/ping"}]}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/essentials/integration-guides/reference-objects-faq"}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/mcp/overview"}]}]},{"version":"2024-09-01","tabs":[{"tab":"API Documentation","groups":[{"group":"Getting Started","pages":[{"title":"Introduction","icon":"hand-wave","href":"/introduction"},{"title":"Quickstart","icon":"rabbit","href":"/essentials/quickstart/quickstart"},{"title":"Changelog","icon":"wind","href":"/api-reference/v2026-11-01/changelog"},{"title":"API Keys","icon":"key","description":null,"href":"/essentials/api-keys"},{"title":"API Versioning","icon":"code-branch","href":"/api-reference/versioning"},{"title":"Currencies","icon":"money-bill","description":null,"href":"/essentials/currencies"},{"title":"Product Categories","icon":"tag","href":"/essentials/product-categories"},{"title":"Tax IDs","icon":"id-card","href":"/essentials/tax-ids"},{"title":"FAQs","icon":"question","href":"/essentials/faqs"},{"title":"AI help","icon":"robot","href":"/ai-help/overview"}]},{"group":"API Reference","pages":[{"title":"Introduction v2024-09-01","href":"/api-reference/v2024-09-01/introduction"},{"title":"Calculations","icon":"calculator","mode":"wide","href":"/objects/calculations"},{"title":"Transactions","icon":"cash-register","mode":"wide","href":"/objects/transactions"},{"title":"Products","icon":"boxes-stacked","mode":"wide","href":"/objects/products"},{"title":"Customers","icon":"person","mode":"wide","href":"/objects/customers"},{"title":"Exchange Rates","icon":"money-bill-transfer","mode":"wide","href":"/objects/exchange-rates"},{"title":"Health Check Ping","openapi":"GET /tax/ping","href":"/api-reference/v2024-09-01/endpoint/ping"}]}]},{"tab":"Integrations","pages":[{"title":"Integrations","href":"/essentials/integration-guides/reference-objects-faq"}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/mcp/overview"}]}]}]},"title":"API Versioning - Numeral API","buildId":"dpl_2xiSHD9XEvLsPGPcfoMtkLTB3dy9","deploymentId":"dpl_2xiSHD9XEvLsPGPcfoMtkLTB3dy9","dynamics":[],"chunks":[]}
