Shopify Functions / API 2026-04

Billing address and PO number
can now be rejected by a server-side validation function

Cart and Checkout Validation Functions add billingAddress and poNumber . You can now enforce billing-country blocks or PO-number requirements for B2B orders at checkout without relying on client-side UI extensions.

On this page
  1. What's changing (in 30 seconds)
  2. Diagram: from input to validation error display
  3. New input fields and error targets
  4. Before (UI extension dependent) vs 2026-04 (validated by function)
  5. Impact (compatibility)
  6. 5 key points for developers
  7. 3 practical use cases
  8. One-line summary for proposals

1What's changing

API version 2026-04 , Cart and Checkout Validation Functions can now validate billing addressandPO number (purchase order number).
The relevant fields have been added to the input graph, and new checkout field targets are available for surfacing error messages.

Before: dependent on client-side UI extensions

Billing address and PO number checks could only be implemented in checkout UI extensions (client-side). There was no reliable way to enforce them on the server side.

2026-04: enforced by validation functions

Compliance rules such as blocking specific billing countries or requiring PO numbers on B2B orders can now be enforced in the function itself, without relying on UI extensions.

2Diagram: from input to validation error display

Customer input Billing address PO number checkout / cart Function input graph billingAddress poNumber null outside of validation Validation Function Evaluate rules Field-level errors at checkout $.cart.billingAddress.{field} $.cart.poNumber Error shown on the relevant field
When a function returns validation (errors) against a target, checkout displays them asfield-level errorson the billing address and PO number.
billingAddress and poNumber existin all Shopify Function input graphs, but outside Cart and Checkout Validation they return null .

3Added input fields and error targets

Input graph field

Input graph

billingAddress

Billing address. Available in all Function input graphs. Outside Cart and Checkout Validation, null.

Input graph

poNumber

PO (purchase order) number. Available in all Function input graphs. Outside Cart and Checkout Validation, null.

Checkout field targets for error messages

TargetApplies to
$.cart.billingAddress.{field} All standard address subfields of the billing address
$.cart.poNumber PO number

※ {field} The list of individual subfield names that can be specified is not included in this article. It only states "all standard address subfields."

4Legacy (UI extension–based) vs. 2026-04 (validated by functions)

ItemLegacyAPI 2026-04 and later
Billing address validation UI extension Implemented client-side Function $.cart.billingAddress.{field} validates
PO number validation UI extension Implemented client-side Function $.cart.poNumber validates
Enforcement Relies on client-side UI Enforced by server-side validation functions
Expected use cases — Blocking prohibited billing countries, requiring PO numbers for B2B orders, etc.
Impact on existing functions — No breaking changes Add validation optionally

5Impact (compatibility)

No breaking changes

Existing Functions continue to work as-is. Validation for these new targets can beadded optionally.

Field-level error display

When a function returns validation for these targets, checkout surfaces them as field-level errors on the billing address or PO number.

Adoption is just "add validation if you want." You can roll it out incrementally — store by store, rule by rule — without disrupting existing operations.

65 key points for developers

2026-04

1. Required API version is 2026-04

This validation is available from API version 2026-04 onward. You must bump your function's target API version.

billing poNumber

2. The input graph is shared across all Functions

billingAddress and poNumber are added to every Shopify Function input graph. The fields themselves are accessible from any function.

null

3. null outside of validation

Both fields return outside of Cart and Checkout Validation null . Don't build other Function types around expected values here.

$.cart.billingAddress $.cart.poNumber

4. Two new error target families

$.cart.billingAddress.{field}(all standard address subfields) and $.cart.poNumber. Returning validation against these produces field-level errors.

UI FN

5. Shift from client-side UI extensions to the server side

Blocking restricted billing countries or requiring a PO number for B2B can now be enforced in functions without relying on client-side UI extensions. Since there are no breaking changes, you can adopt this just by adding validation to your existing functions.

73 practical use cases

B2B PO #
USE CASE 1

Make the PO number "server-side required" for B2B orders

Problem
You want to require a purchase order (PO) number for B2B transactions, but client-side UI extensions can be bypassed and can't reliably enforce it.
Solution
In a Cart and Checkout Validation Function, $.cart.poNumber return an error if it's empty and block checkout completion.
Impact
Reliably reject orders without a PO number on the server side, preventing reconciliation gaps in accounting and billing.
Technical notes
Requires API version 2026-04.poNumber outside of Cart and Checkout Validation, null.
USE CASE 2

Block restricted billing countries at checkout

Problem
For export control and compliance reasons, you don't want to accept orders with billing addresses from specific countries.
Approach
Evaluate the billing address country code in the function, and if it's a prohibited country, return $.cart.billingAddress.{field} an error on the field.
Outcome
Display prohibited-country billing addresses as errors on the relevant field, and block the order at the checkout stage.
Technical notes
The key point is that this can be enforced server-side without relying on UI extensions.billingAddress Note that outside of validation, null behaves differently.
USE CASE 3

Fix billing address issues at the subfield level

Problem
Issues with billing addresses (such as missing required subfields) cause problems downstream.
Approach
$.cart.billingAddress.{field} Validate the standard address subfields with the function, and return errors on the fields that have issues.
Outcome
Show customers which fields they need to correct via field-level errors, and have them fix the issues during checkout.
Technical notes
Details on which individual subfield names can be specified are not covered in this article. Check the developer documentation before implementation.

8One-line summary for proposals

"From API 2026-04,billing addresses and PO numbers can be validated with the Cart and Checkout Validation Function.
Without relying on client-side UI extensions,you can enforce blocking prohibited-country billing addresses and requiring PO numbers for B2B server-side.
There are no breaking changes — you can adopt this simply by adding validation to existing functions."