Cart and Checkout Validation docs: localized field error target shown in three different forms (plural example silently blocks checkout)

Functions
1

API and version: Cart and Checkout Validation Function API, 2026-07 (same content on the 2026-10 page)

Summary

The documentation shows three different paths for a localized field error target:

Location Target shown
Validation Function API, “Supported checkout field targets” table $.cart.localizedfield.key
Validation Function API, JavaScript and Rust examples for required localized fields $.cart.localizedFields.${field.key}
Checkout UI extensions, Localized Fields API $.cart.localizedField.${taxIdField.key}

Only $.cart.localizedField.<KEY> (singular, camelCase, uppercase key) renders. With the plural path used in the Function examples, checkout is blocked and no message is shown anywhere.

Observed (29 July 2026, development store, API 2026-07)

  • $.cart.localizedFields.TAX_CREDENTIAL_IT: order blocked, no message. Same result with one-page and three-page checkout, with the order confirmation step on and off, and with a plain ASCII message.
  • $.cart.localizedField.TAX_CREDENTIAL_IT: message rendered under the field.

On 30 July 2026 Shopify Developer Support confirmed the singular form, called the silent drop a platform bug and said they were raising a docs correction. As of 13 September 2026 the table and both examples still show these forms.

Expected

Copying the official example renders the error under the field.

Requests

  1. Use $.cart.localizedField.<KEY> in the table and in every example, ideally with a real key such as TAX_CREDENTIAL_IT.
  2. Report an unrecognized target during development (CLI, function replay or run log) instead of discarding the error silently.

Impact

An app that follows the official example ships a validation that blocks checkout without telling the buyer what to fix.

2

Hi @max2348, thanks for the detailed report - I had a look and you’re spot on. Use $.cart.localizedField.TAX_CREDENTIAL_IT. It’s singular, camelCase, with the key in uppercase exactly as it appears in the input.

On your second request, an unrecognized target currently blocks checkout without any message, and nothing in the tooling flags the wrong path at development time. Surfacing that (CLI output, function replay or run log) is certainly reasonable and I’ve passed it along as feedback with the docs correction. I’ll let you know here in the thread once I have info to share - thanks again!

3

Thanks Donal, really appreciate you checking and confirming this.

We’re already using $.cart.localizedField. for both CF and PEC, so this confirms our implementation. One distinction that would be useful to make explicit in the docs is that the input collection is localizedFields (plural), while the error target uses localizedField (singular).

Thanks also for passing along the diagnostics feedback. A development-time warning would help prevent this from reaching a merchant’s live checkout, where the buyer gets blocked without knowing what to correct.