--- title: "Request a calculation" method: POST path: "/tax/v2/calculations" tags: ["Tax"] --- # Request a calculation `POST /tax/v2/calculations` In the one example, you can see a tax determination for a service provided directly to a consumer not through a marketplace. The other example shows a tax determination for a transaction that takes place between a third party seller and a consumer through a marketplace. Note that these examples are just indicative. Fonoa's tax engine covers a vast larger set of use cases. If you want to learn more about Fonoa's tax engine, its functionalities, or see it in action, please get in touch here - https://www.fonoa.com/contact-sales. ## Request body - TaxDetermineRequest - `supplier` object, required — The supplier object contains parameters related to the supplier/seller for a given transaction. - `taxable` boolean, required — Defines whether the supplier is taxable or not in the supplier country. - `country` string, required — Supplier's country code expressed in ISO 3166-1 alpha-2 format (e.g., au for Australia, hr for Croatia). - `tax_region` string — Supplier's region code (e.g., bc for British Columbia). This parameter is relevant for certain countries only. - `registered_in_customer_country` boolean — Specifies whether the supplier is tax registered in the customer country. - `reference_id` string — This parameter can be used when a marketplace is requesting a calcultion for an underlying transaction between a third party supplier and the end customer in its platform and wants to uniquely identify that supplier using an identifier from its systems. - `customer` object, required — The customer object contains parameters related to the customer/buyer for a given transaction. - `taxable` boolean, required — Defines whether the customer is taxable or not in the customer country. - `country` string, required — Customer's country code expressed in ISO 3166-1 alpha-2 format (e.g., au for Australia, hr for Croatia). - `tax_region` string — Customer's region code (e.g., bc for British Columbia). This parameter is relevant for certain countries only. - `marketplace` object — The marketplace object contains parameters related to the marketplace assuming this is a transaction happening via a marketplace. - `registered_in_customer_country` boolean — It can be used to indicate whether the marketplace is tax registered in the customer country. - `calculate_for_unregistered_customer_countries` boolean — Specifies whether the marketplace wants to receive a calculation even if it is not tax registered in the customer country. - `is_user_marketplace` boolean — This parameter indicates whether a transaction is processed from a marketplace's perspective and the marketplace wants to receive a tax determination even if the marketplace is potntially not liable as the deemed supplier. - `transaction` object, required — The transaction object contains parameters related to the order/transaction in general. - `id` string — This can any value that uniquely identifies this transaction e.g. an order or transaction identifier. If provided it should be a value that has not been used already in the past for a tax calculation with Fonoa. - `price_includes_tax` boolean — Specifies whether the price(s) of the transaction items are deemed to include any indirect taxes or not. It applies to all items of a transaction. - `date` string, ISO8601, required — Date of the transaction in ISO8601 format (YYYY-MM-DDThh:mm:ssTZD). - `description` string — Description for the transaction. - `through_marketplace` boolean — Specifies whether the transaction takes place through a marketplace. - `items` object[], required — Use the items object to specify the items being transacted in a given transaction and their details. - `id` string, required — A unique id per line item. In the same API call, each line item needs to have a different id. - `unit_price` number, required — Item amount/value. It will be treated as net of indirect taxes or gross based on the input on the price_includes_tax parameter. - `tax_category_code` string, required — A code that specifies the category of the item that is being transacted. The list of possible values will be provided by Fonoa during integration. One value is provided in the examples. - `quantity` number — It indicates the quantity for this line item. It will default to 1 if no value is provided. - `description` string — Description for the line item. ## Response `200` OK - TaxDetermineResponse - `total_gross` number, required — The gross amount of the entire transaction (and all its items) excluding any withholding taxes. total_gross = items.gross_amount (1) + items.gross_amount (2) + ... - `total_net` number, required — The net amount of the entire transaction (and all its items). total_net = items.net_amount (1) + items.net_amount (2) + … - `total_indirect_tax_amount` number, required — The aggregation of all indirect tax amounts of the entire transaction (and all its items). It excludes any withholding taxes. total.indirect_tax_amount = items.indirect_tax_amount(1) + items.indirect_tax_amount(2) + … - `items` object[], required — he items object contains info per item (product/service) as it was requested by the clients. It has some root level info and two additional objects namely the tax_breakdown and unit_ The items are identified by the ‘id’ field provided per item in the request. - `id` string, required — The id provided in the API request for this item (items.id). Should be unique per item. Use it to identify items provided in the request. - `quantity` integer — The quantity provided in the API request for this item (items.quantity). - `unit_price` number, float, required — The unit_price provided in the API request for this item (items.unit_price) - `supplier_taxable` boolean — We are referencing the supplier as provided in the API call - so in case the marketplace does the call, them, in case another supplier, that supplier. - `tax_logic_label` string — A string that identifies the tax logic that has been applied for that transaction. - `gross_amount` number, required — Gross amount for the item. Doesn't include withholding taxes. It's multiplied by quantity. items.gross_amount = items.net_amount + items.indirect_tax_amount - `net_amount` number, required — Net amount for the item stripped of any indirect taxes that are already applied. - `indirect_tax_amount` number, required — An aggregation of the tax amounts from all the indirect taxes being applied. indirect_tax_amount = tax_breakdown.amount(1) + tax_breakdown.amount(2)... - `effective_indirect_tax_rate` number, required — Effective indirect tax rate for the item. It doesn't include withholding taxes. - `unit` object — It shows the gross, net and indirect tax amounts on unit level i.e. for quantity = 1 of this item. - `net_amount` number — The indirect tax amount for a single quantity of this item. unit.net_amount = items.net_amount / items.quantity - `gross_amount` number — The gross tax amount for a single quantity of this item unit.gross_amount = items.gross_amount / items.quantity - `indirect_tax_amount` number — The indirect tax amount for a single quantity of this item. unit.indirect_tax_amount = items.indirect_tax_amount / items.quantity - `tax_breakdown` object[], required — The tax breakdown details the exact taxes that apply for that item. - `type` string, required — Indicates what type of tax applied. It can take the value indirect or withholding. - `name` string, required — The specific name of the tax applied e.g. IVA, GST, QST, ISR - `amount` number, required — The tax amount that has been applied. It's already multiplied by quantity. Example: if items.net_amount = 200 and the tax_breakdown.rate = 10% → here we will have amount = 20 ($10 per quantity if quantity is 2). - `rate` number, required — The tax rate that has been applied. - `remit` number, required — The amount that needs to be remitted to the government. It's already multiplied by quantity. It is only returned for cases where the supplier is in Mexico. - `country` string, required — The country the tax of which has been applied expressed in ISO 3166-1 alpha-2 format. - `tax_region` string, required — The tax region the tax of which has been applied expressed in ISO 3166-1 alpha-2 format. Only shown when the tax is in Canada. - `taxable_amount` number — The amount on top of which the tax shown in this object was applied. It's already multiplied by quantity. ## Other responses - `400` — Bad Request - `500` — Internal Server Error --- [API](https://skmtc.dev/fonoa/apis/fonoa-api.md) · [All operations](https://skmtc.dev/fonoa/apis/fonoa-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fonoa/fonoa-api/revisions/cf0ebc843a3f/schema)