Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 55 ยท Shopify Functions

Cart Validation, Delivery and Payment Customization

Use Shopify Functions to block invalid carts with validation errors and to hide, move or rename delivery and payment options at checkout, with runnable stand-ins.

Discounts are the best-known use of Shopify Functions, but three other function APIs shape the checkout in a quieter way. A cart and checkout validation function can say "this cart is not allowed" and show the buyer an error. A delivery customization function can hide, reorder or rename shipping options. A payment customization function can do the same for payment methods. Together they let you enforce business rules, such as "no more than 5 of this item" or "no cash on delivery for orders above a limit", without running a server in the buyer's request path.

This lesson explains the shape of each function, what the output means, and where the limits are. The real function code, queries and GraphQL calls are read-only here, because Shopify Functions run inside Shopify's WebAssembly sandbox and cannot run on this site. The runnable examples are plain JavaScript stand-ins that follow the same rule: a function is a pure transformation from input data to a list of operations. If you have not read the basics, start with Shopify Functions Overview and Building a Function from Scratch.

The output shapes below follow the Functions API as of version 2025-07. Shopify renames fields between versions (cart validation changed its output format in 2025), so always generate the input schema for the API version your app targets with the CLI and compare it with these examples.

The idea: return instructions, do not change things

None of these functions edits the cart itself. Each one reads an input (the result of a GraphQL query you wrote in input.graphql) and returns operations: small instructions that Shopify applies. That is why the functions are easy to test: input in, output out, no side effects.

flowchart LR
  A["Checkout renders"] --> B["Shopify builds input<br/>from your input.graphql"]
  B --> C["Function runs in Wasm sandbox"]
  C --> D["Operations returned"]
  D --> E["Shopify applies them<br/>(errors, hide, move, rename)"]

The function never touches the checkout directly: it returns operations and Shopify applies them.

Because the function runs on every relevant checkout change, it has strict limits on time and size. We return to those at the end.

Cart and checkout validation

The validation target is cart.validations.generate.run (a second target, cart.validations.generate.fetch, exists for functions that need extra network data, and it is used far less often). The function receives the cart and returns a list of operations. A validationAdd operation carries a list of errors, and each error has a message for the buyer and a target, a path that says where the error belongs.

Read-only example of input.graphql:

GRAPHQL
query RunInput {
  cart {
    lines {
      id
      quantity
      merchandise {
        __typename
        ... on ProductVariant {
          product { title }
        }
      }
    }
  }
}

And a read-only function in JavaScript (generated projects use src/cart_validations_generate_run.js or a similar name, depending on the template version):

JavaScript
export function cartValidationsGenerateRun(input) {
  const errors = input.cart.lines
    .filter((line) => line.quantity > 5)
    .map((line) => ({
      message: "You can buy at most 5 of each item.",
      target: `$.cart.lines[${input.cart.lines.indexOf(line)}].quantity`,
    }));

  return { operations: [{ validationAdd: { errors } }] };
}

Important behaviors:

  • Blocking is a merchant setting. The function only reports errors. Whether an error actually stops the buyer from continuing is controlled by the validation record's blockOnFailure setting (you create that record with the validationCreate mutation, or the merchant enables it in your app's settings UI). With blocking off, the checkout proceeds even if the function reports problems.
  • Errors can be tied to a place. A target such as $.cart shows a general error, and a target pointing at a line shows it next to that line. The exact set of supported targets depends on the surface (cart page, checkout), so test on both.
  • Return an empty list when everything is fine. Returning no errors is a valid output, and it is what most runs do.
  • Validation is not security. Buyers can use APIs and scripts. Treat validation as a user-experience and policy layer, and re-check critical rules when the order arrives, for example in an order webhook (see Webhooks in Shopify).

Here is a runnable stand-in. It uses the same input shape and the same operation names, with a few rules that merchants often want.

Node.js A cart validation stand-in

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Delivery customization

The delivery target is cart.delivery-options.transform.run. The input lists the cart's delivery groups (the cart is split into groups that ship together), and each group has delivery options with a handle and a title. The function returns operations that refer to an option by its handle:

  • hide removes an option from what the buyer sees.
  • move places an option at a given index.
  • rename changes the title shown to the buyer.

Typical uses: hide express shipping for heavy items, put the cheapest option first, or rename "Standard" to "Standard (3 to 5 days)". A function cannot create a delivery option or change its price. Rates still come from your shipping settings or carrier services (see Shipping Rates for how rates are built).

Payment customization

The payment target is cart.payment-methods.transform.run. It works the same way, but the input lists payment methods with an id and a name, and the operations are hide, move and rename on a paymentMethodId. Use it to hide a pay-on-delivery method for large orders, or to move a preferred wallet to the top. Do not use it to take a payment method away to hide a fee, and keep the merchant informed in your app's UI about which rules are active. For the payment side of the story, see Payments Overview.

Both customization functions are configured the same way as other functions: you create a record for the function with a mutation such as deliveryCustomizationCreate or paymentCustomizationCreate, and you can store settings in a metafield that the function reads through its input query. Which plans can use which function types has changed over time, so check the current reference before promising a feature to merchants.

Node.js Delivery and payment operations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Limits you must design for

Functions are fast on purpose, so they come with documented limits. At the time of writing these include a cap of roughly 11 million WebAssembly instructions per run, a compiled module size limit of about 256 KB, and limits on the size of the input and output. Treat the numbers as orders of magnitude and read the current limits in the reference before you rely on them. What they mean in practice:

  • Query only what you need. A large input costs time to build and parse. Ask for the fields your rule uses.
  • No network and no clock. A function cannot call your server or read arbitrary state. Everything it knows comes from the input, so put settings in a metafield and read them in the query. (The separate fetch target exists for fetching data ahead of the run, but it has its own limits.)
  • Be deterministic. The same input must give the same output. That also makes testing easy, which the next lesson covers.
  • Fail safe. If your rule cannot decide, return no operations. For a validation function, a crash means the checkout may proceed without your check, or it may be blocked, depending on settings, so keep the code simple.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a cart validation function return?

    Functions return operations, and Shopify applies them. A validation function returns errors through validationAdd; it never edits the cart itself.
  2. 2. Where is it decided whether a validation error actually stops the buyer from continuing?

    The function only reports errors. The validation record's blockOnFailure setting controls whether the checkout is blocked.
  3. 3. Which operations can a delivery customization function return?

    A delivery customization can hide, move or rename existing options. It cannot create options or change prices.
  4. 4. Why should a critical business rule not rely on a validation function alone?

    Validation improves the checkout experience, but it is not a security boundary. Re-check rules that protect money or stock when you receive the order.

Summary

  • Validation, delivery and payment customization functions read an input and return operations; Shopify applies them.
  • Validation returns validationAdd with errors (a message and a target); blocking depends on the validation record's blockOnFailure setting.
  • Delivery customization hides, moves or renames options by handle; payment customization does the same by payment method id.
  • Functions cannot create options, change prices, call the network or keep state; settings come in through metafields in the input.
  • Respect the instruction and size limits, keep the input query small, and re-check critical rules on the order.
  • Field names change between API versions, so generate the schema for your target version.

Next: Testing and Debugging Functions.