Shopify just rolled out a game‑changing improvement for developers building function‑settings extensions on discount and checkout rule pages. By allowing an extension’s onSubmit handler to reject with an AggregateError, the admin UI can now display up to ten distinct validation messages in a single save attempt. This post breaks down the change, explains who needs to care, and walks you through the exact code you’ll need to start leveraging the new multi‑error reporting.
What’s New?
Previously, if your extension rejected the promise passed to event.waitUntil() with a single Error, the admin UI would surface only that one message. Merchants often had to fix a field, click Save, then discover the next error on a subsequent attempt. The new behavior expands the contract: when you throw an AggregateError containing multiple Error objects, the admin lists each one (up to ten), trims messages to 300 characters, and de‑duplicates identical texts. Each error can also carry a custom code, enabling you to highlight the exact field that needs attention.
Who Is Affected?
The update applies to any app that uses a s-function-settings extension on discount or checkout rule pages and is built with the Polaris web components on API version 2025‑10 or later. Extensions still on older API versions keep the original single‑error behavior, and extensions that continue to reject a single Error remain fully functional. In short, if you’re already targeting the latest API, you’ll automatically see the new multi‑error UI without any extra configuration.
Why It Matters for Merchants
From a merchant’s perspective, the change eliminates a frustrating trial‑and‑error loop. When a form contains several invalid fields—say, a missing minimum quantity and a percentage value above 100%—the admin now surfaces both messages immediately. Merchants can correct all issues in one go, speeding up discount creation and reducing support tickets caused by “only one error shows up” confusion. It’s a small UX tweak that delivers a noticeably smoother workflow.
How to Implement the AggregateError Pattern
Below is a minimal, production‑ready example that checks two fields and throws an AggregateError when either validation fails. Notice the helper fieldError function that attaches a custom code property to each Error—this code surfaces in the onError event, letting you map the error back to a specific UI component.
javascript
function fieldError(code, message) {
return Object.assign(new Error(message), {code});
}
async function save(settings) {
const errors = [];
if (!settings.minimumQuantity) {
errors.push(fieldError('MINIMUM_QUANTITY_REQUIRED', 'Enter a minimum quantity.'));
}
if (settings.percentage > 100) {
errors.push(fieldError('PERCENTAGE_TOO_HIGH', 'Percentage can be at most 100.'));
}
if (errors.length) {
throw new AggregateError(errors, 'Settings are not valid');
}
// Apply metafield changes or other side‑effects here
}
<s-function-settings
onSubmit={event => event.waitUntil(save(settings))}
onError={event => {
for (const err of event.error.errors) {
console.log(err.code, err.message);
// You could also highlight the offending field based on err.code
}
}}
>
{/* Your custom fields go here */}
</s-function-settings>
Key points to remember:
Testing Your New Validation Logic
What You Need to Do Now
Good news—no immediate migration is required. Existing extensions continue to work exactly as before. However, to take full advantage of the new experience you should:
Conclusion & Next Steps
Shopify’s multi‑error reporting is a subtle but powerful quality‑of‑life upgrade for both developers and merchants. By surfacing every validation issue in one go, you reduce friction, cut down on back‑and‑forth saves, and deliver a cleaner, more professional discount‑creation experience. Update your function‑settings extensions today, test the new flow, and watch your merchants thank you for the smoother workflow. Need help adapting your code or testing on a live store? Reach out in the Shopify Community forums or drop a comment below—we’re happy to help!
