> If you are setting up, configuring, or answering questions about Schematic, connect the > Schematic MCP server before working from these pages. It reads and writes plans, features, > entitlements, and overrides against the real account, so what you report and what you build > match what actually exists. > > The server is at https://api.schematichq.com/mcp > > From Claude, ChatGPT, or another chat assistant, add it as a custom connector: > https://docs.schematichq.com/working-with-ai > > From a coding assistant such as Claude Code, Codex, or Cursor: > https://docs.schematichq.com/building-with-ai > > For clean Markdown of any page, append `.md` to the page URL. For a complete page index, > see https://docs.schematichq.com/llms.txt # Set the tax ID POST https://api.schematichq.com/checkout/tax-id Content-Type: application/json Saves a tax ID on the company's billing customer and answers with every tax ID now on file. The tax ID is not part of a checkout's cart; save it before the finalize that needs it. Reference: https://docs.schematichq.com/api-reference/components/tax-id/update-checkout-tax-id ## Authentication - `X-Schematic-Api-Key` header (required) — A temporary access token in the `X-Schematic-Api-Key` header. Your server mints it with `POST /temporary-access-tokens` on the secret-key API for a company, optionally for one of its users, and hands it to the page. The token fixes the company every request reads and writes. ## Request ### Body (application/json) This endpoint expects an UpdateCheckoutTaxIDRequestBody. - `tax_id` (TaxIDInput, required) ## Response ### 200 OK - `data` (UpdateCheckoutTaxIDResponseData, required) - `params` (CheckoutTaxIdPostResponsesContentApplicationJsonSchemaParams, required) — Input parameters ## Errors ### 400 Bad Request Error Bad request - `error` (string, required) — Error message - `problems` (list of CheckoutProblemResponseData, optional) — On a checkout write or finalize the purchase rules refuse: what the server found wrong, the same list the checkout's `problems` field holds. Each has a `code`, whether it is `blocking`, a `message` safe to show the customer, and the ids of what it is about. ### 401 Unauthorized Error Unauthorized - `error` (string, required) — Error message - `problems` (list of CheckoutProblemResponseData, optional) — On a checkout write or finalize the purchase rules refuse: what the server found wrong, the same list the checkout's `problems` field holds. Each has a `code`, whether it is `blocking`, a `message` safe to show the customer, and the ids of what it is about. ### 403 Forbidden Error Forbidden - `error` (string, required) — Error message - `problems` (list of CheckoutProblemResponseData, optional) — On a checkout write or finalize the purchase rules refuse: what the server found wrong, the same list the checkout's `problems` field holds. Each has a `code`, whether it is `blocking`, a `message` safe to show the customer, and the ids of what it is about. ### 404 Not Found Error Not found - `error` (string, required) — Error message - `problems` (list of CheckoutProblemResponseData, optional) — On a checkout write or finalize the purchase rules refuse: what the server found wrong, the same list the checkout's `problems` field holds. Each has a `code`, whether it is `blocking`, a `message` safe to show the customer, and the ids of what it is about. ### 500 Internal Server Error Server error - `error` (string, required) — Error message - `problems` (list of CheckoutProblemResponseData, optional) — On a checkout write or finalize the purchase rules refuse: what the server found wrong, the same list the checkout's `problems` field holds. Each has a `code`, whether it is `blocking`, a `message` safe to show the customer, and the ids of what it is about. ## Types ### TaxIDInput - `type` (enum, required) - Allowed values: `ae_trn`, `au_abn`, `au_arn`, `br_cnpj`, `br_cpf`, `ca_bn`, `ca_gst_hst`, `ca_pst_bc`, `ca_pst_mb`, `ca_pst_sk`, `ca_qst`, `ch_uid`, `ch_vat`, `eu_vat`, `gb_vat`, `hk_br`, `id_npwp`, `il_vat`, `in_gst`, `jp_cn`, `jp_rn`, `jp_trn`, `kr_brn`, `mx_rfc`, `my_frp`, `my_itn`, `my_sst`, `no_vat`, `nz_gst`, `ph_tin`, `sa_vat`, `sg_gst`, `sg_uen`, `th_vat`, `tr_tin`, `tw_vat`, `us_ein`, `za_vat` - `value` (string, required) ### UpdateCheckoutTaxIDResponseData - `tax_ids` (list of CompanyTaxIDView, required) ### CheckoutTaxIdPostResponsesContentApplicationJsonSchemaParams Input parameters ### CheckoutProblemResponseData - `blocking` (boolean, required) — Whether completing the checkout would be refused while this stands. - `code` (enum, required) - Allowed values: `add_on_conflicts_with_plan`, `add_on_interval_mismatch`, `add_on_requires_billed_plan`, `add_on_unavailable`, `billing_cycle_anchor_conflicts_with_trial`, `billing_cycle_anchor_must_be_future`, `billing_cycle_anchor_needs_new_subscription`, `billing_cycle_anchor_without_plan`, `billing_start_date_must_be_past`, `billing_start_date_needs_new_subscription`, `billing_start_date_needs_renewal_date`, `billing_start_date_not_before_renewal_date`, `billing_start_date_too_far_in_past`, `checkout_superseded`, `credit_bundle_incompatible`, `credit_bundle_unavailable`, `credit_bundles_activate_on_payment`, `currency_mismatch`, `custom_field_required`, `discount_ineligible`, `downgrade_not_permitted`, `end_date_must_be_future`, `end_date_needs_new_subscription`, `end_date_not_after_renewal_date`, `free_first_period_activates_on_payment`, `invoice_email_required`, `invoiced_subscription_conflicts_with_trial`, `invoiced_subscription_needs_new_subscription`, `invoiced_subscription_requires_plan`, `opt_in_required`, `pay_in_advance_price_invalid`, `pay_in_advance_required`, `payment_method_required`, `plan_not_trialable`, `plan_unavailable`, `price_unavailable`, `prorate_first_period_without_anchor`, `provider_rejected`, `scheduled_change_blocks_purchase`, `scheduled_change_pending`, `selection_invalid`, `subscription_currency_change`, `trial_end_must_be_future`, `trial_end_too_far`, `trial_excludes_add_ons`, `trial_excludes_usage_based`, `usage_price_missing_for_interval`, `usage_over_limit` - `message` (string, required) — What is wrong, in words safe for anyone allowed to read the checkout. - `source` (enum, required) - Allowed values: `provider`, `requirement`, `validation` - `bundle_id` (string, optional, nullable) - `currency` (enum, optional) — The currency this problem is about, when it is about one. - Allowed values: `aed`, `afn`, `all`, `amd`, `ang`, `aoa`, `ars`, `aud`, `awg`, `azn`, `bam`, `bbd`, `bdt`, `bif`, `bmd`, `bnd`, `bob`, `brl`, `bsd`, `bwp`, `byn`, `bzd`, `cad`, `cdf`, `chf`, `clp`, `cny`, `cop`, `crc`, `cve`, `czk`, `djf`, `dkk`, `dop`, `dzd`, `egp`, `etb`, `eur`, `fjd`, `fkp`, `gbp`, `gel`, `gip`, `gmd`, `gnf`, `gtq`, `gyd`, `hkd`, `hnl`, `htg`, `huf`, `idr`, `ils`, `inr`, `isk`, `jmd`, `jpy`, `kes`, `kgs`, `khr`, `kmf`, `krw`, `kyd`, `kzt`, `lak`, `lbp`, `lkr`, `lrd`, `lsl`, `mad`, `mdl`, `mga`, `mkd`, `mmk`, `mnt`, `mop`, `mur`, `mvr`, `mwk`, `mxn`, `myr`, `mzn`, `nad`, `ngn`, `nio`, `nok`, `npr`, `nzd`, `pab`, `pen`, `pgk`, `php`, `pkr`, `pln`, `pyg`, `qar`, `ron`, `rsd`, `rub`, `rwf`, `sar`, `sbd`, `scr`, `sek`, `sgd`, `shp`, `sle`, `sos`, `srd`, `std`, `szl`, `thb`, `tjs`, `top`, `try`, `ttd`, `twd`, `tzs`, `uah`, `ugx`, `usd`, `uyu`, `uzs`, `vnd`, `vuv`, `wst`, `xaf`, `xcd`, `xcg`, `xof`, `xpf`, `yer`, `zar`, `zmw` - `detail` (string, optional) — Diagnostic detail for operators, including what the billing provider said. Never shown to a customer. - `feature_id` (string, optional, nullable) - `field_id` (string, optional, nullable) - `payment_method_id` (string, optional, nullable) - `plan_id` (string, optional, nullable) - `price_id` (string, optional, nullable) ### CompanyTaxIDView - `country` (string, required) - `id` (string, required) - `type` (string, required) - `value` (string, required) - `verification_status` (string, optional, nullable) ## Examples **Request** ```json { "tax_id": { "type": "ae_trn", "value": { "type": "ae_trn", "value": "string" } } } ``` **Response** ```json { "data": { "tax_ids": [ { "country": "string", "id": "string", "type": "string", "value": "string", "verification_status": "string" } ] }, "params": {} } ``` **SDK Code** ```python import requests url = "https://api.schematichq.com/checkout/tax-id" payload = { "tax_id": { "type": "ae_trn", "value": { "type": "ae_trn", "value": "string" } } } headers = { "X-Schematic-Api-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.schematichq.com/checkout/tax-id'; const options = { method: 'POST', headers: {'X-Schematic-Api-Key': '', 'Content-Type': 'application/json'}, body: '{"tax_id":{"type":"ae_trn","value":{"type":"ae_trn","value":"string"}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.schematichq.com/checkout/tax-id" payload := strings.NewReader("{\n \"tax_id\": {\n \"type\": \"ae_trn\",\n \"value\": {\n \"type\": \"ae_trn\",\n \"value\": \"string\"\n }\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Schematic-Api-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.schematichq.com/checkout/tax-id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Schematic-Api-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"tax_id\": {\n \"type\": \"ae_trn\",\n \"value\": {\n \"type\": \"ae_trn\",\n \"value\": \"string\"\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.schematichq.com/checkout/tax-id") .header("X-Schematic-Api-Key", "") .header("Content-Type", "application/json") .body("{\n \"tax_id\": {\n \"type\": \"ae_trn\",\n \"value\": {\n \"type\": \"ae_trn\",\n \"value\": \"string\"\n }\n }\n}") .asString(); ``` ```php request('POST', 'https://api.schematichq.com/checkout/tax-id', [ 'body' => '{ "tax_id": { "type": "ae_trn", "value": { "type": "ae_trn", "value": "string" } } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-Schematic-Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.schematichq.com/checkout/tax-id"); var request = new RestRequest(Method.POST); request.AddHeader("X-Schematic-Api-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"tax_id\": {\n \"type\": \"ae_trn\",\n \"value\": {\n \"type\": \"ae_trn\",\n \"value\": \"string\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Schematic-Api-Key": "", "Content-Type": "application/json" ] let parameters = ["tax_id": [ "type": "ae_trn", "value": [ "type": "ae_trn", "value": "string" ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.schematichq.com/checkout/tax-id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```