> ## Documentation Index > Fetch the complete documentation index at: https://docs.nocotax.app/llms.txt > Use this file to discover all available pages before exploring further. # Create a Tax Calculation > Creates a Tax Calculation. This endpoint calculates the applicable taxes for a given transaction. It is designed to support both B2B and B2C scenarios, including guest checkouts, self-owned organizations, and third-party transactions. **Use Cases:** - Calculate taxes for a guest user (no customer/supplier organization). - Calculate taxes for a registered organization (customer or supplier). - Calculate taxes for digital or physical goods. - Calculate taxes for cross-border transactions (e.g., EU OSS, IOSS, or standard VAT). **Edge Cases:** - If both `customer_id` and `customer_details` are provided, the API will return an error. - If both `supplier_id` and `supplier_details` are provided, the API will return an error. - If neither `customer_id` nor `customer_details` is provided, the API will assume the self-owned organization is the customer. - If neither `supplier_id` nor `supplier_details` is provided, the API will assume the self-owned organization is the supplier. - The `country` field in `address` is mandatory for both customer and supplier. - The `items` array must contain at least one item. - If `tax_code` is not provided for an item, the default tax code `D10000000` (digital goods) will be used. ## OpenAPI ````yaml /api-reference/openapi.yaml post /tax_calculations openapi: 3.0.1 info: title: Nocotax API version: v1 servers: - url: https://api.nocotax.app/ variables: protocol: default: https defaultHost: default: api.nocotax.app/ security: - basic_auth: [] tags: - name: Introduction x-traitTag: true description: > The Nocotax API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors. To make the Nocotax API as secure as possible. Authentication is performed through HTTP Basic Auth. Credentials can be found on your Nocotax developers menu, in the "API Keys" section. - name: Authentication x-traitTag: true description: > Authentication to the API occurs via HTTP Basic Auth. Provide your Account ID as the basic auth username, and the API secret key as the password. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests. You can manage your API keys from your account. Your API keys carry many privileges, so be sure to keep them secret! - name: Errors x-traitTag: true description: > Nocotax uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with our servers. ``` HTTP status codes summary 200 OK - Everything worked as expected. 201 Created - Resource has been successfully created 202 Accepted - Request has been accepted, but requires asynchronous work to be fully performed 400 Bad Request - Request failed due to a combination of errors 401 Unauthorized - No valid API credentials provided. 402 Payment Required - Your request was in livemode while your account is not activated for live requests yet. 403 Forbidden - You are not authorized to access the requested item. 404 Not Found - The requested item doesn't exist. 406 Unacceptable - Your request format was not supported. Use JSON. 409 Conflict - The data you submitted is in conflict with existing data. 422 Unprocessable Entity - Often missing a required parameter. 429 Too Many Requests - You sent us too many API requests in a row. Please retry later. 500, 502, 503, 504 Server errors - something went wrong on our end. ``` - name: Pagination x-traitTag: true description: > All top-level API resources have support for bulk fetches “list” API methods. For instance, you can list organization, list invoices. We use cursor-based pagination using the parameter `after`. Pass `after` parameter at the previous page last object id value to determine where to start in the list. Reverse pagination is possible as well thanks to the `before` parameter. ## Attributes
AttributeType
limitinteger, optional A limit on the number of objects to be returned. Must be included between 1 and 100
afterstring, optional A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `after=obj_foo` in order to fetch the next page of the list.
beforestring, optional A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `before=obj_bar` in order to fetch the previous page of the list.
### List Response format
AttributeType
objectstring, value is `list`
dataarray, An array containing the actual response elements, paginated by any request parameters.
has_beforeboolean, Whether or not there are more elements available before this page. If `false`, this page is the beginning of the list.
has_moreboolean, Whether or not there are more elements available after this page. If `false`, this page is the end of the list
paths: /tax_calculations: post: tags: - Tax Calculations summary: Create a Tax Calculation description: |2- Creates a Tax Calculation. This endpoint calculates the applicable taxes for a given transaction. It is designed to support both B2B and B2C scenarios, including guest checkouts, self-owned organizations, and third-party transactions. **Use Cases:** - Calculate taxes for a guest user (no customer/supplier organization). - Calculate taxes for a registered organization (customer or supplier). - Calculate taxes for digital or physical goods. - Calculate taxes for cross-border transactions (e.g., EU OSS, IOSS, or standard VAT). **Edge Cases:** - If both `customer_id` and `customer_details` are provided, the API will return an error. - If both `supplier_id` and `supplier_details` are provided, the API will return an error. - If neither `customer_id` nor `customer_details` is provided, the API will assume the self-owned organization is the customer. - If neither `supplier_id` nor `supplier_details` is provided, the API will assume the self-owned organization is the supplier. - The `country` field in `address` is mandatory for both customer and supplier. - The `items` array must contain at least one item. - If `tax_code` is not provided for an item, the default tax code `D10000000` (digital goods) will be used. operationId: TaxCalculationsCreate parameters: [] requestBody: content: application/json: schema: type: object properties: customer_details: type: object description: >- The tax calculation customer's details, if no organization is created. Useful when you need to display tax rates for a guest or to init a shipping cart. Cannot be used along with `customer_id`. Leave blank if your account's self-owned organization is the customer of the transaction properties: address: type: object description: >- The customer’s physical address (billing or shipping). Required if `customer_details` is provided. properties: line1: type: string nullable: true description: Address line 1 (e.g., street name and number). line2: type: string nullable: true description: >- Address line 2 (e.g., apartment, suite, unit, or building). city: type: string nullable: true description: City name. postal_code: type: string nullable: true description: Postal or ZIP code. state: type: string nullable: true description: State, province, or region. country: type: string description: >- Country ISO alpha-2 code (e.g., "FR", "US"). **Required.** required: - country tax_registrations: type: array description: >- The customer's tax registration data. They represent where the organization is registered for tax. items: type: object properties: country: type: string description: >- Country ISO alpha-2 code for this tax registration (e.g., "FR", "DE"). number: type: string description: Tax registration number (e.g., VAT number). tax_registration_type: type: string description: >- Type of tax registration. Valid values depends on the country of the tax registration. enum: - standard - oss_eu - oss_out - ioss nullable: true required: - country - number required: - address nullable: true customer_id: type: string description: >- The ID of the organization this tax calculation refers as a customer. Cannot be used along with `customer_details`. Leave blank if your account's self-owned organization is the customer of the transaction. nullable: true items: type: array description: >- A list of items the customer is buying or willing to buy. **At least one item is required.** Each item must have a unique `reference` within the calculation object. items: type: object properties: reference: type: string description: >- A unique reference to identify the item amongst others within the calculation object (e.g., SKU or product ID). tax_code: type: string description: >- A `tax_code` to use for this item. If not provided, we will use the default tax code `D10000000` corresponding to digital goods. supplier_details: type: object description: >- The tax calculation supplier's details, if no organization is created. Useful when you need to display tax rates for a guest or to init a shipping cart. Cannot be used along with `supplier_id`. Leave blank if your account's self-owned organization is the supplier of the transaction properties: address: type: object properties: line1: type: string nullable: true description: Address line 1 (e.g., street name and number). line2: type: string nullable: true description: >- Address line 2 (e.g., apartment, suite, unit, or building). city: type: string nullable: true description: City name. postal_code: type: string nullable: true description: Postal or ZIP code. state: type: string nullable: true description: State, province, or region. country: type: string description: >- Country ISO alpha-2 code (e.g., "FR", "US"). **Required.** required: - country tax_registrations: type: array description: >- The supplier's tax registration data. They represent where the organization is registered for tax. items: type: object properties: country: type: string description: >- The country ISO alpha2 code for this tax registration number: type: string description: The tax number for this registration tax_registration_type: type: string description: >- Type of the tax registration. Valid values depends on the country of the tax registration. enum: - standard - oss_eu - oss_out - ioss nullable: true required: - country - number required: - address nullable: true supplier_id: type: string description: >- The ID of the organization this tax calculation refers as a merchant/supplier. Cannot be used along with `supplier_details`. Leave blank if your account's self-owned organization is the supplier/merchant of the transaction. nullable: true responses: '201': description: successful content: application/json: example: id: tax_cc_17920607808btjf8f02947 livemode: false object: tax_calculation customer_details: address: city: West Johnnieport line1: 68481 Schoen Hill line2: Apt. 914 country: SN postal_code: '86577' tax_registrations: [] items: - id: tax_cci_17920607808jvv9d0a3372 livemode: false reference: ref-0000-0000-001-A tax_code: D10000000 tax_class: DIGITAL_GOODS tax_summary: tax_collectible: false taxes: - tax_id: fallback-tax jurisdiction: SN percentage: '0.0' tax_exemption: type: NOT_REGISTERED legal_notice: null - id: tax_cci_17920607808pr0715bd253 livemode: false reference: ref-0000-0000-002-A tax_code: P10000000 tax_class: PHYSICAL_GOODS tax_summary: tax_collectible: false taxes: - tax_id: fallback-tax jurisdiction: SN percentage: '0.0' tax_exemption: type: NOT_REGISTERED legal_notice: null supplier_details: address: city: West Carlenabury line1: 80664 Lang Knolls line2: Suite 331 country: SI postal_code: 20440-4930 tax_registrations: [] created_at: '2026-10-15T10:39:40.410Z' updated_at: '2026-10-15T10:39:40.410Z' schema: $ref: '#/components/schemas/taxCalculation' default: description: Error Response content: application/json: schema: $ref: '#/components/schemas/errorResponse' components: schemas: taxCalculation: type: object properties: id: type: string livemode: type: boolean object: type: string enum: - tax_calculation customer_details: type: object description: The tax calculation customer's details properties: address: type: object properties: line1: type: string nullable: true description: Address line 1 (e.g., street name and number). line2: type: string nullable: true description: Address line 2 (e.g., apartment, suite, unit, or building). city: type: string nullable: true description: City name. postal_code: type: string nullable: true description: Postal or ZIP code. state: type: string nullable: true description: State, province, or region. country: type: string description: Country ISO alpha-2 code (e.g., "FR", "US"). **Required.** tax_registrations: type: array description: >- The customer's tax registration data. They represent where the organization is registered for tax. items: type: object properties: country: type: string description: The country ISO alpha2 code for this tax registration number: type: string description: The tax number for this registration tax_registration_type: type: string description: Type of the tax registration nullable: true nullable: true items: type: array description: >- The list of items the customer is buying or willing to buy, for which tax has been calculated items: type: object properties: id: type: string livemode: type: boolean reference: type: string description: >- A unique reference to identify the item amongst others within the calculation object (e.g., SKU or product ID). tax_code: type: string description: A `tax_code` to use for this item tax_class: type: string description: The tax class for this item, defining tax rules enum: - DIGITAL_GOODS - PHYSICAL_GOODS - SERVICES - LOCALIZABLE_SERVICES tax_summary: type: object description: Core details about tax calculation for this item properties: tax_collectible: type: boolean description: Whether tax shall be collected or not for this item taxes: type: array description: A list of taxes that apply for this item properties: jurisdiction: type: string description: The jurisdiction this tax data refers to percentage: type: string format: decimal description: >- If not equals to 0, the percentage of tax to be applied to this item tax_id: type: string description: ID of the `tax` object this tax data refers to tax_exemption: type: object description: When filled, the reason why this amount is tax exempt nullable: true properties: type: type: string description: Enum representing why this amount is tax exempt legal_notice: type: string description: >- A piece of text to be displayed on document representations justifying the tax exemption. nullable: true supplier_details: type: object description: The tax calculation supplier's details properties: address: type: object properties: line1: type: string nullable: true description: Address line 1 (e.g., street name and number). line2: type: string nullable: true description: Address line 2 (e.g., apartment, suite, unit, or building). city: type: string nullable: true description: City name. postal_code: type: string nullable: true description: Postal or ZIP code. state: type: string nullable: true description: State, province, or region. country: type: string description: Country ISO alpha-2 code (e.g., "FR", "US"). **Required.** tax_registrations: type: array description: >- The supplier's tax registration data. They represent where the organization is registered for tax. items: type: object properties: country: type: string description: The country ISO alpha2 code for this tax registration number: type: string description: The tax number for this registration tax_registration_type: type: string description: Type of the tax registration nullable: true nullable: true errorResponse: type: object properties: message: type: string status: type: integer type: type: string enum: - INVALID_REQUEST_ERROR params: nullable: true type: array items: type: object properties: field: type: string errors: type: array items: type: string securitySchemes: basic_auth: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.