{"openapi":"3.1.0","info":{"title":"API Reference","version":"1.0.0"},"paths":{"/request/v60":{"get":{"operationId":"get-tax-rates-v-60","summary":"Get Tax Rates","description":"**Every request locates the applicable jurisdiction(s) with one of three parameter sets.** Send the parameters from a single set. When parameters from more than one set are present, the most precise set wins: `address`, then `lat`/`lng`, then `postalcode`.\n\n**Option 1 (recommended) — `address`.** Geocodes the street address to a single rooftop-level jurisdiction and applies unincorporated-area and special-district adjustments. This is the preferred method and the one to use for calculating tax.\n\n**Option 2 (alternative) — `lat` and `lng`.** Resolves the single jurisdiction containing a geographic point. Use it when you already have verified coordinates and want to skip geocoding. Both parameters are required; one on its own is not a coordinate lookup.\n\n**Option 3 (general use only, not an accurate rate method) — `postalcode`, plus optional `state` (or `stateCode`), `county`, and `city`.** Returns every rate that overlaps the ZIP, with no door-level accuracy. The optional parameters only narrow that list; they do not resolve a single jurisdiction. Do not use this set to calculate tax on a transaction. A postal-code lookup (no `address` and no `lat`/`lng`) also returns the legacy v5.0-style response body (`version`, `rCode`, `results`) rather than the structured object documented below.\n\nOptions 1 and 2 are geocoded lookups and require a current plan with geocoding; without it the request returns response code 107. A request that supplies none of the three sets returns response code 104.\n\nWalkthroughs with full request and response samples: [By Address](/guides/rest-api/by-address), [By Lat / Lng](/guides/rest-api/by-lat-lng), [By Postal Code](/guides/rest-api/by-postal-code).","tags":["ZIPTAX API > Tax Rates"],"parameters":[{"name":"key","in":"query","description":"API key that authenticates the request and resolves the account's plan, entitlements, and rate limits. Supply it either as this query parameter or the X-API-KEY request header. A missing, malformed, or unknown key returns response code 101.","required":false,"schema":{"type":"string","minLength":10,"maxLength":100}},{"name":"format","in":"query","description":"Serialization format of the response body. 'json' (default) returns a JSON object; 'xml' returns the same data as an XML document.","required":false,"schema":{"$ref":"#/components/schemas/type_ZIPTAX API/taxRates:GetTaxRatesV60RequestFormat","default":"json"}},{"name":"countryCode","in":"query","description":"Country of the lookup: 'USA' (default), 'CAN', or a US territory (ASM, GUM, MNP, PRI, VIR). 'CAN' requires the Canadian rates (rate_loc_can) entitlement; otherwise the request returns response code 112. US territories are looked up via the USA path and require no additional entitlement.","required":false,"schema":{"$ref":"#/components/schemas/type_ZIPTAX API/taxRates:GetTaxRatesV60RequestCountryCode","default":"USA"}},{"name":"postalcode","in":"query","description":"5-digit US ZIP code to look up. When supplied on its own the response may contain rates for multiple overlapping jurisdictions. An invalid format returns response code 104.","required":false,"schema":{"type":"string","pattern":"^[0-9]{5}$","minLength":5,"maxLength":5}},{"name":"address","in":"query","description":"Street address to geocode to a single rooftop-level jurisdiction. Geocoding requires the geo_enabled entitlement; an incomplete or ungeocodable address returns response code 109.","required":false,"schema":{"type":"string","maxLength":100}},{"name":"state","in":"query","description":"State name or two-letter abbreviation. Used with city or postal code to disambiguate the location. An invalid format returns response code 102.","required":false,"schema":{"type":"string","maxLength":50}},{"name":"stateCode","in":"query","description":"Two-letter state code (e.g. CA). Alternative to 'state' for supplying the state as a code rather than a name.","required":false,"schema":{"type":"string","pattern":"^[A-Z]{2}$","minLength":2,"maxLength":2}},{"name":"city","in":"query","description":"City name used together with state to narrow the lookup when no street address is supplied. An invalid format returns response code 103.","required":false,"schema":{"type":"string","maxLength":50}},{"name":"county","in":"query","description":"County name used to refine the lookup when supplied without a street address.","required":false,"schema":{"type":"string","maxLength":50}},{"name":"lat","in":"query","description":"Latitude of a geographic point. When both lat and lng are supplied the API resolves the single jurisdiction containing that point (coordinate lookup).","required":false,"schema":{"type":"number","format":"double","minimum":-90,"maximum":90}},{"name":"lng","in":"query","description":"Longitude of a geographic point. When both lat and lng are supplied the API resolves the single jurisdiction containing that point (coordinate lookup).","required":false,"schema":{"type":"number","format":"double","minimum":-180,"maximum":180}},{"name":"adjustment","in":"query","description":"Sourcing/unincorporated-area handling. Defaults to 'auto', which applies the appropriate sourcing adjustment on geo (address) lookups in unincorporated areas. The values 'origin' and 'destination' are accepted but currently do not change the resolved result.","required":false,"schema":{"$ref":"#/components/schemas/type_ZIPTAX API/taxRates:GetTaxRatesV60RequestAdjustment","default":"auto"}},{"name":"sat_item_total","in":"query","description":"Single-article item total in dollars, used for Tennessee Single Article Tax (SAT) calculation on TN address lookups. Note: the v6.0 response does not currently return a SAT breakdown object; the SAT detail (satTaxDetail) is available in the v5.0 response.","required":false,"schema":{"type":"number","format":"double","minimum":0}},{"name":"historical","in":"query","description":"Historical period to price the lookup against, formatted YYYYMM (6 digits, e.g. 202401). Returns the rates that were in effect for that month. Requires historical data to be enabled; an invalid format returns response code 111.","required":false,"schema":{"type":"string","pattern":"^[0-9]{6}$"}},{"name":"taxabilityCode","in":"query","description":"Product Taxability Information Code (TIC). When supplied, the response includes a productDetail object describing the rate rules that apply to that product category in the resolved jurisdiction. Accepts numeric standard TIC codes (e.g., 20010) or alphanumeric override codes (e.g., CIR00001). Requires the product_rates entitlement for standard codes.","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9]{1,10}$"}},{"name":"addressDetailExtended","in":"query","description":"When true, returns a full geocoding object in the response broken into address parts (street, city, postal code, etc.). Defaults to false.","required":false,"schema":{"type":"boolean","default":false}},{"name":"shippingExtended","in":"query","description":"When true, returns a detailed shipping object to help navigate collection complexity. The GENERAL_RULE value will be one of: EXEMPT, EXEMPT_WHEN_SEPARATELY_STATED, ITEM_SPECIFIC, CONDITIONAL, or TAXABLE. For EXEMPT_WHEN_SEPARATELY_STATED, the response includes a boolean flag, and a natural-language description is included for clarity. Defaults to false.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:V60Response"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"405":{"description":"Method Not Allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}}}},"/account/v60/metrics":{"get":{"operationId":"get-account-metrics-v-60","summary":"Get Account Metrics","description":"Returns usage metrics for the authenticated account in the simplified v6.0 format. In v6.0 all keys are geo keys, so the counters reflect geo usage.","tags":["ZIPTAX API > Account"],"parameters":[{"name":"key","in":"query","description":"API key identifying the account whose usage metrics are returned. May be supplied as this query parameter or the X-API-KEY header.","required":false,"schema":{"type":"string","minLength":10,"maxLength":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:MetricsV60Response"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}}}},"/merchant/create":{"post":{"operationId":"create-merchant","summary":"Create Merchant","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nCreates a new merchant under the authenticated account. Requires X-API-KEY header. Set merchantType to choose the compliance model. \"self-managed\" creates a merchant that is active immediately with no TaxCloud invite; \"taxcloud\" (the default) starts the TaxCloud invite process and is an Enterprise plan feature.","tags":["ZIPTAX API > Merchant"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:CreateMerchantResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchantName":{"type":"string","minLength":1,"maxLength":255,"description":"Legal or trading name of the merchant business. Required; must be 1–255 characters."},"contactFirst":{"type":"string","description":"First name of the merchant's primary contact."},"contactLast":{"type":"string","description":"Last name of the merchant's primary contact."},"contactEmail":{"type":"string","description":"Email address of the merchant's primary contact; used for TaxCloud invitations and notifications."},"sendTaxcloudInvite":{"type":"boolean","description":"Sends invite to set up and connect a TaxCloud account to a merchant who does not already use TaxCloud. To connect a TaxCloud account for a merchant who already uses TaxCloud, use the \"Set Merchant Credentials\" function. Ignored when merchantType is 'self-managed'."},"merchantType":{"$ref":"#/components/schemas/type_ZIPTAX API/merchant:CreateMerchantRequestMerchantType","default":"taxcloud","description":"The merchant's compliance model, chosen once at creation. 'taxcloud' (the default) starts the TaxCloud invite process, so TaxCloud can handle registration, filing, and remittance for the merchant; creating one requires an Enterprise plan. 'self-managed' skips the invite entirely and the merchant is active as soon as the call returns, with the merchant remaining responsible for their own compliance."},"referenceId":{"type":"string","maxLength":255,"description":"The ID you use in your own system to identify this merchant."}},"required":["merchantName"]}}}}}},"/merchant/update":{"post":{"operationId":"update-merchant","summary":"Update Merchant","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nUpdates a merchant's details, its compliance model, or both.\n\nSend `update` to change the merchant's name and contact details, `setMerchantType` to switch the merchant between the `taxcloud` and `self-managed` compliance models, or both together. At least one of the two is required.\n\nSwitching the compliance model sets the merchant's `status`:\n\n| `setMerchantType` | Resulting `status` |\n| --- | --- |\n| `taxcloud` | `taxcloud_invited`, and a TaxCloud invite is emailed to the merchant |\n| `self-managed` | `external_compliance` |\n\n**Switching to `self-managed` disconnects the merchant from TaxCloud.** Their stored TaxCloud credentials are removed, so the order, exemption certificate, and refund endpoints return 403 for them and cart calculation switches to Ziptax's own rate engine. Reconnecting later means switching back to `taxcloud` and setting their credentials again with Set Merchant Credentials.\n\nSending the compliance model a merchant already has changes nothing and does not re-send the invite, so a request is safe to repeat.\n\nYou can only update merchants that belong to your account. Requests for any other merchant, or for one that has been deleted, return 403.","tags":["ZIPTAX API > Merchant"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:UpdateMerchantResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the merchant to update. The merchant must be owned by the calling account."},"sendTaxcloudInvite":{"type":"boolean","description":"Whether to email the merchant a TaxCloud invite when this request switches them to 'taxcloud'. Defaults to true. It has no effect on a request that does not change the compliance model, so repeating a request will not invite the merchant twice. The invite goes to the merchant's stored contactEmail; include an 'update' block to change that address first. A merchant with no contact email cannot be invited."},"setMerchantType":{"$ref":"#/components/schemas/type_ZIPTAX API/merchant:UpdateMerchantRequestSetMerchantType","description":"Switches the merchant to a different compliance model. Use 'taxcloud' to have TaxCloud handle the merchant's registration, filing, and remittance: their status becomes 'taxcloud_invited' and they are emailed an invite. Use 'self-managed' to hand compliance back to the merchant: their status becomes 'external_compliance' and their stored TaxCloud credentials are removed. 'connected' and 'offline' are deprecated names for 'taxcloud' and 'self-managed'. Sending the merchant's current model changes nothing. Omit this field to leave the compliance model as it is."},"update":{"$ref":"#/components/schemas/type_ZIPTAX API:UpdateStruct","description":"New values for the merchant's name and contact details. Every field in this block is replaced, so send the current value for anything you do not want to clear. Omit the block to change only the compliance model."}},"required":["merchantId"]}}}}}},"/merchant/delete":{"post":{"operationId":"delete-merchant","summary":"Delete Merchant","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nDeletes a merchant. You can only delete merchants that belong to your account. Requests for any other merchant, or for one that has already been deleted, return 403.","tags":["ZIPTAX API > Merchant"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:DeleteMerchantResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the merchant to soft-delete. The merchant must be owned by the calling account."}},"required":["merchantId"]}}}}}},"/merchant/get":{"post":{"operationId":"get-merchant","summary":"Get Merchant","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nReturns a single merchant by ID. You can only read merchants that belong to your account. Requests for any other merchant, or for one that has been deleted, return 404.","tags":["ZIPTAX API > Merchant"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:GetMerchantResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the merchant to retrieve. The merchant must be owned by the calling account."}},"required":["merchantId"]}}}}}},"/merchant/list":{"get":{"operationId":"list-merchants","summary":"List Merchants","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nReturns every active merchant on your account. Deleted merchants are not included.","tags":["ZIPTAX API > Merchant"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:Item"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}}}},"/merchant/credentials/set":{"post":{"operationId":"set-merchant-credentials","summary":"Set Merchant Credentials","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nSets or updates TaxCloud credentials for a merchant. Credentials are encrypted at rest with AES-256-GCM. On success an asynchronous webhook notification is sent to the configured endpoint.","tags":["ZIPTAX API > Merchant"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:SetMerchantCredentialsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string","description":"TaxCloud API key to associate with the merchant. Stored encrypted at rest with AES-256-GCM."},"connectionId":{"type":"string","description":"TaxCloud connection ID that pairs with the API key to identify the merchant's TaxCloud integration."},"merchantId":{"type":"string","description":"UUID of the merchant whose TaxCloud credentials are being set. The merchant must be owned by the calling account."}},"required":["apiKey","connectionId","merchantId"]}}}}}},"/merchant/credentials/delete":{"post":{"operationId":"delete-merchant-credentials","summary":"Delete Merchant Credentials","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nDeletes TaxCloud credentials for a merchant. The caller must own the merchant.","tags":["ZIPTAX API > Merchant"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:DeleteMerchantCredentialsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the merchant whose TaxCloud credentials are being deleted. The merchant must be owned by the calling account."}},"required":["merchantId"]}}}}}},"/merchant/nexus/create":{"post":{"operationId":"create","summary":"Create Nexus Locations","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nRecords one or more physical locations for a merchant. A merchant's physical locations are what establish its nexus, and nexus is what decides whether a sale is sourced at its origin or its destination, so this is the data a self-managed cart calculation depends on.\n\nEach address is geocoded as it is written, and the normalized result is what every response returns; expect the address you get back to differ from the one you sent. If any address in the request cannot be resolved to a US state the whole request is rejected with 422 and nothing is stored, so a retry cannot duplicate the locations that would otherwise have succeeded.\n\nAddress resolution for the whole request is budgeted at 10 seconds. A batch that exceeds it returns 504 and stores nothing; send fewer locations per call if you hit this. Geocoding that had already completed is still billed, because the lookups were still performed.\n\nAvailable to self-managed merchants only. A TaxCloud-connected merchant's nexus is held in TaxCloud, so this returns 403 for them.","tags":["ZIPTAX API > Merchant Nexus"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:MerchantNexusCreateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusLocationInput"},"description":"The locations to record. Up to 25 per call; each one is geocoded as it is written, which is what bounds the batch."},"merchantId":{"type":"string","description":"UUID of the merchant these locations belong to. Must be owned by the calling account and must be self-managed."},"nexusType":{"type":"string","enum":["physical"],"description":"The kind of nexus being recorded. Only 'physical' can be created: economic nexus is derived from a merchant's sales activity rather than declared, so sending 'economic' is rejected rather than silently stored as physical."}},"required":["locations","merchantId"]}}}}}},"/merchant/nexus/list":{"post":{"operationId":"list","summary":"List Nexus Locations","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nReturns a merchant's recorded nexus locations. Deleted locations are not included.\n\nAvailable to self-managed merchants only; a TaxCloud-connected merchant returns 403, and their nexus is read through the Management API instead.","tags":["ZIPTAX API > Merchant Nexus"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:MerchantNexusListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the merchant whose locations to list. Must be owned by the calling account and must be self-managed."},"nexusType":{"$ref":"#/components/schemas/type_ZIPTAX API/merchantNexus:MerchantNexusListRequestNexusType","description":"Restricts the response to one kind of nexus. Omit it to return every kind. Only 'physical' is supported; 'economic' is rejected with 400, because those rows carry a registration id instead of an address and do not fit this response shape (ZIP-1214)."}},"required":["merchantId"]}}}}}},"/merchant/nexus/update":{"post":{"operationId":"update","summary":"Update Nexus Location","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nReplaces a recorded location.\n\nThe `location` block is a full replacement, not a patch: every field in it is written, so send the current value for anything you do not want cleared. The address is geocoded again, so an update may change the normalized address even when you send the same string, and a location can be moved to a different state this way.\n\nAvailable to self-managed merchants only; a TaxCloud-connected merchant returns 403.","tags":["ZIPTAX API > Merchant Nexus"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:MerchantNexusUpdateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusLocationInput","description":"The location's new contents. Every field is replaced, so send the current value for anything you do not want to clear."},"locationId":{"type":"string","description":"Identifier of the location to replace, as returned by /merchant/nexus/create or /merchant/nexus/list. A location that has been deleted returns 404."},"merchantId":{"type":"string","description":"UUID of the merchant that owns the location. Must be owned by the calling account and must be self-managed."}},"required":["location","locationId","merchantId"]}}}}}},"/merchant/nexus/delete":{"post":{"operationId":"delete","summary":"Delete Nexus Location","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nRemoves a recorded location so it no longer contributes to the merchant's nexus. The location stops appearing in /merchant/nexus/list immediately, and is retained internally so past filings keep their basis.\n\nRemoving a merchant's last location is allowed: it simply means no physical nexus is tracked for them. Deleting a location that is already gone returns 404.\n\nAvailable to self-managed merchants only; a TaxCloud-connected merchant returns 403.","tags":["ZIPTAX API > Merchant Nexus"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:MerchantNexusDeleteResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"locationId":{"type":"string","description":"Identifier of the location to remove, as returned by /merchant/nexus/create or /merchant/nexus/list."},"merchantId":{"type":"string","description":"UUID of the merchant that owns the location. Must be owned by the calling account and must be self-managed."}},"required":["locationId","merchantId"]}}}}}},"/merchant/cart/calculate":{"post":{"operationId":"merchant-cart-calculate","summary":"Calculate Cart Tax","description":"<span class=\"plan-badge plan-badge--pro\">Available on Pro and Enterprise Plans</span>\n\nCalculates sales tax per line item for one or more carts. The request body is the same for every merchant, and Ziptax routes on the merchant's compliance model.\n\nFor a **TaxCloud-connected merchant**, the cart is forwarded to TaxCloud (POST /connections/{connectionId}/carts) using the merchant's stored credentials, and TaxCloud's response is returned verbatim. Additional cart fields (items, transactionDate, destination, ...) are relayed unchanged. Requires an Enterprise plan and credentials on file; a connected merchant without valid credentials returns 404.\n\nFor a **self-managed merchant** (status external_compliance), Ziptax calculates the tax in-process with its own rate engine and no TaxCloud call. Three differences matter on that path. (1) Calculation only: nothing is persisted, connectionId is omitted from the response, and the returned cartId is a correlation token that cannot be passed to /merchant/order/create-from-cart. (2) tic uses the Ziptax taxability code vocabulary, not TaxCloud's: 10001 is shipping and 11000 is handling, while TaxCloud's shipping codes (11010-11015) and the Colorado retail delivery fee code (11098) carry no special meaning and are taxed as ordinary product codes. (3) discounts, exemption, and deliveredBySeller are rejected with 400 rather than ignored, non-USD currency and countryCode CA are rejected, and a cart is capped at 250 line items.\n\nEvery other merchant transaction endpoint returns 403 for a self-managed merchant. See the Self-Managed Cart Calculation guide for the full contract.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Calculated carts. For a TaxCloud-connected merchant this is TaxCloud's response relayed verbatim; for a self-managed merchant it is the Ziptax calculation, which has no connectionId, exemption, or deliveredBySeller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API/merchantTaxCloud:MerchantCartCalculateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCart"},"description":"The carts to calculate tax for. Most integrations send a single cart; up to 100 carts may be calculated in one call."},"merchantId":{"type":"string","description":"UUID of the merchant whose TaxCloud connection is used. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"transactionDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the carts are calculated for. Defaults to the current time when omitted."}},"required":["items","merchantId"]}}}}}},"/merchant/order/create-from-cart":{"post":{"operationId":"merchant-order-create-from-cart","summary":"Create Order From Cart","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud POST /connections/{connectionId}/carts/orders to capture a previously calculated cart as an order. cartId and orderId travel in the forwarded body. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudOrderResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cartId":{"type":"string","minLength":1,"maxLength":50,"description":"The cartId returned by (or supplied to) /merchant/cart/calculate identifying the calculated cart to convert into an order."},"completed":{"type":"boolean","description":"Whether the order has shipped, creating a tax liability. Defaults to false. Ignored when completedDate is provided."},"completedDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the order was shipped on, which created the tax liability. Takes precedence over the completed field when provided."},"kind":{"$ref":"#/components/schemas/type_ZIPTAX API/merchantTaxCloud:MerchantOrderCreateFromCartRequestKind","default":"order","description":"The kind of order to create: 'order' for a sale (default) or 'credit' for a credit order."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"orderId":{"type":"string","minLength":1,"maxLength":50,"description":"Your identifier for the resulting order in your own system. Used later with /merchant/order/get, /merchant/order/update, and /merchant/refund/create."}},"required":["cartId","merchantId","orderId"]}}}}}},"/merchant/order/create":{"post":{"operationId":"merchant-order-create","summary":"Create Order","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud POST /connections/{connectionId}/orders to create an order directly. All order fields other than merchantId are relayed unchanged. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudOrderResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string","description":"Batch ID for grouping related orders."},"channel":{"type":"string","description":"The sales channel the order came from. Pass one of amazon, ebay, or walmart to exclude marketplace-collected tax from filing."},"completedDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the order was shipped on, which created the tax liability."},"currency":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCurrency","description":"The currency the line-item prices and tax amounts are denominated in."},"customerId":{"type":"string","maxLength":50,"description":"Your identifier for the customer in your own system. Used to match exemption certificates and order history."},"deliveredBySeller":{"type":"boolean","description":"Whether the seller delivers the order directly (own vehicles) rather than via common carrier. Affects taxability of delivery charges in some states."},"destination":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-to (destination) address of the sale."},"discounts":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudDiscounts","description":"Line-item and order-level discounts to apply. If omitted, prices are used as is."},"excludeFromFiling":{"type":"boolean","description":"Whether to exclude the order from tax filing."},"exemption":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudExemption","description":"Exemption information for the customer."},"kind":{"$ref":"#/components/schemas/type_ZIPTAX API/merchantTaxCloud:MerchantOrderCreateRequestKind","default":"order","description":"The kind of order: 'order' for a sale (default) or 'credit' for a credit order."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCartItemWithTax"},"description":"The items on the order, each including the tax rate and amount that was collected."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"orderId":{"type":"string","maxLength":50,"description":"Your identifier for the order in your own system. Used later with /merchant/order/get, /merchant/order/update, and /merchant/refund/create."},"origin":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-from (origin) address of the sale."},"transactionDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the order was purchased on."}},"required":["completedDate","currency","customerId","destination","lineItems","merchantId","orderId","origin","transactionDate"]}}}}}},"/merchant/order/get":{"post":{"operationId":"merchant-order-get","summary":"Get Order","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud GET /connections/{connectionId}/orders/{orderId}. orderId is a path identifier; the optional expand field is passed through as a query parameter. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudOrderResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expand":{"type":"string","enum":["refunds"],"description":"Set to 'refunds' to include the order's refunds in the response. Forwarded to TaxCloud as a query parameter."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"orderId":{"type":"string","description":"Your identifier for the order to retrieve, as supplied when the order was created."}},"required":["merchantId","orderId"]}}}}}},"/merchant/order/update":{"post":{"operationId":"merchant-order-update","summary":"Update Order","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud PATCH /connections/{connectionId}/orders/{orderId}. orderId is a path identifier; the remaining body is the update payload relayed unchanged. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudOrderResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"completedDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the order was shipped on, which creates the tax liability."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"orderId":{"type":"string","description":"Your identifier for the order to update, as supplied when the order was created. Consumed for routing and not forwarded in the update payload."}},"required":["merchantId","orderId"]}}}}}},"/merchant/cert/create":{"post":{"operationId":"merchant-cert-create","summary":"Create Exemption Certificate","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud POST /connections/{connectionId}/exemption-certificates. All certificate fields other than merchantId are relayed unchanged. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCertResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"Address of the exempt customer."},"customerBusinessDescription":{"type":"string","description":"Free-text description of the business. Provide when customerBusinessType is Other."},"customerBusinessType":{"$ref":"#/components/schemas/type_ZIPTAX API/merchantTaxCloud:MerchantCertCreateRequestCustomerBusinessType","description":"The type of business the customer is."},"customerId":{"type":"string","description":"Your identifier for the exempt customer. Carts and orders submitted with this customerId can use the certificate."},"customerName":{"type":"string","description":"Name of the customer or organization the certificate is issued to."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"reason":{"$ref":"#/components/schemas/type_ZIPTAX API/merchantTaxCloud:MerchantCertCreateRequestReason","description":"The reason the customer is exempt from sales tax."},"reasonDescription":{"type":"string","maxLength":20,"description":"Short free-text elaboration of the exemption reason (maximum 20 characters)."},"states":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudExemptState"},"description":"The states the certificate is valid in, each as a two-letter abbreviation object."}},"required":["address","customerBusinessType","customerId","customerName","merchantId","reason","reasonDescription","states"]}}}}}},"/merchant/cert/get":{"post":{"operationId":"merchant-cert-get","summary":"Get Exemption Certificate","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud GET /connections/{connectionId}/exemption-certificates/{certificateId}. certificateId is a path identifier. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCertResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificateId":{"type":"string","description":"The certificateId returned when the exemption certificate was created."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."}},"required":["certificateId","merchantId"]}}}}}},"/merchant/cert/list":{"post":{"operationId":"merchant-cert-list","summary":"List Exemption Certificates","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud GET /exemption-certificates, scoped to the merchant's connection via a connectionId query filter, and returns the certificate collection verbatim. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCertListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ascending":{"type":"boolean","default":false,"description":"Whether to sort results in ascending order. Defaults to false (descending)."},"cursor":{"type":"string","description":"Opaque pagination cursor from the nextCursor field of a previous response. Omit to start at the first page."},"customerId":{"type":"string","description":"Filter results to certificates belonging to this customerId."},"disabled":{"type":"boolean","default":false,"description":"Set true to list disabled (revoked) certificates instead of active ones. Defaults to false."},"limit":{"type":"integer","format":"int64","default":20,"description":"Maximum number of certificates to return per page. Defaults to 20; maximum 100."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"sortBy":{"$ref":"#/components/schemas/type_ZIPTAX API/merchantTaxCloud:MerchantCertListRequestSortBy","default":"id","description":"The field to sort results by: 'createdDate' or 'id'. Defaults to 'id'."}},"required":["merchantId"]}}}}}},"/merchant/cert/delete":{"post":{"operationId":"merchant-cert-delete","summary":"Delete Exemption Certificate","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud DELETE /connections/{connectionId}/exemption-certificates/{certificateId}. certificateId is a path identifier. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"description":"Any type"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificateId":{"type":"string","description":"The certificateId returned when the exemption certificate was created."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."}},"required":["certificateId","merchantId"]}}}}}},"/merchant/refund/create":{"post":{"operationId":"merchant-refund-create","summary":"Create Refund","description":"<span class=\"plan-badge plan-badge--enterprise\">Available on Enterprise Plan</span>\n\nForwards to TaxCloud POST /connections/{connectionId}/orders/refunds/{orderId}. orderId is a path identifier; an optional items[] in the forwarded body scopes a partial refund (omit for a full refund). Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate.","tags":["ZIPTAX API > merchantTaxCloud"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"TaxCloud response relayed verbatim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudRefundResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string","description":"Batch ID for grouping related refunds."},"items":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:RefundItem"},"description":"The line items and quantities to refund. Omit (or send an empty array) to refund the entire order."},"merchantId":{"type":"string","description":"UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud."},"orderId":{"type":"string","description":"Your identifier for the order to refund, as supplied when the order was created. Consumed for routing and not forwarded in the refund payload."},"returnedDate":{"type":"string","format":"date-time","description":"Include only if this return amends a previously filed sales tax return; providing it triggers an Amended Sales Tax Return. Not typically recommended."}},"required":["merchantId","orderId"]}}}}}},"/data/tic":{"get":{"operationId":"get-tic-data","summary":"Get TIC Codes","description":"Returns Taxability Information Code (TIC) data","tags":["ZIPTAX API > Data"],"parameters":[{"name":"format","in":"query","description":"Serialization format of the response body: 'json' (default) or 'xml'.","required":false,"schema":{"$ref":"#/components/schemas/type_ZIPTAX API/data:GetTicDataRequestFormat","default":"json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TicResponse"}}}}}}},"/search/tic":{"post":{"operationId":"search-tic","summary":"Search TIC Codes","description":"Searches Taxability Information Codes (TIC) by free-text product description and returns ranked matches. Requires authentication via the X-API-KEY header or key query parameter.","tags":["ZIPTAX API > search"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TicSearchResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":1024,"description":"Free-text product description to match against TIC codes"}},"required":["query"]}}}}}},"/search/tic/recommend":{"post":{"operationId":"recommend-tic","summary":"Recommend TIC Code","description":"Returns a recommended Taxability Information Code (TIC) for a free-text product description using a machine-learning model. Requires authentication via the X-API-KEY header or key query parameter.","tags":["ZIPTAX API > search"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:TicRecommendResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":1024,"description":"Free-text product description to get a recommended TIC for"}},"required":["query"]}}}}}},"/schemas/ticsearch":{"get":{"operationId":"get-tic-search-schema","summary":"Get TIC Search JSON Schema","description":"Returns the JSON Schema describing the TIC search response body. Public; no authentication required.","tags":["ZIPTAX API > search"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"description":"Any type"}}}}}}}},"/system/health":{"get":{"operationId":"get-health","summary":"Health Check","description":"Returns the health status of the API and its components","tags":["ZIPTAX API > System"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:HealthResponse"}}}}}}},"/system/metadata":{"get":{"operationId":"get-metadata","summary":"Get System Metadata","description":"Returns system metadata including version and environment information","tags":["ZIPTAX API > System"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:MetadataResponse"}}}}}}},"/nexus-threshold/list":{"post":{"operationId":"nexus-threshold-list","summary":"List Economic Nexus Thresholds","description":"Returns the economic nexus thresholds that decide when a seller has to register in a state: the sales figure, the transaction count where one still applies, how the two combine, which sales count toward them, whether marketplace sales are included, and the period each state measures over.\n\nThis is reference data. It is the same for every caller and is not derived from your sales: compare it against your own totals to work out where you are approaching a threshold.\n\nSend no body, or no `stateCodes`, to get every jurisdiction the country publishes. `countryCode` defaults to USA, currently the only country published. States with no general statewide sales tax (Delaware, Montana, New Hampshire, Oregon) are returned with `noSalesTax: true` and null thresholds rather than omitted.\n\nA `stateCodes` list naming a code that is not published is rejected with 400 rather than answered with the states that did match, so a typo cannot read back as 'this state has no threshold'.","tags":["ZIPTAX API > nexusThresholds"],"parameters":[{"name":"X-API-KEY","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusThresholdListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorModel"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"countryCode":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 3166-1 alpha-3 country code. Defaults to USA, which is the only country published today. A country with no published data returns 404."},"stateCodes":{"type":"array","items":{"type":"string"},"description":"Two-letter jurisdiction codes to return. Omit it for every jurisdiction. The response is ordered by state code regardless of the order sent, and a repeated code yields one row."}}}}}}}}},"servers":[{"url":"https://api.zip-tax.com","description":"Default"}],"components":{"schemas":{"type_ZIPTAX API/taxRates:GetTaxRatesV60RequestFormat":{"type":"string","enum":["json","xml"],"default":"json","description":"Serialization format of the response body. 'json' (default) returns a JSON object; 'xml' returns the same data as an XML document.","title":"GetTaxRatesV60RequestFormat"},"type_ZIPTAX API/taxRates:GetTaxRatesV60RequestCountryCode":{"type":"string","enum":["USA","CAN","PRI","ASM","GUM","MNP","VIR"],"default":"USA","description":"Country of the lookup: 'USA' (default), 'CAN', or a US territory (ASM, GUM, MNP, PRI, VIR). 'CAN' requires the Canadian rates (rate_loc_can) entitlement; otherwise the request returns response code 112. US territories are looked up via the USA path and require no additional entitlement.","title":"GetTaxRatesV60RequestCountryCode"},"type_ZIPTAX API/taxRates:GetTaxRatesV60RequestAdjustment":{"type":"string","enum":["auto","origin","destination"],"default":"auto","description":"Sourcing/unincorporated-area handling. Defaults to 'auto', which applies the appropriate sourcing adjustment on geo (address) lookups in unincorporated areas. The values 'origin' and 'destination' are accepted but currently do not change the resolved result.","title":"GetTaxRatesV60RequestAdjustment"},"type_ZIPTAX API:V60AddressDetailIncorporated":{"type":"string","enum":["true","false"],"description":"Whether the location falls within incorporated city limits, as the string 'true' or 'false'.","title":"V60AddressDetailIncorporated"},"type_ZIPTAX API:V60AddressComponents":{"type":"object","properties":{"countryCode":{"type":"string","description":"ISO-3 country code of the geocoded location (e.g. USA, CAN)."},"countryName":{"type":"string","description":"Full country name of the geocoded location (e.g. United States, Canada)."},"stateCode":{"type":"string","description":"State or province code (e.g. CA, ON)."},"state":{"type":"string","description":"Full state or province name."},"county":{"type":"string","description":"County name, when available."},"city":{"type":"string","description":"City name."},"street":{"type":"string","description":"Street name."},"postalCode":{"type":"string","description":"Full postal code (ZIP+4 for US addresses when available; full Canadian postal code for Canadian addresses)."},"houseNumber":{"type":"string","description":"House/street number, when available."}},"required":["countryCode","countryName","stateCode","state","county","city","street","postalCode","houseNumber"],"title":"V60AddressComponents"},"type_ZIPTAX API:V60AddressDetail":{"type":"object","properties":{"normalizedAddress":{"type":"string","description":"Standardized address returned by the geocoder, or empty when the location was not geocoded (e.g. postal-code-only lookups)."},"incorporated":{"$ref":"#/components/schemas/type_ZIPTAX API:V60AddressDetailIncorporated","description":"Whether the location falls within incorporated city limits, as the string 'true' or 'false'."},"geoLat":{"type":"number","format":"double","description":"Latitude of the geocoded location, or 0 when the location was not geocoded."},"geoLng":{"type":"number","format":"double","description":"Longitude of the geocoded location, or 0 when the location was not geocoded."},"address":{"$ref":"#/components/schemas/type_ZIPTAX API:V60AddressComponents","description":"Extended address components from the geocoder. Present only when addressDetailExtended=true is supplied on a geocoded (address or lat/lng) lookup. Available for both USA and Canadian lookups."}},"required":["normalizedAddress","incorporated","geoLat","geoLng"],"title":"V60AddressDetail"},"type_ZIPTAX API:V60BaseRateJurType":{"type":"string","enum":["US_STATE_SALES_TAX","US_STATE_USE_TAX","US_COUNTY_SALES_TAX","US_COUNTY_USE_TAX","US_CITY_SALES_TAX","US_CITY_USE_TAX","US_DISTRICT_SALES_TAX","US_DISTRICT_USE_TAX"],"description":"Jurisdiction level combined with the tax kind (sales vs use) this component represents.","title":"V60BaseRateJurType"},"type_ZIPTAX API:V60BaseRate":{"type":"object","properties":{"jurDescription":{"type":"string","description":"Human-readable label combining the jurisdiction and tax type (e.g. 'US State Sales Tax')."},"jurName":{"type":"string","description":"Name or code of the jurisdiction: state alpha code, county/city name, or district label (e.g. 'CA', 'ORANGE', 'Local District: 37')."},"jurTaxCode":{"type":"string","description":"FIPS-like tax code for the jurisdiction (state, county, city, or district). For Texas city components this is the TAID published for the city that contains the address. Null when the jurisdiction has no associated code."},"jurType":{"$ref":"#/components/schemas/type_ZIPTAX API:V60BaseRateJurType","description":"Jurisdiction level combined with the tax kind (sales vs use) this component represents."},"rate":{"type":"number","format":"double","description":"Tax rate for this jurisdiction/tax-type component, as a decimal fraction (e.g. 0.0625 = 6.25%)."}},"required":["jurDescription","jurName","jurType","rate"],"title":"V60BaseRate"},"type_ZIPTAX API:V60ResponseInfo":{"type":"object","properties":{"code":{"type":"integer","format":"int64","description":"Numeric status code (100 = success)"},"definition":{"type":"string","description":"URL to the response schema"},"message":{"type":"string","description":"Human-readable summary"},"name":{"type":"string","description":"Symbolic status name"}},"required":["code","definition","message","name"],"title":"V60ResponseInfo"},"type_ZIPTAX API:V60Metadata":{"type":"object","properties":{"response":{"$ref":"#/components/schemas/type_ZIPTAX API:V60ResponseInfo","description":"Response-code detail: numeric code, symbolic name, human-readable message, and a URL to the response schema definition."},"version":{"type":"string","description":"Schema version of the response payload."}},"required":["response","version"],"title":"V60Metadata"},"type_ZIPTAX API:V60TaxabilityCodeRateActionCode":{"type":"string","enum":["T00","T01","T02","T03"],"description":"Outcome of the TIC lookup: T00 (valid TIC, rules listed), T01 (valid TIC, no applicable rate rules), T02 (invalid TIC), T03 (invalid TIC format).","title":"V60TaxabilityCodeRateActionCode"},"type_ZIPTAX API:V60RateRule":{"type":"object","properties":{"effectiveDt":{"type":"integer","format":"int64","description":"Date the rule takes effect, in YYYYMMDD format; null when not specified."},"effectiveTaxRate":{"type":"number","format":"double","description":"Decimal tax rate that applies to this product in this jurisdiction; null when not specified."},"exemptOver":{"type":"number","format":"double","description":"Amounts above this dollar value are exempt; null when not specified."},"exemptUnder":{"type":"number","format":"double","description":"Line-item exemption threshold; amounts below this dollar value are exempt; null when not specified."},"expiresDt":{"type":"integer","format":"int64","description":"Date the rule expires, in YYYYMMDD format; null means the rule is still in effect."},"isDestinationTaxType":{"type":"boolean","description":"Whether the rule follows destination-based sourcing; null when not specified."},"isFoodDrug":{"type":"boolean","description":"Hint indicating the product falls under food/drug category classification; null when not specified."},"jurTaxCode":{"type":"string","description":"Code identifying the jurisdiction the rule applies to: a FIPS-like code (state, county, or city), or a conditional jurisdiction code of the form 36:XX-#### or 36:XX-L#### (NY ST-100.3 codes for location-resolved school district / city / county rules; the code is specific to the form part the TIC is sourced from); null when not specified."},"perVolumeTaxRate":{"type":"number","format":"double","description":"Per-volume tax rate for volume-based TIC overrides (e.g., $0.05/mL); null when not applicable."},"perVolumeUnit":{"type":"string","description":"Unit of measurement for perVolumeTaxRate (e.g., mL); null when not applicable."},"percentTaxable":{"type":"number","format":"double","description":"Fraction of the sale that is taxable (for example, 0.5 means half-exempt); null when not specified."},"rateCapPerUnit":{"type":"number","format":"double","description":"Maximum tax rate cap per unit for capped TIC overrides (e.g., $0.30/cigar); null when not applicable."},"taxablePortionOver":{"type":"number","format":"double","description":"Only the amount over this threshold is taxed; null when not specified."}},"title":"V60RateRule"},"type_ZIPTAX API:V60TaxabilityCode":{"type":"object","properties":{"countyFIPS":{"type":"string","description":"County FIPS code resolved for the request location."},"id":{"type":"string","description":"Taxability Information Code (TIC) supplied on the request."},"label":{"type":"string","description":"Longer description of the TIC."},"rateActionCode":{"$ref":"#/components/schemas/type_ZIPTAX API:V60TaxabilityCodeRateActionCode","description":"Outcome of the TIC lookup: T00 (valid TIC, rules listed), T01 (valid TIC, no applicable rate rules), T02 (invalid TIC), T03 (invalid TIC format)."},"rateActionMessage":{"type":"string","description":"Human-readable explanation of the rateActionCode."},"rateRules":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:V60RateRule"},"description":"Product rate rules that apply to this TIC in the resolved jurisdiction, filtered to rules active on the current date."},"stateFIPS":{"type":"string","description":"State FIPS code resolved for the request location."},"title":{"type":"string","description":"Short title of the TIC."}},"required":["countyFIPS","id","label","rateActionCode","rateActionMessage","stateFIPS","title"],"title":"V60TaxabilityCode"},"type_ZIPTAX API:V60ProductDetail":{"type":"object","properties":{"taxabilityCode":{"$ref":"#/components/schemas/type_ZIPTAX API:V60TaxabilityCode","description":"Resolved taxability code details and the product rate rules that apply in this jurisdiction."}},"required":["taxabilityCode"],"title":"V60ProductDetail"},"type_ZIPTAX API:V60ServiceTaxable":{"type":"string","enum":["Y","N","L"],"description":"Whether services/labor are taxable in this jurisdiction. 'Y' = the service is fully taxable and must be separately stated on the invoice; 'N' = the service is not taxable and must be separately stated on the invoice; 'L' = the service is not taxable, but the labor portion is taxable and both must be separately stated on the invoice.","title":"V60ServiceTaxable"},"type_ZIPTAX API:V60Service":{"type":"object","properties":{"adjustmentType":{"type":"string","description":"Service taxation classification. Currently always 'SERVICE_TAXABLE'."},"description":{"type":"string","description":"Human-readable explanation of the service taxability determination."},"taxable":{"$ref":"#/components/schemas/type_ZIPTAX API:V60ServiceTaxable","description":"Whether services/labor are taxable in this jurisdiction. 'Y' = the service is fully taxable and must be separately stated on the invoice; 'N' = the service is not taxable and must be separately stated on the invoice; 'L' = the service is not taxable, but the labor portion is taxable and both must be separately stated on the invoice."}},"required":["adjustmentType","description","taxable"],"title":"V60Service"},"type_ZIPTAX API:V60ShippingExtended":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable description of the shipping taxability rule."},"exemptWhenSeparatelyStated":{"type":"string","description":"Whether shipping is exempt when separately stated on the invoice, as the string 'true' or 'false'."},"rule":{"type":"string","description":"General shipping-taxability rule for the state: one of EXEMPT, EXEMPT_WHEN_SEPARATELY_STATED, ITEM_SPECIFIC, CONDITIONAL, or TAXABLE."},"stateCode":{"type":"string","description":"Two-letter state code the shipping rule applies to."},"stateName":{"type":"string","description":"Full state name the shipping rule applies to."}},"required":["description","exemptWhenSeparatelyStated","rule","stateCode","stateName"],"title":"V60ShippingExtended"},"type_ZIPTAX API:V60ShippingTaxable":{"type":"string","enum":["Y","N"],"description":"Whether freight/shipping is taxable in this jurisdiction. 'Y' = taxable, 'N' = not taxable.","title":"V60ShippingTaxable"},"type_ZIPTAX API:V60Shipping":{"type":"object","properties":{"adjustmentType":{"type":"string","description":"Freight taxation classification. Currently always 'FREIGHT_TAXABLE'."},"description":{"type":"string","description":"Human-readable explanation of the freight/shipping taxability determination."},"shippingExtended":{"$ref":"#/components/schemas/type_ZIPTAX API:V60ShippingExtended","description":"Extended state-level shipping rule detail. Present only when shippingExtended=true is supplied on the request."},"taxable":{"$ref":"#/components/schemas/type_ZIPTAX API:V60ShippingTaxable","description":"Whether freight/shipping is taxable in this jurisdiction. 'Y' = taxable, 'N' = not taxable."}},"required":["adjustmentType","description","taxable"],"title":"V60Shipping"},"type_ZIPTAX API:V60OriginDestinationValue":{"type":"string","enum":["O","D"],"description":"Sourcing basis for the location: 'O' = origin-based (ship-from rate), 'D' = destination-based (ship-to rate).","title":"V60OriginDestinationValue"},"type_ZIPTAX API:V60OriginDestination":{"type":"object","properties":{"adjustmentType":{"type":"string","description":"Sourcing ruleset name. Currently always 'ORIGIN_DESTINATION'."},"description":{"type":"string","description":"Human-readable description of the sourcing model applied (e.g. 'Destination Based Taxation')."},"value":{"$ref":"#/components/schemas/type_ZIPTAX API:V60OriginDestinationValue","description":"Sourcing basis for the location: 'O' = origin-based (ship-from rate), 'D' = destination-based (ship-to rate)."}},"required":["adjustmentType","description","value"],"title":"V60OriginDestination"},"type_ZIPTAX API:V60DisplayRate":{"type":"object","properties":{"name":{"type":"string","description":"Label for this display rate line (e.g. the jurisdiction name)."},"rate":{"type":"number","format":"double","description":"Rate for this display line, as a decimal fraction."}},"required":["name","rate"],"title":"V60DisplayRate"},"type_ZIPTAX API:V60TaxSummaryTaxType":{"type":"string","enum":["SALES_TAX","USE_TAX"],"description":"Tax kind this summary aggregates: 'SALES_TAX' or 'USE_TAX'.","title":"V60TaxSummaryTaxType"},"type_ZIPTAX API:V60TaxSummary":{"type":"object","properties":{"displayRates":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:V60DisplayRate"},"description":"Per-line rate breakdown displayed under this summary."},"rate":{"type":"number","format":"double","description":"Aggregated tax rate for this summary line, as a decimal fraction (e.g. 0.0775 = 7.75%)."},"summaryName":{"type":"string","description":"Human-readable name of the summary grouping (e.g. 'Sales Tax')."},"taxType":{"$ref":"#/components/schemas/type_ZIPTAX API:V60TaxSummaryTaxType","description":"Tax kind this summary aggregates: 'SALES_TAX' or 'USE_TAX'."}},"required":["rate","summaryName","taxType"],"title":"V60TaxSummary"},"type_ZIPTAX API:V60Response":{"type":"object","properties":{"addressDetail":{"$ref":"#/components/schemas/type_ZIPTAX API:V60AddressDetail","description":"Normalized and geocoded address details used for the lookup."},"baseRates":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:V60BaseRate"},"description":"Component tax rates broken out by jurisdiction level (state/county/city/district) and tax type (sales/use). Sum the relevant components to obtain a combined rate."},"metadata":{"$ref":"#/components/schemas/type_ZIPTAX API:V60Metadata","description":"Versioning and response-code metadata for the request."},"productDetail":{"$ref":"#/components/schemas/type_ZIPTAX API:V60ProductDetail","description":"Product-specific tax rules. Present only when a taxabilityCode is supplied on the request and the account carries the product_rates entitlement."},"service":{"$ref":"#/components/schemas/type_ZIPTAX API:V60Service","description":"Whether services/labor are taxable in the resolved jurisdiction."},"shipping":{"$ref":"#/components/schemas/type_ZIPTAX API:V60Shipping","description":"Whether freight/shipping is taxable in the resolved jurisdiction."},"sourcingRules":{"$ref":"#/components/schemas/type_ZIPTAX API:V60OriginDestination","description":"Sourcing model (origin- vs destination-based) that applies to the resolved location."},"taxSummaries":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:V60TaxSummary"},"description":"Aggregated sales and use tax rates for the location, summarizing the base rate components."}},"required":["addressDetail","metadata","service","shipping","sourcingRules"],"title":"V60Response"},"type_ZIPTAX API:ErrorDetail":{"type":"object","properties":{"location":{"type":"string","description":"Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'"},"message":{"type":"string","description":"Error message text"},"value":{"description":"The value at the given location"}},"title":"ErrorDetail"},"type_ZIPTAX API:ErrorModel":{"type":"object","properties":{"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:ErrorDetail"},"description":"List of individual error details"},"instance":{"type":"string","format":"uri","description":"A URI reference that identifies the specific occurrence of the problem."},"status":{"type":"integer","format":"int64","description":"HTTP status code"},"title":{"type":"string","description":"A short, human-readable summary of the problem type. This value should not change between occurrences of the error."},"type":{"type":"string","format":"uri","default":"about:blank","description":"A URI reference to human-readable documentation for the error."}},"title":"ErrorModel"},"type_ZIPTAX API:MetricsV60Response":{"type":"object","properties":{"is_active":{"type":"boolean","description":"Whether the account is currently active."},"message":{"type":"string","description":"Informational message about the account."},"request_count":{"type":"integer","format":"int64","description":"Number of requests consumed in the current period."},"request_limit":{"type":"integer","format":"int64","description":"Maximum requests allowed for the account in the current period."},"usage_percent":{"type":"number","format":"double","description":"Request usage as a percentage of the limit (0-100)."}},"required":["is_active","message","request_count","request_limit","usage_percent"],"title":"MetricsV60Response"},"type_ZIPTAX API/merchant:CreateMerchantRequestMerchantType":{"type":"string","enum":["taxcloud","self-managed"],"default":"taxcloud","description":"The merchant's compliance model, chosen once at creation. 'taxcloud' (the default) starts the TaxCloud invite process, so TaxCloud can handle registration, filing, and remittance for the merchant; creating one requires an Enterprise plan. 'self-managed' skips the invite entirely and the merchant is active as soon as the call returns, with the merchant remaining responsible for their own compliance.","title":"CreateMerchantRequestMerchantType"},"type_ZIPTAX API:CreateMerchantResponse":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID assigned to the newly created merchant; use it in subsequent merchant operations."},"message":{"type":"string","description":"Human-readable description of the result."},"status":{"type":"string","description":"Result status of the operation (e.g. 'success')."}},"required":["merchantId","message","status"],"title":"CreateMerchantResponse"},"type_ZIPTAX API/merchant:UpdateMerchantRequestSetMerchantType":{"type":"string","enum":["taxcloud","self-managed","connected","offline"],"description":"Switches the merchant to a different compliance model. Use 'taxcloud' to have TaxCloud handle the merchant's registration, filing, and remittance: their status becomes 'taxcloud_invited' and they are emailed an invite. Use 'self-managed' to hand compliance back to the merchant: their status becomes 'external_compliance' and their stored TaxCloud credentials are removed. 'connected' and 'offline' are deprecated names for 'taxcloud' and 'self-managed'. Sending the merchant's current model changes nothing. Omit this field to leave the compliance model as it is.","title":"UpdateMerchantRequestSetMerchantType"},"type_ZIPTAX API:UpdateStruct":{"type":"object","properties":{"contactEmail":{"type":"string","description":"Updated email address of the merchant's primary contact."},"contactFirst":{"type":"string","description":"Updated first name of the merchant's primary contact."},"contactLast":{"type":"string","description":"Updated last name of the merchant's primary contact."},"merchantName":{"type":"string","minLength":1,"maxLength":255,"description":"New legal or trading name of the merchant business. Required; must be 1–255 characters."},"referenceId":{"type":"string","maxLength":255,"description":"The ID you use in your own system to identify this merchant."}},"required":["merchantName"],"title":"UpdateStruct"},"type_ZIPTAX API:UpdateMerchantResponse":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the updated merchant."},"message":{"type":"string","description":"Human-readable description of the result."},"status":{"type":"string","description":"Result status of the operation (e.g. 'success')."}},"required":["merchantId","message","status"],"title":"UpdateMerchantResponse"},"type_ZIPTAX API:DeleteMerchantResponse":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the deleted merchant."},"message":{"type":"string","description":"Human-readable description of the result."},"status":{"type":"string","description":"Result status of the operation (e.g. 'success')."}},"required":["merchantId","message","status"],"title":"DeleteMerchantResponse"},"type_ZIPTAX API:GetMerchantResponseStatus":{"type":"string","enum":["taxcloud_invited","taxcloud_connected","taxcloud_disconnected","external_compliance"],"description":"Derived TaxCloud lifecycle status: 'taxcloud_invited' (invite sent, not yet accepted), 'taxcloud_connected' (TaxCloud credentials set and active), 'taxcloud_disconnected' (previously connected, now disconnected), or 'external_compliance' (managed outside TaxCloud).","title":"GetMerchantResponseStatus"},"type_ZIPTAX API:GetMerchantResponse":{"type":"object","properties":{"contactEmail":{"type":"string","description":"Email address of the merchant's primary contact."},"contactFirst":{"type":"string","description":"First name of the merchant's primary contact."},"contactLast":{"type":"string","description":"Last name of the merchant's primary contact."},"merchantId":{"type":"string","description":"UUID of the merchant."},"merchantName":{"type":"string","description":"Legal or trading name of the merchant business."},"referenceId":{"type":"string","description":"The ID you use in your own system to identify this merchant."},"status":{"$ref":"#/components/schemas/type_ZIPTAX API:GetMerchantResponseStatus","description":"Derived TaxCloud lifecycle status: 'taxcloud_invited' (invite sent, not yet accepted), 'taxcloud_connected' (TaxCloud credentials set and active), 'taxcloud_disconnected' (previously connected, now disconnected), or 'external_compliance' (managed outside TaxCloud)."}},"required":["merchantId","merchantName","status"],"title":"GetMerchantResponse"},"type_ZIPTAX API:ItemStatus":{"type":"string","enum":["taxcloud_invited","taxcloud_connected","taxcloud_disconnected","external_compliance"],"description":"Derived TaxCloud lifecycle status: 'taxcloud_invited' (invite sent, not yet accepted), 'taxcloud_connected' (TaxCloud credentials set and active), 'taxcloud_disconnected' (previously connected, now disconnected), or 'external_compliance' (managed outside TaxCloud).","title":"ItemStatus"},"type_ZIPTAX API:Item":{"type":"object","properties":{"contactEmail":{"type":"string","description":"Email address of the merchant's primary contact."},"contactFirst":{"type":"string","description":"First name of the merchant's primary contact."},"contactLast":{"type":"string","description":"Last name of the merchant's primary contact."},"merchantId":{"type":"string","description":"UUID of the merchant."},"merchantName":{"type":"string","description":"Legal or trading name of the merchant business."},"referenceId":{"type":"string","description":"The ID you use in your own system to identify this merchant."},"status":{"$ref":"#/components/schemas/type_ZIPTAX API:ItemStatus","description":"Derived TaxCloud lifecycle status: 'taxcloud_invited' (invite sent, not yet accepted), 'taxcloud_connected' (TaxCloud credentials set and active), 'taxcloud_disconnected' (previously connected, now disconnected), or 'external_compliance' (managed outside TaxCloud)."}},"required":["merchantId","merchantName","status"],"title":"Item"},"type_ZIPTAX API:SetMerchantCredentialsResponse":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the merchant whose credentials were set."},"message":{"type":"string","description":"Human-readable description of the result."},"status":{"type":"string","description":"Result status of the operation (e.g. 'success')."}},"required":["merchantId","message","status"],"title":"SetMerchantCredentialsResponse"},"type_ZIPTAX API:DeleteMerchantCredentialsResponse":{"type":"object","properties":{"merchantId":{"type":"string","description":"UUID of the merchant whose credentials were deleted."},"message":{"type":"string","description":"Human-readable description of the result."},"status":{"type":"string","description":"Result status of the operation (e.g. 'success')."}},"required":["merchantId","message","status"],"title":"DeleteMerchantCredentialsResponse"},"type_ZIPTAX API:NexusLocationInputLocationType":{"type":"string","enum":["office","store","warehouse","inventory_fba","employee","property","temporary"],"description":"What kind of presence this location represents. 'office', 'store', and 'warehouse' are premises you occupy; 'inventory_fba' covers inventory held in a third-party fulfilment network; 'employee' covers staff or contractors working in a state; 'property' covers inventory or equipment held there; 'temporary' covers short-term presence such as a trade show.","title":"NexusLocationInputLocationType"},"type_ZIPTAX API:NexusLocationInput":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":255,"description":"The location's street address as a single line. It is geocoded when you send it, and the normalized result is what every response returns, so the value you get back will usually differ from the one you sent. US addresses only. An address that cannot be resolved to a state is rejected with 422 rather than stored."},"isFulfillmentOrigin":{"type":"boolean","description":"Whether goods actually ship from this location. This is the field origin-sourcing consults, so set it explicitly for anything unusual, such as an office that also ships or a warehouse that does not. When omitted it defaults by locationType: true for 'warehouse', 'inventory_fba', and 'store'; false for the rest."},"locationType":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusLocationInputLocationType","description":"What kind of presence this location represents. 'office', 'store', and 'warehouse' are premises you occupy; 'inventory_fba' covers inventory held in a third-party fulfilment network; 'employee' covers staff or contractors working in a state; 'property' covers inventory or equipment held there; 'temporary' covers short-term presence such as a trade show."},"name":{"type":"string","maxLength":255,"description":"Your own label for this location. Shown back to you on every response and never used in a calculation."},"referenceId":{"type":"string","maxLength":255,"description":"The ID you use in your own system to identify this location."},"registered":{"type":"boolean","description":"Whether the merchant is registered to collect sales tax in this location's state. Defaults to false when omitted."}},"required":["address","locationType"],"title":"NexusLocationInput"},"type_ZIPTAX API:NexusLocationOutputLocationType":{"type":"string","enum":["office","store","warehouse","inventory_fba","employee","property","temporary"],"description":"What kind of presence this location represents.","title":"NexusLocationOutputLocationType"},"type_ZIPTAX API:NexusLocationOutput":{"type":"object","properties":{"address":{"type":"string","description":"The normalized address resolved when the location was written, not the string you sent."},"isFulfillmentOrigin":{"type":"boolean","description":"Whether goods ship from this location."},"locationId":{"type":"string","description":"Server-issued identifier for this location. Use it with /merchant/nexus/update and /merchant/nexus/delete."},"locationType":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusLocationOutputLocationType","description":"What kind of presence this location represents."},"name":{"type":"string","description":"Your own label for this location. Empty when none was supplied."},"referenceId":{"type":"string","description":"The ID you use in your own system to identify this location. Empty when none was supplied."},"registered":{"type":"boolean","description":"Whether the merchant is registered to collect sales tax in this location's state."}},"required":["address","isFulfillmentOrigin","locationId","locationType","name","referenceId","registered"],"title":"NexusLocationOutput"},"type_ZIPTAX API:MerchantNexusCreateResponse":{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusLocationOutput"},"description":"The stored locations, in the order submitted, each with its server-issued locationId and normalized address."},"merchantId":{"type":"string","description":"UUID of the merchant the locations were recorded for."}},"required":["merchantId"],"title":"MerchantNexusCreateResponse"},"type_ZIPTAX API/merchantNexus:MerchantNexusListRequestNexusType":{"type":"string","enum":["physical","economic"],"description":"Restricts the response to one kind of nexus. Omit it to return every kind. Only 'physical' is supported; 'economic' is rejected with 400, because those rows carry a registration id instead of an address and do not fit this response shape (ZIP-1214).","title":"MerchantNexusListRequestNexusType"},"type_ZIPTAX API:MerchantNexusListResponse":{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusLocationOutput"},"description":"The merchant's recorded locations. An empty array when the merchant has none, which means no physical nexus is being tracked for them."},"merchantId":{"type":"string","description":"UUID of the merchant the locations belong to."}},"required":["merchantId"],"title":"MerchantNexusListResponse"},"type_ZIPTAX API:MerchantNexusUpdateResponse":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusLocationOutput","description":"The stored location after the update, with its normalized address."},"merchantId":{"type":"string","description":"UUID of the merchant the location belongs to."}},"required":["location","merchantId"],"title":"MerchantNexusUpdateResponse"},"type_ZIPTAX API:MerchantNexusDeleteResponse":{"type":"object","properties":{"locationId":{"type":"string","description":"Identifier of the removed location."},"merchantId":{"type":"string","description":"UUID of the merchant the location belonged to."},"message":{"type":"string","description":"Human-readable description of the result."}},"required":["locationId","merchantId","message"],"title":"MerchantNexusDeleteResponse"},"type_ZIPTAX API:TaxCloudCurrencyCurrencyCode":{"type":"string","enum":["USD","CAD"],"default":"USD","description":"ISO 4217 currency code the line-item prices are denominated in. USD or CAD. Defaults to USD when omitted.","title":"TaxCloudCurrencyCurrencyCode"},"type_ZIPTAX API:TaxCloudCurrency":{"type":"object","properties":{"currencyCode":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCurrencyCurrencyCode","default":"USD","description":"ISO 4217 currency code the line-item prices are denominated in. USD or CAD. Defaults to USD when omitted."}},"title":"TaxCloudCurrency"},"type_ZIPTAX API:TaxCloudAddressCountryCode":{"type":"string","enum":["US","CA"],"default":"US","description":"ISO 3166-1 alpha-2 country code of the address. US (United States) or CA (Canada). Defaults to US when omitted.","title":"TaxCloudAddressCountryCode"},"type_ZIPTAX API:TaxCloudAddress":{"type":"object","properties":{"city":{"type":"string","minLength":1,"maxLength":50,"description":"City or post-town of the address."},"countryCode":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddressCountryCode","default":"US","description":"ISO 3166-1 alpha-2 country code of the address. US (United States) or CA (Canada). Defaults to US when omitted."},"line1":{"type":"string","minLength":1,"maxLength":128,"description":"First line of the address: street number and name, PO Box, or building. Values longer than 50 characters are automatically truncated by TaxCloud."},"line2":{"type":"string","maxLength":128,"description":"Second line of the address, if any (e.g. apartment, suite, or unit number). Values longer than 50 characters are automatically truncated by TaxCloud."},"state":{"type":"string","minLength":1,"maxLength":32,"description":"State, province, or other large territorial division, as a two-letter abbreviation (e.g. MN, CA, ON)."},"zip":{"type":"string","minLength":1,"maxLength":16,"description":"Postal or ZIP code. Five-digit (55401) and ZIP+4 (55401-2427) formats are accepted for US addresses."}},"required":["city","line1","state","zip"],"title":"TaxCloudAddress"},"type_ZIPTAX API:TaxCloudLineItemDiscountType":{"type":"string","enum":["percentage","amount"],"description":"The kind of discount: 'percentage' (a fraction of the price) or 'amount' (a fixed currency amount).","title":"TaxCloudLineItemDiscountType"},"type_ZIPTAX API:TaxCloudLineItemDiscount":{"type":"object","properties":{"itemId":{"type":"string","description":"The itemId of the line item this discount applies to. Must match an itemId in the lineItems array."},"type":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudLineItemDiscountType","description":"The kind of discount: 'percentage' (a fraction of the price) or 'amount' (a fixed currency amount)."},"value":{"type":"number","format":"double","minimum":0,"description":"The discount value: a decimal fraction between 0 and 1 for 'percentage' (e.g. 0.1 = 10% off), or a currency amount for 'amount'. When discounts are provided, line-item prices must be pre-discount (original) prices."}},"required":["itemId","type","value"],"title":"TaxCloudLineItemDiscount"},"type_ZIPTAX API:TaxCloudOrderLevelDiscountType":{"type":"string","enum":["percentage","amount"],"description":"The kind of discount: 'percentage' (a fraction of the order total) or 'amount' (a fixed currency amount).","title":"TaxCloudOrderLevelDiscountType"},"type_ZIPTAX API:TaxCloudOrderLevelDiscount":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudOrderLevelDiscountType","description":"The kind of discount: 'percentage' (a fraction of the order total) or 'amount' (a fixed currency amount)."},"value":{"type":"number","format":"double","minimum":0,"description":"The discount value: a decimal fraction between 0 and 1 for 'percentage', or a currency amount for 'amount'. When discounts are provided, line-item prices must be pre-discount (original) prices."}},"required":["type","value"],"title":"TaxCloudOrderLevelDiscount"},"type_ZIPTAX API:TaxCloudDiscounts":{"type":"object","properties":{"lineItemDiscounts":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudLineItemDiscount"},"description":"Discounts applied to specific line items, applied before any order-level discount. Each entry must reference a valid itemId from the lineItems array."},"orderDiscount":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudOrderLevelDiscount","description":"A discount applied to the entire order, applied after line-item discounts. Shipping items (TICs 11010-11015) and Colorado retail delivery fees (TIC 11098) are excluded from order-level discount calculations."}},"title":"TaxCloudDiscounts"},"type_ZIPTAX API:TaxCloudExemption":{"type":"object","properties":{"exemptionId":{"type":"string","description":"Identifier of an exemption certificate previously created for the customer (see /merchant/cert/create). When provided, the customer is treated as exempt and the certificate is associated with the transaction."},"isExempt":{"type":"boolean","description":"Whether the customer is exempt from sales tax. Assumed true when exemptionId is provided."}},"title":"TaxCloudExemption"},"type_ZIPTAX API:TaxCloudCartItem":{"type":"object","properties":{"index":{"type":"integer","format":"int64","description":"Zero-based position of the item within the cart. Each line item must have a unique index."},"itemId":{"type":"string","minLength":1,"maxLength":50,"description":"Your unique identifier for the line item (e.g. SKU or line reference). Used to match line items in later order, refund, and discount operations."},"price":{"type":"number","format":"double","minimum":0,"description":"Unit price of the item, in the cart's currency. When discounts are provided, this must be the pre-discount (original) price; tax is calculated on the discounted amount. Self-managed merchants only: both the unit price and the extended price (price * quantity) must be at most 1e12."},"productId":{"type":"string","description":"Unique ID of the product in the merchant's TaxCloud product catalog (e.g. SKU). Must match an existing catalog product when provided."},"quantity":{"type":"number","format":"double","minimum":0,"maximum":99999.9999,"description":"Quantity of the item. Fractional quantities are allowed. For quantities above the maximum, send a single line with quantity 1 and the extended (total) amount as the price."},"tic":{"type":"integer","format":"int64","description":"Taxability Information Code (TIC) classifying the product for product-specific tax rules (e.g. 11010 for shipping). Defaults to 0 (general tangible goods) when omitted."}},"required":["index","itemId","price","quantity"],"title":"TaxCloudCartItem"},"type_ZIPTAX API:TaxCloudCart":{"type":"object","properties":{"cartId":{"type":"string","minLength":1,"maxLength":50,"description":"Your identifier for this cart. If omitted, TaxCloud generates one and returns it in the response; either way, pass it to /merchant/order/create-from-cart to capture the cart as an order."},"currency":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCurrency","description":"The currency the line-item prices are denominated in."},"customerId":{"type":"string","minLength":1,"maxLength":50,"description":"Your identifier for the customer in your own system. Used to match exemption certificates and order history."},"deliveredBySeller":{"type":"boolean","description":"Whether the seller delivers the order directly (own vehicles) rather than via common carrier. Affects taxability of delivery charges in some states."},"destination":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-to (destination) address of the sale. Tax is generally calculated for this address in destination-sourced states."},"discounts":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudDiscounts","description":"Line-item and order-level discounts to apply. If omitted, prices are used as is."},"exemption":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudExemption","description":"Exemption information for the customer. When the customer is exempt, calculated tax is zero for exempt jurisdictions."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCartItem"},"description":"The line items in the cart. Tax is calculated per item and returned per item in the response."},"origin":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-from (origin) address of the sale. Used together with destination to determine sourcing and the applicable jurisdictions."}},"required":["currency","customerId","destination","lineItems","origin"],"title":"TaxCloudCart"},"type_ZIPTAX API:TaxCloudTax":{"type":"object","properties":{"amount":{"type":"number","format":"double","description":"The calculated tax amount for the line item, in the transaction currency."},"rate":{"type":"number","format":"double","description":"The combined tax rate applied to the line item, as a decimal fraction (e.g. 0.08125 = 8.125%)."}},"required":["amount","rate"],"title":"TaxCloudTax"},"type_ZIPTAX API:TaxCloudCartItemWithTaxResponse":{"type":"object","properties":{"index":{"type":"integer","format":"int64","description":"Zero-based position of the item within the cart or order."},"itemId":{"type":"string","description":"Your unique identifier for the line item, as submitted."},"originalPrice":{"type":"number","format":"double","description":"The original (pre-discount) unit price, as submitted."},"price":{"type":"number","format":"double","description":"The unit price tax was calculated on. When discounts were applied, this is the discounted unit price."},"quantity":{"type":"number","format":"double","description":"Quantity of the item."},"tax":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudTax","description":"The tax rate and amount calculated for this line item."},"tic":{"type":"integer","format":"int64","description":"Taxability Information Code (TIC) the item was calculated under. Null when no TIC applies."}},"required":["index","itemId","originalPrice","price","quantity","tax"],"title":"TaxCloudCartItemWithTaxResponse"},"type_ZIPTAX API:TaxCloudCartResponse":{"type":"object","properties":{"cartId":{"type":"string","description":"Identifier of the calculated cart. Pass this to /merchant/order/create-from-cart to capture the cart as an order."},"currency":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCurrency","description":"The currency the prices and tax amounts are denominated in."},"customerId":{"type":"string","description":"Your identifier for the customer, as submitted."},"deliveredBySeller":{"type":"boolean","description":"Whether the seller delivers the order directly, as submitted (false when omitted)."},"destination":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-to (destination) address, as submitted."},"exemption":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudExemption","description":"The exemption information applied to the calculation."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCartItemWithTaxResponse"},"description":"The submitted line items, each with its calculated tax rate and amount."},"origin":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-from (origin) address, as submitted."}},"required":["cartId","currency","customerId","deliveredBySeller","destination","exemption","origin"],"title":"TaxCloudCartResponse"},"type_ZIPTAX API:CartCalculateResponseBody":{"type":"object","properties":{"connectionId":{"type":"string","description":"The TaxCloud connection the calculation ran under."},"items":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCartResponse"},"description":"One calculated cart per submitted cart, in the same order, with per-line-item tax rates and amounts."},"transactionDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the carts were calculated for."}},"required":["connectionId"],"title":"CartCalculateResponseBody"},"type_ZIPTAX API:SelfManagedCartItemWithTaxResponse":{"type":"object","properties":{"index":{"type":"integer","format":"int64","description":"Zero-based position of the item within the cart, as submitted."},"itemId":{"type":"string","description":"Your unique identifier for the line item, as submitted."},"originalPrice":{"type":"number","format":"double","description":"The original unit price. Always equal to price, because discounts are not supported for self-managed merchants."},"price":{"type":"number","format":"double","description":"The unit price tax was calculated on, as submitted. Discounts are not supported for self-managed merchants, so this is always the submitted price."},"quantity":{"type":"number","format":"double","description":"Quantity of the item, as submitted."},"tax":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudTax","description":"The tax rate and amount calculated for this line item. The amount is money and is rounded to two decimal places, the same precision a TaxCloud-connected cart returns; the rate keeps five decimal places."},"tic":{"type":"integer","format":"int64","description":"Taxability Information Code (TIC) the item was calculated under, as submitted. Null when no TIC was supplied (general tangible goods)."}},"required":["index","itemId","originalPrice","price","quantity","tax"],"title":"SelfManagedCartItemWithTaxResponse"},"type_ZIPTAX API:SelfManagedCartResponse":{"type":"object","properties":{"cartId":{"type":"string","description":"Identifier of the calculated cart: the cartId you submitted, or a generated one when you omitted it. Self-managed calculations are not persisted, so this identifier is for correlating the response with the request only and cannot be used with /merchant/order/create-from-cart."},"currency":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCurrency","description":"The currency the prices and tax amounts are denominated in. Always USD for self-managed merchants."},"customerId":{"type":"string","description":"Your identifier for the customer, as submitted."},"destination":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-to (destination) address, as submitted."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:SelfManagedCartItemWithTaxResponse"},"description":"The submitted line items, each with its calculated tax rate and amount."},"origin":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-from (origin) address, as submitted."}},"required":["cartId","currency","customerId","destination","origin"],"title":"SelfManagedCartResponse"},"type_ZIPTAX API:SelfManagedCartCalculateResponseBody":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:SelfManagedCartResponse"},"description":"One calculated cart per submitted cart, in the same order, with per-line-item tax rates and amounts."}},"title":"SelfManagedCartCalculateResponseBody"},"type_ZIPTAX API/merchantTaxCloud:MerchantCartCalculateResponse":{"oneOf":[{"$ref":"#/components/schemas/type_ZIPTAX API:CartCalculateResponseBody"},{"$ref":"#/components/schemas/type_ZIPTAX API:SelfManagedCartCalculateResponseBody"}],"title":"MerchantCartCalculateResponse"},"type_ZIPTAX API/merchantTaxCloud:MerchantOrderCreateFromCartRequestKind":{"type":"string","enum":["order","credit"],"default":"order","description":"The kind of order to create: 'order' for a sale (default) or 'credit' for a credit order.","title":"MerchantOrderCreateFromCartRequestKind"},"type_ZIPTAX API:TaxCloudOrderResponseKind":{"type":"string","enum":["order","credit"],"description":"The kind of order: 'order' for a sale or 'credit' for a credit order.","title":"TaxCloudOrderResponseKind"},"type_ZIPTAX API:TaxCloudRefundTax":{"type":"object","properties":{"amount":{"type":"number","format":"double","description":"The tax amount refunded for the item, calculated proportionally from the order's tax. When the order had discounts, this reflects tax on the discounted price."}},"required":["amount"],"title":"TaxCloudRefundTax"},"type_ZIPTAX API:TaxCloudRefundItemResponse":{"type":"object","properties":{"index":{"type":"integer","format":"int64","description":"Zero-based position of the item within the refund."},"itemId":{"type":"string","description":"The itemId of the refunded line item, matching the original order."},"price":{"type":"number","format":"double","description":"The unit price refunded, calculated automatically from the order. When the order had discounts, this reflects the discounted amount actually paid."},"quantity":{"type":"number","format":"double","description":"The quantity refunded."},"tax":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudRefundTax","description":"The tax amount refunded for this line item."},"tic":{"type":"integer","format":"int64","description":"Taxability Information Code (TIC) of the refunded item."}},"required":["index","itemId","price","quantity"],"title":"TaxCloudRefundItemResponse"},"type_ZIPTAX API:TaxCloudRefundResponse":{"type":"object","properties":{"batchId":{"type":"string","description":"Batch ID grouping this refund with related refunds, if one was supplied."},"connectionId":{"type":"string","description":"The TaxCloud connection the refund was recorded under."},"createdDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the refund was created."},"items":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudRefundItemResponse"},"description":"The refunded line items, each with the refunded price, quantity, and tax amount."},"returnedDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the refund took effect."}},"required":["connectionId"],"title":"TaxCloudRefundResponse"},"type_ZIPTAX API:TaxCloudOrderResponse":{"type":"object","properties":{"batchId":{"type":"string","description":"Batch ID grouping this order with related orders, if one was supplied."},"channel":{"type":"string","description":"The sales channel the order came from (e.g. amazon, ebay, walmart). Null when no channel was recorded."},"completedDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the order was shipped/completed on, creating the tax liability. Absent for orders that are not yet completed."},"connectionId":{"type":"string","description":"The TaxCloud connection the order was recorded under."},"currency":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCurrency","description":"The currency the prices and tax amounts are denominated in."},"customerId":{"type":"string","description":"Your identifier for the customer in your own system."},"deliveredBySeller":{"type":"boolean","description":"Whether the seller delivered the order directly."},"destination":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-to (destination) address of the order."},"excludeFromFiling":{"type":"boolean","description":"Whether the order is excluded from tax filing."},"exemption":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudExemption","description":"The exemption information recorded on the order."},"kind":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudOrderResponseKind","description":"The kind of order: 'order' for a sale or 'credit' for a credit order."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCartItemWithTaxResponse"},"description":"The order's line items, each with its tax rate and amount."},"orderId":{"type":"string","description":"Your identifier for the order in your own system."},"origin":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"The ship-from (origin) address of the order."},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudRefundResponse"},"description":"Refunds recorded against this order. Only included when the request set expand to 'refunds'."},"transactionDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the order was purchased on."}},"required":["channel","connectionId","currency","customerId","deliveredBySeller","destination","excludeFromFiling","exemption","kind","orderId","origin"],"title":"TaxCloudOrderResponse"},"type_ZIPTAX API/merchantTaxCloud:MerchantOrderCreateRequestKind":{"type":"string","enum":["order","credit"],"default":"order","description":"The kind of order: 'order' for a sale (default) or 'credit' for a credit order.","title":"MerchantOrderCreateRequestKind"},"type_ZIPTAX API:TaxCloudCartItemWithTax":{"type":"object","properties":{"index":{"type":"integer","format":"int64","description":"Zero-based position of the item within the order. Each line item must have a unique index."},"itemId":{"type":"string","minLength":1,"maxLength":50,"description":"Your unique identifier for the line item (e.g. SKU or line reference). Referenced by refunds and discounts."},"price":{"type":"number","format":"double","minimum":0,"description":"Unit price of the item that tax was calculated on, in the order's currency."},"productId":{"type":"string","description":"Unique ID of the product in the merchant's TaxCloud product catalog. Must match an existing catalog product when provided."},"quantity":{"type":"number","format":"double","minimum":0,"maximum":99999.9999,"description":"Quantity of the item. Fractional quantities are allowed. For quantities above the maximum, send a single line with quantity 1 and the extended (total) amount as the price."},"tax":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudTax","description":"The tax rate and amount collected for this line item. Required when creating an order directly (the amounts were computed by your checkout)."},"tic":{"type":"integer","format":"int64","description":"Taxability Information Code (TIC) classifying the product for product-specific tax rules. Defaults to 0 (general tangible goods) when omitted."}},"required":["index","itemId","price","quantity","tax"],"title":"TaxCloudCartItemWithTax"},"type_ZIPTAX API/merchantTaxCloud:MerchantCertCreateRequestCustomerBusinessType":{"type":"string","enum":["AccommodationAndFoodServices","AgriculturalForestryFishingHunting","Construction","FinanceAndInsurance","InformationPublishingAndCommunications","Manufacturing","Mining","RealEstate","RentalAndLeasing","RetailTrade","TransportationAndWarehousing","Utilities","WholesaleTrade","BusinessServices","ProfessionalServices","EducationAndHealthCareServices","NonprofitOrganization","Government","NotABusiness","Other"],"description":"The type of business the customer is.","title":"MerchantCertCreateRequestCustomerBusinessType"},"type_ZIPTAX API/merchantTaxCloud:MerchantCertCreateRequestReason":{"type":"string","enum":["FederalGovernment","StateOrLocalGovernment","TribalGovernment","ForeignDiplomat","CharitableOrganization","EducationalOrganization","Resale","AgriculturalProduction","IndustrialProductionOrManufacturing","DirectPayPermit","DirectMail","Other","ReligiousOrganization"],"description":"The reason the customer is exempt from sales tax.","title":"MerchantCertCreateRequestReason"},"type_ZIPTAX API:TaxCloudExemptState":{"type":"object","properties":{"abbreviation":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter abbreviation of a state the exemption certificate is valid in."}},"required":["abbreviation"],"title":"TaxCloudExemptState"},"type_ZIPTAX API:TaxCloudCertResponse":{"type":"object","properties":{"accountId":{"type":"integer","format":"int64","description":"The TaxCloud account id the certificate belongs to."},"address":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudAddress","description":"Address of the exempt customer."},"certificateId":{"type":"string","description":"TaxCloud's identifier for the exemption certificate. Use it with /merchant/cert/get, /merchant/cert/delete, and as exemptionId on carts and orders."},"connectionId":{"type":"string","description":"The TaxCloud connection the certificate belongs to."},"createdDate":{"type":"string","format":"date-time","description":"RFC3339 datetime the certificate was created."},"customerBusinessDescription":{"type":"string","description":"Free-text description of the business, present when customerBusinessType is Other."},"customerBusinessType":{"type":"string","description":"The type of business the customer is (e.g. RetailTrade, Government, NonprofitOrganization)."},"customerId":{"type":"string","description":"Your identifier for the exempt customer."},"customerName":{"type":"string","description":"Name of the customer the certificate was issued to."},"disabledAt":{"type":"string","format":"date-time","description":"RFC3339 datetime the certificate was disabled, or null while it is active."},"reason":{"type":"string","description":"The reason the customer is exempt (e.g. Resale, FederalGovernment, CharitableOrganization)."},"reasonDescription":{"type":"string","description":"Free-text elaboration of the exemption reason."},"singlePurchase":{"type":"boolean","description":"Whether the certificate covers a single purchase only, rather than being a blanket certificate."},"states":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudExemptState"},"description":"The states the certificate is valid in."}},"required":["accountId","address","certificateId","connectionId","createdDate","customerBusinessType","customerId","customerName","reason","reasonDescription","singlePurchase"],"title":"TaxCloudCertResponse"},"type_ZIPTAX API/merchantTaxCloud:MerchantCertListRequestSortBy":{"type":"string","enum":["createdDate","id"],"default":"id","description":"The field to sort results by: 'createdDate' or 'id'. Defaults to 'id'.","title":"MerchantCertListRequestSortBy"},"type_ZIPTAX API:TaxCloudCertListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TaxCloudCertResponse"},"description":"The exemption certificates on this page of results."},"limit":{"type":"integer","format":"int64","description":"The maximum number of results per page that was applied."},"nextCursor":{"type":"string","description":"Opaque cursor to pass as 'cursor' on the next call to fetch the following page. Null when there are no further results."}},"required":["limit","nextCursor"],"title":"TaxCloudCertListResponse"},"type_ZIPTAX API:RefundItem":{"type":"object","properties":{"itemId":{"type":"string","minLength":1,"maxLength":50,"description":"The itemId of the line item to refund. Must match an itemId from the original order."},"quantity":{"type":"number","format":"double","minimum":0,"maximum":99999.9999,"description":"The quantity of the item to refund. May be fractional and must not exceed the quantity on the original order."}},"required":["itemId","quantity"],"title":"RefundItem"},"type_ZIPTAX API/data:GetTicDataRequestFormat":{"type":"string","enum":["json","xml"],"default":"json","description":"Serialization format of the response body: 'json' (default) or 'xml'.","title":"GetTicDataRequestFormat"},"type_ZIPTAX API:TicData":{"type":"object","properties":{"id":{"type":"string","description":"Taxability Information Code (TIC) identifier (numeric string)."},"label":{"type":"string","description":"Longer, localized description of what the TIC category covers."},"nl_label":{"type":"string","description":"Non-localized (base English) description of the TIC category, independent of locale."},"nl_title":{"type":"string","description":"Non-localized (base English) title of the TIC category, independent of locale."},"parent":{"type":"string","description":"TIC code of this code's parent category in the TIC hierarchy; empty for top-level categories."},"title":{"type":"string","description":"Short, localized human-readable title of the TIC category."}},"required":["id","label","nl_label","nl_title","parent","title"],"title":"TicData"},"type_ZIPTAX API:TicEntry":{"type":"object","properties":{"tic":{"$ref":"#/components/schemas/type_ZIPTAX API:TicData","description":"A single TIC record."}},"required":["tic"],"title":"TicEntry"},"type_ZIPTAX API:TicResponse":{"type":"object","properties":{"tic_list":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TicEntry"},"description":"Full list of Taxability Information Codes (TICs) available to the account."}},"title":"TicResponse"},"type_ZIPTAX API:TicSearchResult":{"type":"object","properties":{"label":{"type":"string","description":"Descriptive label for the TIC, when available"},"name":{"type":"string","description":"Human-readable label for the matched TIC"},"tic":{"type":"string","description":"Matched Taxability Information Code (TIC)"}},"required":["name","tic"],"title":"TicSearchResult"},"type_ZIPTAX API:TicSearchResponse":{"type":"object","properties":{"$schema":{"type":"string","format":"uri","description":"URL to the JSON Schema for this response"},"nextCursor":{"type":"string","description":"Cursor for retrieving the next page of results"},"query":{"type":"string","description":"Echo of the input query"},"results":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TicSearchResult"},"description":"Ranked TIC results (most relevant first)"}},"required":["$schema","query"],"title":"TicSearchResponse"},"type_ZIPTAX API:TicRecommendPredictionStatus":{"type":"string","enum":["success","fail"],"description":"Prediction status","title":"TicRecommendPredictionStatus"},"type_ZIPTAX API:TicRecommendPrediction":{"type":"object","properties":{"error":{"type":"string","description":"Error string formatted as \"<code> - <message>\" on failure; null on success"},"label":{"type":"string","description":"Label for the recommended TIC"},"naturalLabel":{"type":"string","description":"Natural-language label for the recommended TIC"},"product_description":{"type":"string","description":"Normalized product description used for matching"},"status":{"$ref":"#/components/schemas/type_ZIPTAX API:TicRecommendPredictionStatus","description":"Prediction status"},"ticId":{"type":"integer","format":"int64","description":"Recommended Taxability Information Code (TIC)"},"tic_description":{"type":"string","description":"Description of the recommended TIC"}},"required":["status"],"title":"TicRecommendPrediction"},"type_ZIPTAX API:TicRecommendResponse":{"type":"object","properties":{"predictions":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:TicRecommendPrediction"},"description":"Recommended TIC predictions"}},"title":"TicRecommendResponse"},"type_ZIPTAX API:HealthComponentsDynamo":{"type":"string","enum":["ok","config_error","connection_error"],"description":"DynamoDB connectivity status: 'ok', 'config_error' (AWS config could not be loaded), or 'connection_error' (table could not be described).","title":"HealthComponentsDynamo"},"type_ZIPTAX API:HealthComponentsTaxdata":{"type":"string","enum":["ok","empty","partial"],"description":"Tax-data cache status: 'ok', 'empty' (cache not loaded), or 'partial' (fewer than the expected number of records loaded).","title":"HealthComponentsTaxdata"},"type_ZIPTAX API:HealthComponents":{"type":"object","properties":{"dynamo":{"$ref":"#/components/schemas/type_ZIPTAX API:HealthComponentsDynamo","description":"DynamoDB connectivity status: 'ok', 'config_error' (AWS config could not be loaded), or 'connection_error' (table could not be described)."},"taxdata":{"$ref":"#/components/schemas/type_ZIPTAX API:HealthComponentsTaxdata","description":"Tax-data cache status: 'ok', 'empty' (cache not loaded), or 'partial' (fewer than the expected number of records loaded)."},"taxdata_count":{"type":"integer","format":"int64","description":"Number of tax-data records currently loaded in the in-memory cache."}},"required":["dynamo","taxdata","taxdata_count"],"title":"HealthComponents"},"type_ZIPTAX API:HealthResponse":{"type":"object","properties":{"components":{"$ref":"#/components/schemas/type_ZIPTAX API:HealthComponents","description":"Per-component health detail."},"status":{"type":"string","description":"Overall health of the API. Always 'ok' on a served response; component-level detail is in the components object."}},"required":["components","status"],"title":"HealthResponse"},"type_ZIPTAX API:MetadataResponse":{"type":"object","properties":{"go_version":{"type":"string","description":"Go runtime version the running binary was built with."},"hostname":{"type":"string","description":"Opaque identifier for the instance serving the request. Stable for the life of that instance and changes when it restarts. Useful for telling support which instance handled a request; it is not a resolvable hostname."}},"required":["go_version","hostname"],"title":"MetadataResponse"},"type_ZIPTAX API:NexusThresholdOutputIncludableSales":{"type":"string","enum":["gross-sales","retail-sales","taxable-sales","gross-receipts","none"],"description":"Which sales count toward the threshold. 'none' for a state with no general statewide sales tax.","title":"NexusThresholdOutputIncludableSales"},"type_ZIPTAX API:NexusThresholdOutputMarketplace":{"type":"string","enum":["included","excluded","none"],"description":"Whether sales made through a marketplace facilitator count toward the threshold. 'none' for a state with no general statewide sales tax.","title":"NexusThresholdOutputMarketplace"},"type_ZIPTAX API:NexusThresholdOutputRule":{"type":"string","enum":["either-threshold","both-required","sales-only"],"description":"How the two thresholds combine. 'either-threshold': meeting either one establishes nexus. 'both-required': both must be met. 'sales-only': there is no transaction test.","title":"NexusThresholdOutputRule"},"type_ZIPTAX API:NexusThresholdOutput":{"type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-3 code of the country this jurisdiction belongs to."},"includableSales":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusThresholdOutputIncludableSales","description":"Which sales count toward the threshold. 'none' for a state with no general statewide sales tax."},"includableSalesDetail":{"type":"string","description":"The source wording behind includableSales, carrying qualifiers the enum cannot: California, Georgia, and Missouri count tangible personal property only, and Connecticut names retail sales of both property and services. Empty for a state with no general statewide sales tax."},"marketplace":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusThresholdOutputMarketplace","description":"Whether sales made through a marketplace facilitator count toward the threshold. 'none' for a state with no general statewide sales tax."},"noSalesTax":{"type":"boolean","description":"True for the states with no general statewide sales tax: Delaware, Montana, New Hampshire, and Oregon. They are returned rather than omitted so a caller iterating states does not read a missing row as missing data."},"period":{"type":"string","description":"The window the threshold is measured over, in the source's own words. Prose rather than a code because the periods genuinely differ per state, from a calendar year to a rolling twelve months to the previous four sales tax quarters. Empty for a state with no general statewide sales tax."},"rule":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusThresholdOutputRule","description":"How the two thresholds combine. 'either-threshold': meeting either one establishes nexus. 'both-required': both must be met. 'sales-only': there is no transaction test."},"stateCode":{"type":"string","description":"Two-letter jurisdiction code. US states plus DC and PR."},"thresholdSales":{"type":"integer","format":"int64","description":"Sales volume, in whole US dollars, that establishes economic nexus. Null for a state with no general statewide sales tax."},"thresholdTransactions":{"type":"integer","format":"int64","description":"Number of separate transactions that establishes economic nexus. Null when the state has no transaction test, which is increasingly common: several states have repealed theirs."}},"required":["countryCode","includableSales","includableSalesDetail","marketplace","noSalesTax","period","rule","stateCode"],"title":"NexusThresholdOutput"},"type_ZIPTAX API:NexusThresholdListResponse":{"type":"object","properties":{"thresholds":{"type":"array","items":{"$ref":"#/components/schemas/type_ZIPTAX API:NexusThresholdOutput"},"description":"The matching thresholds, ordered by state code."}},"title":"NexusThresholdListResponse"}},"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-KEY"}}}}