See all services → Shopify Plus Partner
API Developer

Show Every Function Settings Error in One Save Attempt

Shopify admin now surfaces every validation error from a function settings extension at once. Merchants configuring discounts or checkout rules see all of the problems after a single save instead of fixing fields one at a time.

Executive summary

What changed

Previously, when an extension onSubmit handler rejected the promise passed to event.waitUntil(), the admin displayed a single message taken from that error. A merchant with four misconfigured fields learned about one of them, corrected it, saved again, and then met the next. The handler can now reject with an AggregateError, and the admin reads the message of each Error in its errors list.

The admin shows up to ten errors, trims each message to 300 characters, and collapses duplicate messages to one line. Each entry can carry a code string, and the onError handler receives the same entries with their codes, so the extension can mark the matching fields in its own interface. An entry with no code, an empty code, or a code longer than 64 characters falls back to a default: UNKNOWN on discount pages and EXTENSION_ERROR on checkout rule pages. Rejecting with a single Error behaves exactly as before. The onerror property of s-function-settings is now typed as the AggregateError it receives in the 2025-10, 2026-10, and 2027-01 release candidate versions of the UI extensions package.

Why it matters

Nothing breaks if you ignore this, and that is the right way to read it: the change removes friction rather than adding capability. The friction was real, though. Discount and checkout rule configuration on Plus stores usually involves several interdependent fields: minimum quantities, tiered percentages, market scoping, customer segment conditions. Serial error reporting turns a two minute configuration task into a ten minute one, and every failed save is an opportunity for a merchandiser to abandon the task and hand it to a developer instead.

For teams that maintain custom discount logic, this is the class of refinement that shows up in support ticket volume rather than in a feature list. If you are weighing how much promotional logic to push into functions, our notes on complex discount logic at enterprise scale cover the trade-offs.

Role-specific impact

Use-case example

Real-world scenario

A specialty retailer runs a volume discount app built in house. Its function settings extension exposes six fields per tier, and the merchandising team configures roughly forty tiered promotions each quarter. Before this change, a typical first save surfaced one error, and the team averaged 3.4 saves per promotion to reach a valid state. Batching the failures into a single AggregateError with per field codes brought that down to 1.6 saves, recovering close to four hours of merchandising time per quarter.

Implementation checklist

  1. Confirm your function settings extension targets API version 2025-10 or later and is built with Polaris web components.
  2. Update the UI extensions package to 2025-10, 2026-10, or the 2027-01 release candidate so onerror carries the AggregateError type.
  3. Refactor onSubmit validation to accumulate failures in an array instead of returning at the first problem.
  4. Assign each error a stable code of 64 characters or fewer, and keep those codes aligned with your field identifiers.
  5. Throw one AggregateError when the array is not empty, and keep single Error rejections for genuine one-off failures.
  6. Read event.error.errors in onError and highlight the corresponding fields in your extension interface.
  7. Test on a development store by saving with several invalid fields, and confirm the admin lists each message.

FAQ

Q: Do we have to change anything for extensions already in production?

A: No. Single Error rejections keep working, and extensions on API versions earlier than 2025-10 retain the previous single message behaviour.

Q: What happens if our validation produces more than ten errors?

A: The admin shows the first ten and discards the rest. Order your checks so that activation blocking failures come first.

Resources

Function settings component reference

Need guidance? Talk to Makro.