Verify Expected Mismatch

What a mismatch means

When Verify Expected returns expectationsWereMet: false, it means the promotions currently applicable to the cart differ from the list the customer saw during their last Verify call. This is a deliberate safety mechanism — it prevents a customer from being charged a different amount than the price they agreed to.

This is not an error in your integration. It is the system working correctly.

Common causes

A promotion's usage limit was reached by another customer between the time your customer viewed their cart and when they clicked "Place order". Concurrent shoppers can exhaust a limited-use promotion.
A coupon code's per-code limit was hit by another redemption in the same window.
The promotion's schedule ended — an end date passed while the customer was in checkout.
The cart contents changed — for example, the customer has the checkout open in two tabs.
An admin disabled a promotion in the Dashboard while the customer was in the checkout flow.

What your storefront must do

Do NOT proceed to payment capture or Record when Verify Expected returns a mismatch.

The correct response is:

Re-call the Verify endpoint to get the current applicable promotions and updated cart totals.
Display the updated cart state to the customer, clearly indicating that the pricing has changed.
Ask the customer to confirm the updated cart before proceeding.
Only proceed to Record after the customer confirms.

Do not silently proceed with the old expected values. The Record endpoint re-evaluates the cart one final time before committing usage records — if expectations still don't match at that point, Record will also reject the request.

Why silent fallback is not an option

Silently proceeding and charging the customer a price they didn't agree to creates a support and chargeback risk. The Verify Expected / Record design exists to give the customer one final moment to confirm before their card is charged.

For implementation guidance on handling the full Verify Expected and Record flow, see the Custom Storefront integration guide.