Cart validation functions can't see draft order metafields on draftOrderComplete

Hey folks

We’ve hit something with cart validation functions and draft orders and wanted to check whether it’s expected or a gap.

Since validation functions now run when a draft order is completed (via draftOrderComplete, or “Mark as paid” in the admin), we’d love for our validation to read data we store on the draft. But the function’s cart never seems to include the draft order’s metafields, so a metafield-based check can’t pass for any draft.

Where this hurts:

  • Merchants completing drafts in the admin are fine. They get the unresolved business rule modal, click “Ignore and create order”, and carry on.
  • Apps that create and complete drafts through the Admin API can’t do that. For example, helpdesk apps like Gorgias re-ship an order by duplicating it into a draft and completing it. There’s no API equivalent of the ignore button, so draftOrderComplete just returns the validation error and the draft gets stuck. That’s true even when the data the validation needs is already on the draft as a metafield. One merchant ended up with a pile of open re-ship drafts that their team had to find and push through by hand.

How to reproduce (Admin API 2026-07):

  1. Create a draft with draftOrderCreate and metafields: [{namespace: "my_app", key: "selection", type: "json", value: "{…}"}]. The metafield is right there in the response.
  2. Read the draft back. Still there.
  3. Call draftOrderComplete(id, paymentPending: true). Our function’s input query asks for cart { metafield(namespace: "my_app", key: "selection") { jsonValue } }, but at buyerJourney.step: CHECKOUT_COMPLETION that field comes through as null, so the draft stays open with our validation error in userErrors.

What does work:

  • Draft customAttributes show up fine through cart.attribute(key:).
  • On the draft’s invoice-link checkout, a cart metafield written by a checkout UI extension is visible as you’d expect.

A couple of related things we noticed:

  • There’s no documented way for a function to know the cart came from a draft order.
  • The draft order → order metafield copy (“Matching draft order definition”) can only be set up in the admin. MetafieldCapabilities on 2026-07, 2026-10 and unstable only has cartToOrderCopyable, so apps can’t create that link for merchants.

A few questions:

  1. Is it intended that draft order metafields aren’t passed to validation functions as cart metafields?
  2. Could they be exposed (maybe only when a matching draft order definition exists), or could the function input get a documented “this is a draft order” signal?
  3. Is there, or could there be, a way for an API caller to complete a draft despite a validation error, like the admin’s “Ignore and create order”?
  4. Is an API for linking draft order and order metafield definitions on the roadmap?

Happy to share more details if that helps. Thanks a lot!

Hi @Patrick_Jakubik

Your findings match the current implementation: draft-order metafields aren’t mapped into the validation Function’s cart.metafield input. Setting up matching draft/order definitions won’t make those values available to the Function either; that handles copying onto the resulting order.

One detail I found is that bypassCartValidations exists on unstable, but it isn’t available in 2026-07 or 2026-10. Unstable is for early testing only, so this still leaves the production re-shipment workflow you described without a stable API override. The attribute approach you’ve tested also depends on the app creating the draft being able to supply that data.

I saw your earlier discussion with Kellan, where feedback about configuring matching definitions through the API was already recorded. I don’t have a confirmed update on that request. I also can’t yet confirm whether leaving draft metafields out of the Function input is intentional, or whether support for them or a draft-origin field will be added.

Thanks @Patrick_Jakubik for your feedback. We’re exploring improvements to metafield support in Draft Orders. Your use case is helpful input as the team considers what to address.