Order Validation Functions

An order_validation function runs at both cart verification and order placement. It fires during cart verification (with step: 'cart') so your rules can surface in the cart/checkout preview, and again as the final gate at order placement (with step: 'review'). Return one or more errors and the order is rejected with a 400 Bad Request. Return nothing and the order proceeds. Use it for purchase limits, geographic blocks, age/compliance gates, required-accessory rules, or anything that needs to block the order itself — not just hide a payment method or warn the customer in the cart.

How It Works

This function runs at cart verification (step: 'cart') and at the order-place endpoint (step: 'review'), so your rules can be reflected in the cart/checkout preview as well as enforced as the final gate when the customer presses “Place order”.

Function Manifest

{
  "handle": "my-validation-app",
  "name": "Order Validator",
  "version": "1.0.0",
  "functions": {
    "order_validation": {
      "handle": "order-rules",
      "name": "Order Validation Rules",
      "config": {
        "maxQuantityPerLine": 10,
        "blockedCountries": ["XX", "YY"]
      }
    }
  }
}

Input Schema

interface OrderValidationInput {
  cart: {
    items: CartItem[];
    totalPrice: number;       // Subtotal in display currency
    itemCount: number;
    currency: string;
  };
  customer?: {
    id: string;
    email: string;
  };
  shippingAddress?: {      // optional — absent on some dispatches
    firstName: string;
    lastName: string;
    address1: string;
    address2: string;
    city: string;
    province: string;
    country: string;
    zip: string;
    phone: string;
  };
  step?: 'cart' | 'shipping' | 'payment' | 'review';
  //  Which dispatch point this call is for: 'cart' at cart verification,
  //  'review' at order placement. Defaults to 'review' when absent.
}

interface CartItem {
  id: string;                 // lineItemId
  variantId: string;
  productId: string;
  title: string;
  quantity: number;
  price: number;              // Effective unit price (display currency)
  originalPrice: number;
}

The input is intentionally minimal. There is no paymentMethod, no shop, no tags/productType/vendor on items, and customer carries only id and email. If you need richer data, fetch it from your own backend keyed on the customer/order ids you receive here.

Output Schema

interface OrderValidationOutput {
  errors?: ValidationError[];
}

interface ValidationError {
  message: string;          // Required — shown to the customer
  target: 'cart' | 'line' | 'line_item' | 'shipping' | 'customer';
  //  REQUIRED. An error whose `target` isn't one of these values fails
  //  output validation, so the whole result is dropped and the order is
  //  allowed through. (`line_item` is an alias for `line`.)
  lineId?: string;          // CartItem.id when target='line' / 'line_item'
  code?: string;            // Machine-readable code for analytics
}

The backend treats errors.length > 0 as invalid. There is no valid: true|false boolean — an empty errors array (or an absent field) means the order is allowed. When multiple errors are returned, the first message becomes the HTTP 400 headline. The full list is attached to the response as data.errors so the frontend can render per-line/per-field callouts.

HTTP/1.1 400 Bad Request

{
  "status": "error",
  "message": "Maximum 10 units allowed for \"Premium Widget\". Reduce quantity from 15.",
  "data": {
    "errors": [
      {
        "message": "Maximum 10 units allowed for \"Premium Widget\". Reduce quantity from 15.",
        "target": "line",
        "lineId": "line_42",
        "code": "QUANTITY_LIMIT_EXCEEDED",
        "appId": "my-validation-app"
      }
    ]
  }
}

The platform automatically stamps each error with the originating appId so the frontend can attribute blame.

Examples

Per-line quantity cap

function validateOrder(input, config) {
  const max = config.maxQuantityPerLine || 10;
  const errors = input.cart.items
    .filter(i => i.quantity > max)
    .map(i => ({
      message: `Maximum ${max} units allowed for "${i.title}". Reduce from ${i.quantity}.`,
      target: 'line',
      lineId: i.id,
      code: 'QUANTITY_LIMIT_EXCEEDED'
    }));
  return { errors };
}

Geographic block

function validateOrder(input, config) {
  const blocked = config.blockedCountries || [];
  if (blocked.includes(input.shippingAddress.country)) {
    return {
      errors: [{
        message: `We can't ship to ${input.shippingAddress.country}.`,
        target: 'shipping',
        code: 'RESTRICTED_COUNTRY'
      }]
    };
  }
  return { errors: [] };
}

Guest checkout limit

function validateOrder(input) {
  if (!input.customer && input.cart.totalPrice > 500) {
    return {
      errors: [{
        message: 'Orders over ₹500 require an account. Please sign in to continue.',
        target: 'customer',
        code: 'ACCOUNT_REQUIRED'
      }]
    };
  }
  return { errors: [] };
}

Required-accessory check

function validateOrder(input) {
  const errors = [];
  const ids = new Set(input.cart.items.map(i => i.productId));

  // Console controller (prod_console) needs at least one cable (prod_cable_a/b)
  if (ids.has('prod_console') && !ids.has('prod_cable_a') && !ids.has('prod_cable_b')) {
    errors.push({
      message: 'Add a USB-C cable to your cart to use the console.',
      target: 'cart',
      code: 'MISSING_ACCESSORY'
    });
  }
  return { errors };
}

How errors render in the UI

The checkout converts the 400 into an inline error banner above the place-order button. When target='line' and lineId matches a cart line, the checkout can additionally highlight that specific line (subject to theme support).

⚠ Maximum 10 units allowed for "Premium Widget". Reduce from 15.

[Edit cart] [Continue editing]

Multiple apps

All installed validation functions run in install order. Errors from every function are concatenated, and the order is blocked if any function returns at least one error.

Best Practices

Validate early when possible

A cart-transform or storefront-side check that prevents the bad state at all is a better customer experience than a 400 after they pressed “Place order”. Use order_validation as the server-side gate, not the primary signal.

Write actionable messages

“Reduce quantity from 15 to 10” beats “Quantity invalid”. Tell the customer exactly what to change.

Use `target` + `lineId`

Themes that support per-line error rendering rely on these fields. Plain string messages still work, but lose the inline-highlight UX.

Handle missing customer

Guest checkouts arrive with customer === undefined. Don’t crash — return { errors: [] } if your rule doesn’t apply.

Keep functions fast

The order-place flow blocks on this dispatch. A slow validator means a slow checkout. If you need to call an external API, cache aggressively and short-circuit on identical inputs.

Get Started

Guides

Extensions

Functions

App Bridge

Billing

AI & MCP

Order Validation Functions

Order Validation Functions

How It Works

Function Manifest

Input Schema

Output Schema

Examples

Per-line quantity cap

Geographic block

Guest checkout limit

Required-accessory check

How errors render in the UI

Multiple apps

Best Practices

See Also

​Order Validation Functions

​How It Works

​Function Manifest

​Input Schema

​Output Schema

​Examples

​Per-line quantity cap

​Geographic block

​Guest checkout limit

​Required-accessory check

​How errors render in the UI

​Multiple apps

​Best Practices

​See Also

Order Validation Functions

How It Works

Function Manifest

Input Schema

Output Schema

Examples

Per-line quantity cap

Geographic block

Guest checkout limit

Required-accessory check

How errors render in the UI

Multiple apps

Best Practices

See Also