Tweak - Match TaxJar cache entries across cart and order paths (WOOTAX-258) (#2983)

* WOOTAX-258: match TaxJar cache entries across cart and order paths

The transient cache key was an md5 of the raw request body, so two requests
that would receive the same answer from TaxJar routinely missed each other.

Two causes, fixed separately:

* The line item `id` was built from WooCommerce's cart item key on the cart
  path and from the numeric order item ID on the order path, so the same
  basket produced two different bodies. Both paths now derive `id` from the
  tax-relevant inputs alone (product, tax code, quantity, unit price,
  discount, tax location), with an occurrence counter to keep genuinely
  identical lines distinct. The product ID stays the first `-` segment,
  which get_itemized_tax_rates() and the rate-override hooks rely on.

* The key was byte-sensitive, so a differently-cased city, a stray double
  space or "5" vs "5.00" split the cache. The key now comes from a canonical
  projection of the body: whitespace and case folded, amounts given one
  representation, key order fixed, line items sorted. Numeric normalization
  is applied by field name so a leading-zero ZIP is never reinterpreted.

The body sent to TaxJar is unchanged apart from `id`, which TaxJar treats as
an opaque echo field.

* WOOTAX-258: address PR review — @SInCE stamps and cache-hit coverage

Review follow-ups on #2983:

- The five new private cache-key helpers were stamped `@since 3.4.0`; the
  release in progress is 3.6.10.

- `calculate_backend_totals()` passes the order-item-ID-keyed map from
  `get_backend_line_items()` straight into `calculate_tax()` without going
  through `group_items_by_location()`, so `array_values()` is the only thing
  keeping `line_items` a JSON array rather than an object on every admin-side
  request. The one existing `calculate_tax()` test returns at the cross-state
  guard and never reaches it. Adds a test that captures the encoded body and
  asserts a zero-indexed list, checking the raw JSON as well as the decoded
  array since `json_decode()` hides the array/object distinction.

- `smartcalcs_cache_request()` had no coverage at all: the existing tests
  compare `get_cache_signature()` outputs in isolation, verifying the
  ingredients but never the result. Adds a test that counts
  `smartcalcs_request()` invocations across two equivalent-but-byte-different
  bodies and asserts one HTTP call plus a populated signature transient. It
  asserts specifically on `tj_tax_<md5(signature)>` and on the *absence* of the
  `tj_tax_<zip>_<state>` key, which only ever caches 400 zip-to-state
  mismatches and would otherwise mask a broken signature.

Both new tests were verified to fail against mutated guards.

* update since docs

* Chore: Renumber unreleased release from 3.7.0 to 3.6.12.

The pending TaxJar response-cache work is retargeted from the 3.7.0 minor
to the 3.6.x patch line. Update the unreleased changelog and readme
headings, and move the five @SInCE stamps on the new cache-normalization
helpers so they document the version that will actually ship.

* Fix - Re-key the non-taxable record onto canonical TaxJar line item ids.

get_line_items() and get_backend_line_items() record exempt lines under the
context-specific `<product_id>-<cart_item_key>` / `<product_id>-<order_item_id>`
id, but assign_canonical_line_item_ids() then rewrites each line item's id to
`<product_id>-<fingerprint>-<occurrence>`, and that canonical id is what TaxJar
echoes back. get_itemized_tax_rates() looks the record up by the echoed id, so
the two key shapes could never match: the guard never fired and the 0% breakdown
line of a non-taxable product overwrote the shared Standard-class rate row.

That silently reverted the unreleased 3.6.12 fix for mixed taxable/non-taxable
carts. Both call sites now move the record onto the canonical ids, restoring the
invariant the property docblock already states ("Keyed by TaxJar line item id").

Applies @Abdalsalaam's review suggestions on #2983 verbatim, at both call sites.

Also updates three tests that indexed get_line_items()'s return positionally.
This PR keys that array by cart item key (and the backend one by order item ID)
and pins it in test_get_line_items_is_keyed_by_cart_item_key, so the tests now
take the single element rather than element zero.

Full suite: 399 tests, 975 assertions, green.

---------

Co-authored-by: Iyut <iyut85@yahoo.com>

Author: bartech

changelog.txt

@@ -14,6 +14,7 @@
 * Fix   - Calculate tax correctly for carts mixing taxable and non-taxable products, so a non-taxable product no longer resets the standard tax rate to zero.
 * Tweak - Centralize TaxJar address handling in an internal value object. No change to tax calculation.
 * Tweak - Store tax rate rows against the postcode the rate was quoted for when the address postcode holds more than one comma-separated value.
+* Tweak - Reduce redundant TaxJar API calls by matching cached tax responses across the cart and order paths and ignoring irrelevant formatting differences.
 
 = 3.6.11 - 2026-08-05 =
 * Fix   - Prevent a fatal error during cart and checkout tax calculation when TaxJar returns an incomplete tax response.

classes/class-wc-connect-taxjar-integration.php

@@ -617,9 +617,11 @@ public function calculate_totals( $wc_cart_object ) {
 		}
 
 		foreach ( $wc_cart_object->get_cart() as $cart_item_key => $cart_item ) {
-			$product       = $cart_item['data'];
-			$line_item_key = $product->get_id() . '-' . $cart_item_key;
-			if ( isset( $taxes['line_items'][ $line_item_key ] ) && ! $taxes['line_items'][ $line_item_key ]->combined_tax_rate ) {
+			$product = $cart_item['data'];
+			// get_line_items() keys by cart item key and stores the canonical TaxJar ID
+			// under 'id'; the response is keyed by that canonical ID.
+			$line_item_key = $line_items[ $cart_item_key ]['id'] ?? null;
+			if ( null !== $line_item_key && isset( $taxes['line_items'][ $line_item_key ] ) && ! $taxes['line_items'][ $line_item_key ]->combined_tax_rate ) {
 				if ( method_exists( $product, 'set_tax_status' ) ) {
 					$product->set_tax_status( 'none' ); // Woo 3.0+
 				} else {
@@ -680,9 +682,10 @@ public function calculate_backend_totals( $order_id ) {
 			 * @var WC_Order_Item_Product $item Product Order Item.
 			 */
 			foreach ( $order->get_items() as $item_key => $item ) {
-				$product_id    = $item->get_product_id();
-				$line_item_key = $product_id . '-' . $item_key;
-				if ( isset( $taxes['rate_ids'][ $line_item_key ] ) ) {
+				// get_backend_line_items() keys by order item ID and stores the canonical
+				// TaxJar ID under 'id'; the response is keyed by that canonical ID.
+				$line_item_key = $line_items[ $item_key ]['id'] ?? null;
+				if ( null !== $line_item_key && isset( $taxes['rate_ids'][ $line_item_key ] ) ) {
 					$rate_id  = $taxes['rate_ids'][ $line_item_key ];
 					$item_tax = new WC_Order_Item_Tax();
 					$item_tax->set_rate( $rate_id );
@@ -967,10 +970,13 @@ protected function get_backend_address() {
 	/**
 	 * Get line items at checkout
 	 *
-	 * Unchanged from the TaxJar plugin.
+	 * Based on the TaxJar plugin, with canonical line item IDs added.
 	 * See: https://github.com/taxjar/taxjar-woocommerce-plugin/blob/96b5d57/includes/class-wc-taxjar-integration.php#L645
 	 *
-	 * @return array
+	 * @param WC_Cart $wc_cart_object Cart object.
+	 *
+	 * @return array Line items keyed by cart item key. Each item's 'id' is the
+	 *               canonical TaxJar line item ID, not the cart item key.
 	 */
 	protected function get_line_items( $wc_cart_object ) {
 		$line_items                   = array();
@@ -1049,29 +1055,42 @@ protected function get_line_items( $wc_cart_object ) {
 				$this->_log( 'Tax location override for product ' . $id . ': ' . $default_location . ' -> ' . $tax_location );
 			}
 
-			array_push(
-				$line_items,
-				array(
-					'id'               => $id . '-' . $cart_item_key,
-					'quantity'         => $quantity,
-					'product_tax_code' => $tax_code,
-					'unit_price'       => $unit_price,
-					'discount'         => $discount,
-					'tax_location'     => $tax_location,
-				)
+			$line_items[ $cart_item_key ] = array(
+				'id'               => $id,
+				'quantity'         => $quantity,
+				'product_tax_code' => $tax_code,
+				'unit_price'       => $unit_price,
+				'discount'         => $discount,
+				'tax_location'     => $tax_location,
 			);
 		}
 
+		$line_items = $this->assign_canonical_line_item_ids( $line_items );
+
+		// The exempt record was keyed while ids were still context-specific; move it onto
+		// the canonical ids, which is what get_itemized_tax_rates() looks up.
+		$non_taxable = array();
+		foreach ( array_keys( $this->non_taxable_line_items ) as $legacy_key ) {
+			$item_key = substr( $legacy_key, (int) strpos( $legacy_key, '-' ) + 1 );
+			if ( isset( $line_items[ $item_key ] ) ) {
+				$non_taxable[ $line_items[ $item_key ]['id'] ] = true;
+			}
+		}
+		$this->non_taxable_line_items = $non_taxable;
+
 		return $line_items;
 	}
 
 	/**
 	 * Get line items for backend orders
 	 *
-	 * Unchanged from the TaxJar plugin.
+	 * Based on the TaxJar plugin, with canonical line item IDs added.
 	 * See: https://github.com/taxjar/taxjar-woocommerce-plugin/blob/96b5d57/includes/class-wc-taxjar-integration.php#L695
 	 *
-	 * @return array
+	 * @param WC_Order $order Order object.
+	 *
+	 * @return array Line items keyed by order item ID. Each item's 'id' is the
+	 *               canonical TaxJar line item ID, not the order item ID.
 	 */
 	protected function get_backend_line_items( $order ) {
 		$line_items                   = array();
@@ -1120,19 +1139,30 @@ protected function get_backend_line_items( $order ) {
 			}
 
 			if ( $unit_price ) {
-				array_push(
-					$line_items,
-					array(
-						'id'               => $id . '-' . $item_key,
-						'quantity'         => $quantity,
-						'product_tax_code' => $tax_code,
-						'unit_price'       => $unit_price,
-						'discount'         => $discount,
-						'tax_location'     => $tax_location,
-					)
+				$line_items[ $item_key ] = array(
+					'id'               => $id,
+					'quantity'         => $quantity,
+					'product_tax_code' => $tax_code,
+					'unit_price'       => $unit_price,
+					'discount'         => $discount,
+					'tax_location'     => $tax_location,
 				);
 			}
 		}
+
+		$line_items = $this->assign_canonical_line_item_ids( $line_items );
+
+		// The exempt record was keyed while ids were still context-specific; move it onto
+		// the canonical ids, which is what get_itemized_tax_rates() looks up.
+		$non_taxable = array();
+		foreach ( array_keys( $this->non_taxable_line_items ) as $legacy_key ) {
+			$item_key = substr( $legacy_key, (int) strpos( $legacy_key, '-' ) + 1 );
+			if ( isset( $line_items[ $item_key ] ) ) {
+				$non_taxable[ $line_items[ $item_key ]['id'] ] = true;
+			}
+		}
+		$this->non_taxable_line_items = $non_taxable;
+
 		return $line_items;
 	}
 
@@ -1145,6 +1175,195 @@ protected function get_line_item( $id, $line_items ) {
 		return null;
 	}
 
+	/**
+	 * Replace each line item's product ID with a canonical TaxJar line item ID.
+	 *
+	 * The cart path used to key line items by WooCommerce's cart item key and the
+	 * order path by the numeric order item ID, so the same basket produced two
+	 * different request bodies — and therefore two different cache keys — depending
+	 * on which path built it. TaxJar treats `id` as an opaque echo field, so the two
+	 * paths can agree on one value derived purely from the tax-relevant inputs:
+	 * product, tax code, quantity, unit price, discount and tax location.
+	 *
+	 * Format is `<product_id>-<fingerprint>-<occurrence>`. The product ID stays the
+	 * first `-` segment because `get_itemized_tax_rates()` recovers the product from
+	 * it, and `override_cart_item_tax_rates()` / `override_order_item_taxes()` match
+	 * on the `<product_id>-` prefix. The occurrence counter keeps two otherwise
+	 * identical lines — an order can legitimately hold the same product twice at the
+	 * same price — distinct, so neither loses its rate.
+	 *
+	 * @since 3.6.12
+	 *
+	 * @param array $line_items Line items whose 'id' is currently the bare product ID.
+	 *
+	 * @return array The same array with 'id' expanded to the canonical ID.
+	 */
+	private function assign_canonical_line_item_ids( array $line_items ): array {
+		$occurrences = array();
+
+		foreach ( $line_items as $key => $line_item ) {
+			$product_id = $line_item['id'];
+
+			$fingerprint = hash(
+				'md5',
+				(string) wp_json_encode(
+					array(
+						'product_id'       => (string) $product_id,
+						'product_tax_code' => $this->normalize_cache_string( $line_item['product_tax_code'] ),
+						'quantity'         => $this->normalize_cache_number( $line_item['quantity'] ),
+						'unit_price'       => $this->normalize_cache_number( $line_item['unit_price'] ),
+						'discount'         => $this->normalize_cache_number( $line_item['discount'] ),
+						'tax_location'     => $this->normalize_cache_string( $line_item['tax_location'] ),
+					)
+				)
+			);
+
+			$occurrences[ $fingerprint ] = isset( $occurrences[ $fingerprint ] ) ? $occurrences[ $fingerprint ] + 1 : 0;
+
+			$line_items[ $key ]['id'] = $product_id . '-' . substr( $fingerprint, 0, 12 ) . '-' . $occurrences[ $fingerprint ];
+		}
+
+		return $line_items;
+	}
+
+	/**
+	 * Normalize a string for cache-key purposes.
+	 *
+	 * Trims, collapses runs of whitespace and upper-cases, so that "beverly hills",
+	 * "Beverly  Hills" and "Beverly Hills " all hash the same. Used only to derive
+	 * cache keys and line item fingerprints — never to build the request sent to
+	 * TaxJar, which keeps the merchant's values verbatim.
+	 *
+	 * @since 3.6.12
+	 *
+	 * @param mixed $value Value to normalize.
+	 *
+	 * @return string
+	 */
+	private function normalize_cache_string( $value ): string {
+		if ( is_bool( $value ) ) {
+			$value = $value ? '1' : '0';
+		}
+
+		if ( ! is_scalar( $value ) && null !== $value ) {
+			return '';
+		}
+
+		$value = preg_replace( '/\s+/u', ' ', trim( (string) $value ) );
+
+		return function_exists( 'mb_strtoupper' ) ? mb_strtoupper( $value, 'UTF-8' ) : strtoupper( $value );
+	}
+
+	/**
+	 * Normalize a numeric value for cache-key purposes.
+	 *
+	 * Amounts reach the request body as `wc_format_decimal()` strings with varying
+	 * precision, so 5, "5" and "5.00" are the same money but three different bytes.
+	 * Collapses them to one representation. Non-numeric input is left to
+	 * normalize_cache_string() so a value that is not really a number cannot be
+	 * silently reinterpreted — notably ZIP codes, where "01234" must never become
+	 * "1234".
+	 *
+	 * @since 3.6.12
+	 *
+	 * @param mixed $value Value to normalize.
+	 *
+	 * @return string
+	 */
+	private function normalize_cache_number( $value ): string {
+		if ( ! is_numeric( $value ) ) {
+			return $this->normalize_cache_string( $value );
+		}
+
+		$normalized = number_format( (float) $value, 6, '.', '' );
+
+		if ( false !== strpos( $normalized, '.' ) ) {
+			$normalized = rtrim( rtrim( $normalized, '0' ), '.' );
+		}
+
+		// rtrim() eats the whole string for 0.000000, and -0 is still 0.
+		if ( '' === $normalized || '-' === $normalized || '-0' === $normalized ) {
+			$normalized = '0';
+		}
+
+		return $normalized;
+	}
+
+	/**
+	 * Build the cache signature for a TaxJar request body.
+	 *
+	 * Hashing the raw JSON makes the cache byte-sensitive: a differently-cased city,
+	 * a stray double space in a street address or "5" versus "5.00" for the same
+	 * price all miss a cache entry that would have answered correctly. This projects
+	 * the body onto a canonical form first — whitespace and case folded, amounts
+	 * given one representation, key order fixed, line items sorted — so equivalent
+	 * requests share one entry.
+	 *
+	 * Only the cache key is derived from this. The body sent to TaxJar is untouched.
+	 *
+	 * @since 3.6.12
+	 *
+	 * @param string $json Encoded TaxJar request body.
+	 *
+	 * @return string Canonical signature, or the input unchanged if it will not decode.
+	 */
+	private function get_cache_signature( $json ): string {
+		$body = json_decode( (string) $json, true );
+
+		if ( ! is_array( $body ) ) {
+			return (string) $json;
+		}
+
+		return (string) wp_json_encode( $this->canonicalize_cache_payload( $body ) );
+	}
+
+	/**
+	 * Recursively canonicalize a request body for cache-key derivation.
+	 *
+	 * Numeric normalization is applied by field name rather than by looking at the
+	 * value, because several address fields hold digit-only strings that must keep
+	 * their exact form (a leading-zero ZIP above all).
+	 *
+	 * @since 3.6.12
+	 *
+	 * @param mixed  $value Value to canonicalize.
+	 * @param string $key   Key the value was found under.
+	 *
+	 * @return mixed
+	 */
+	private function canonicalize_cache_payload( $value, $key = '' ) {
+		$numeric_fields = array( 'amount', 'shipping', 'quantity', 'unit_price', 'discount' );
+
+		if ( is_array( $value ) ) {
+			$canonical = array();
+
+			foreach ( $value as $child_key => $child_value ) {
+				$canonical[ $child_key ] = $this->canonicalize_cache_payload( $child_value, (string) $child_key );
+			}
+
+			if ( wp_is_numeric_array( $canonical ) ) {
+				// Lists (line items, nexus addresses) carry no meaning in their order,
+				// so sort them to keep the signature independent of how they were built.
+				usort(
+					$canonical,
+					function ( $first, $second ) {
+						return strcmp( (string) wp_json_encode( $first ), (string) wp_json_encode( $second ) );
+					}
+				);
+			} else {
+				ksort( $canonical );
+			}
+
+			return $canonical;
+		}
+
+		if ( in_array( $key, $numeric_fields, true ) ) {
+			return $this->normalize_cache_number( $value );
+		}
+
+		return $this->normalize_cache_string( $value );
+	}
+
 	/**
 	 * Override tax rates for individual cart items.
 	 *
@@ -1173,7 +1392,7 @@ public function override_cart_item_tax_rates( $item_tax_rates, $item, $cart ) {
 		$product_id = $product->get_id();
 
 		// Find the matching line_item_key in response_rate_ids.
-		// Format is "product_id-cart_item_key". The trailing "-" delimiter prevents
+		// Format is "product_id-fingerprint-occurrence". The trailing "-" delimiter prevents
 		// false prefix matches (e.g. product ID 1 won't match "10-xyz" because "1-" != "10").
 		// First-match-wins is safe: if the same product ID appears multiple times (e.g.
 		// two bookings), they share the same tax_location and thus the same tax rates.
@@ -1240,7 +1459,7 @@ public function override_order_item_taxes( $item, $calculate_tax_for ) {
 			return;
 		}
 
-		// Find matching rate_ids by product_id prefix (format: "product_id-cart_item_key").
+		// Find matching rate_ids by product_id prefix (format: "product_id-fingerprint-occurrence").
 		// The trailing "-" delimiter prevents false prefix matches between IDs (e.g. 1 vs 10).
 		// First-match-wins is safe: same product always shares the same tax_location and rates.
 		$matching_rate_ids = null;
@@ -1709,7 +1928,9 @@ public function calculate_tax( $options = array() ) {
 		if ( empty( $line_items ) ) {
 			$body['amount'] = 0.01;
 		} else {
-			$body['line_items'] = $line_items;
+			// Line items arrive keyed by cart item key / order item ID; TaxJar expects a
+			// JSON array, and a string-keyed PHP array would encode as an object.
+			$body['line_items'] = array_values( $line_items );
 		}
 
 		$response = $this->smartcalcs_cache_request( wp_json_encode( $body ), $from_state );
@@ -2113,7 +2334,8 @@ public function validate_taxjar_request( $json ) {
 	/**
 	 * Wrap SmartCalcs API requests in a transient-based caching layer.
 	 *
-	 * Unchanged from the TaxJar plugin.
+	 * Based on the TaxJar plugin. The cache key is derived from a canonical
+	 * projection of the body rather than its raw bytes — see get_cache_signature().
 	 * See: https://github.com/taxjar/taxjar-woocommerce-plugin/blob/4b481f5/includes/class-wc-taxjar-integration.php#L451
 	 *
 	 * @param $json
@@ -2122,7 +2344,7 @@ public function validate_taxjar_request( $json ) {
 	 * @return mixed|WP_Error
 	 */
 	public function smartcalcs_cache_request( $json, $from_state ) {
-		$cache_key           = 'tj_tax_' . hash( 'md5', $json );
+		$cache_key           = 'tj_tax_' . hash( 'md5', $this->get_cache_signature( $json ) );
 		$zip_state_cache_key = false;
 		$request             = json_decode( $json );
 		$to_zip              = isset( $request->to_zip ) ? (string) $request->to_zip : false;