> This page is for version v6.0 (default). > For other versions, use one of these documentation indexes: > - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt > - v5.0: https://docs.zip.tax/v-5-0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.zip.tax/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server. # Special Rules Some product categories carry taxes that don't fit the standard rate breakdown. A restaurant meal can owe a local meals tax on top of sales tax, or a state meals rate that replaces sales tax entirely. Ziptax reports these in `productDetail.taxabilityCode.specialRules`, next to the TIC's [`rateRules`](taxability-information-codes). `specialRules` is the container for every rule of this kind. Each rule type has its own field inside it and its own section on this page. Meal tax is the first. The `specialRules` object is present only when one of its rule types applies to the TIC you sent. ## Meal tax ### When meal tax appears Send `taxabilityCode=41000` or `taxabilityCode=41041` (prepared food) on a `GET /request/v60` call. No other request parameter is needed. The response then carries `productDetail.taxabilityCode.specialRules.mealTax`. Any other TIC gets no `mealTax` object. Meal tax is reported on its own. It never changes `baseRates`, `taxSummaries`, or `rateRules`. The `SALES_TAX` total in `taxSummaries` is still the ordinary sales tax rate at the location, and you combine the two yourself (see [How to calculate meal tax](#how-to-calculate-meal-tax)). ### Response fields `mealTax` has three fields: | Field | Type | Meaning | | ------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `combinedMealRate` | number or `null` | Sum of the rates of the unconditional components in `rules`, as a decimal. It is not the total tax rate. `null` when no unconditional component applies. | | `reasonCodes` | array of strings or `null` | Qualifications of the result. See [Reason codes](#reason-codes). | | `rules` | array or `null` | The meal-tax components that apply at the location, widest jurisdiction first. Empty when none apply. | Each entry in `rules` is one component: | Field | Type | Meaning | | ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `jurisdictionType` | string | Level of the levying jurisdiction, such as `STATE`, `COUNTY`, `INDEPENDENT_CITY`, `MUNICIPALITY`, or `SPECIAL_DISTRICT`. | | `jurisdictionName` | string | Name of the levying jurisdiction. | | `jurisdictionCode` | string | Geography code the location matched: a state FIPS code, a state + county FIPS code, a 7-digit Census place GEOID, or a 10-digit Census county subdivision GEOID (Massachusetts and Vermont towns, which aren't Census places). | | `taxName` | string | Name of the tax program. | | `componentType` | string | `ADD_ON`, `STATE_SPECIAL_TOTAL`, or `OCCUPATION_TAX`. Decides how the component combines with sales tax. See [How to calculate meal tax](#how-to-calculate-meal-tax). | | `rate` | number | Component rate as a decimal (`0.01` = 1%). | | `replacesStateRate` | boolean | `true` exactly when `componentType` is `STATE_SPECIAL_TOTAL`. Despite the name, such a component replaces the whole ordinary sales tax, state and local. | | `effectiveDt` | integer or `null` | First day the component applies, as a `YYYYMMDD` number (`20180101`). `null` when the start date isn't recorded. | | `expiresDt` | integer or `null` | Last day the component applies, as a `YYYYMMDD` number. `null` when open-ended. | | `sourcingBasis` | string | Where the component is sourced. Independent of the lookup's `sourcingRules`. See [Sourcing](#sourcing). | | `conditional` | boolean | Always present. `true` when the component applies only to some sales at the location. | | `conditionCode` | string or `null` | Machine-readable reason the component is conditional, such as `LIVE_PERFORMANCE`. An open set: new codes may be added. `null` when `conditional` is `false`. | | `conditionDescription` | string or `null` | Plain-language description of the condition. `null` when `conditional` is `false`. | > **Info** > > `conditional`, `conditionCode`, and `conditionDescription` are being > added to the API and may not appear in responses yet. Unlike `rateRules`, whose dates are strings, `effectiveDt` and `expiresDt` on a meal-tax component are integers. ### How to calculate meal tax Start from the ordinary sales tax rate, the `SALES_TAX` total in `taxSummaries`. Each component's `componentType` decides how it adjusts that rate: * **`ADD_ON`**: added on top of the ordinary sales tax rate. It is not grossed up. * **`STATE_SPECIAL_TOTAL`**: replaces the whole ordinary sales tax, state and local, whether the meals rate is higher or lower than the ordinary rate. Connecticut, the District of Columbia, Maine, New Hampshire, and Vermont use this type. `replacesStateRate` is `true` exactly for these components. * **`OCCUPATION_TAX`**: a levy on the seller. It is added on its own and also enters the sales tax base, so sales tax is charged on it. Put together, the meal rate is: ```text rate = occupation + sales × (1 + occupation) + addOns ``` where: * `sales` is the ordinary `SALES_TAX` total, or the `STATE_SPECIAL_TOTAL` rate when one applies. * `occupation` is the sum of the `OCCUPATION_TAX` rates (0 when there are none). * `addOns` is the sum of the `ADD_ON` rates. **Example: Vermont.** The ordinary sales tax rate at a Vermont location with a local option tax is 7%. Its meal-tax rules are the 9% state meals tax (`STATE_SPECIAL_TOTAL`) and a 1% local meals tax (`ADD_ON`). The 9% replaces the whole 7%, so the meal rate is 9% + 1% = **10%**, not 7% + 9% + 1%. **Example: an occupation tax.** Omaha, Nebraska levies a 2.5% restaurant occupation tax (`OCCUPATION_TAX`). Assuming, for illustration only, an ordinary sales tax rate of 7%, the meal rate is 0.025 + 0.07 × (1 + 0.025) = 0.09675, or **9.675%**. Use the `SALES_TAX` total from your own lookup in place of the assumed 7%. > **Warning** > > `combinedMealRate` is the sum of the meal-tax components only. It is not > the total tax rate. Don't add it to the `SALES_TAX` total when a > `STATE_SPECIAL_TOTAL` component is present, because that component > replaces the ordinary sales tax instead of adding to it. Conditional components are listed in `rules` but not counted in `combinedMealRate`. When any component has `conditional: true`, decide from its `conditionCode` and `conditionDescription` whether it applies to the sale, and sum the components you apply yourself rather than relying on `combinedMealRate`. Ziptax's cart endpoints, [`/calculate/cart`](../merchant-compliance-solutions/cart) and [`/merchant/cart/calculate`](../merchant-compliance-solutions/self-managed-cart-calculation), apply meal tax to a 41000 or 41041 line this way and skip conditional components. ### Sourcing Sourcing only matters for deliveries, or for orders that cross a jurisdiction line. A meal sold and eaten on the premises is taxed where the sale happens, whatever `sourcingBasis` says. For other sales, `sourcingBasis` says which location a component follows: | Value | Located at | Meaning | | ----------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------- | | `SELLER_LOCATION` | Origin | Follows the seller's location. | | `SELLER_LOCATION_WITH_CATERING_EXCEPTION` | Origin | The seller's location, except catering, which follows the jurisdiction served (Indiana). | | `SELLER_LOCATION_REVIEW_DELIVERY` | Origin | The seller's location for on-site sales. Delivery treatment is not yet confirmed (Mississippi). | | `SOLD_OR_SERVED_LOCATION` | Origin | Where the meal is sold or served (Louisiana). | | `EVENT_LOCATION` | Origin | Where the event takes place (Mississippi catered sales). | | `DESTINATION` | Destination | Where meals are provided or delivered (Vermont). | | `CUSTOMER_RECEIPT_LOCATION` | Destination | Where the customer receives the meal (Wisconsin). | | `STATE_TAX_SOURCING` | Cart's sourcing | Follows the state's ordinary sales tax sourcing. | | `MEAL_SALE_SOURCING` | Cart's sourcing | A local meals excise sourced with the meal sale (Massachusetts). | | `STATEWIDE_EATING_ESTABLISHMENT_SALES` | Cart's sourcing | A statewide levy on eating-establishment sales (Rhode Island). | | `REVIEW_REQUIRED` | Cart's sourcing | The rate is on file but its sourcing is not yet confirmed. Says nothing about the rate itself. | "Cart's sourcing" means the address the cart is sourced at: the origin or the destination, as the lookup's `sourcingRules` says. An interstate cart reads only the destination, so a component located at the origin is dropped. New values may be added. Treat a value you don't recognize as the cart's sourcing. ### Reason codes `reasonCodes` qualifies the result. Check it before reading an empty `rules` array as "no meal tax". | Code | Meaning | What to do | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LOCATION_NOT_RESOLVED` | The location's state could not be resolved, so meal tax was not evaluated. An empty `rules` array is not a finding of no meal tax. | Retry with a full address or a lat/lng pair. | | `RULES_NOT_LOADED` | Meal-tax data is unavailable on the server. This is not a finding of no meal tax. | Retry later. | | `STATE_NOT_COVERED` | Ziptax has no meal-tax rules on file for the state. This is not a finding that the state has none. | Confirm the state's meal tax treatment from another source. | | `UNMAPPED_SCOPES_IN_STATE` | At least one meal-tax district in the state has no mapped boundary. The code is set per state, not per location: every lookup in that state gets it, whatever the address. Today this applies to Illinois, Indiana, Louisiana, Minnesota, Mississippi, and South Dakota. | Apply the returned rules. Treat the result as possibly incomplete only if the location being rated (for a cart, the address the component would be sourced at) could be inside one of the state's unmapped districts, such as Chicago's MPEA district, Downtown Naperville, the Minneapolis downtown taxing area, or Giants Ridge. | ### Worked example: Minneapolis A lookup for a downtown Minneapolis address with TIC 41000: #### cURL ```bash curl -G -H "X-API-KEY: $ZIPTAX_API_KEY" \ "https://api.zip-tax.com/request/v60" \ --data-urlencode "address=350 S 5th St, Minneapolis, MN 55415" \ --data-urlencode "taxabilityCode=41000" ``` `rules` holds one component, Minneapolis's 3% entertainment tax: `componentType` `ADD_ON`, `rate` `0.03`, `sourcingBasis` `REVIEW_REQUIRED`. It applies only to some sales, so it has `conditional: true`, `conditionCode: "LIVE_PERFORMANCE"`, and `conditionDescription` "Applies only to food and drinks sold in public places during live performances." It is the only rule matched in Minneapolis, and it is conditional, so `combinedMealRate` is `null`. For a sale in a public place during a live performance, add 3% to the ordinary `SALES_TAX` total. Otherwise, the meal is taxed at the ordinary rate. `reasonCodes` includes `UNMAPPED_SCOPES_IN_STATE` because the Minneapolis downtown restaurant tax district has no mapped boundary. A seller inside that district may owe a tax this result doesn't list. ## Related #### [Taxability Information Codes](taxability-information-codes) Attach a TIC to a rate request and read its `rateRules`. #### [Cart Tax Calculation](../merchant-compliance-solutions/cart) Quote a cart with meal tax applied per line. #### [By Address](../rest-api/by-address) Address lookups, sourcing rules, and the full response.