Build a complex validation function
You can use Cart and Checkout Validation Functions to ensure that purchases meet certain criteria before customers can complete an order. In this tutorial, you’ll use Shopify Functions to enforce product limits on store merchandise.
What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you’ll learn how to do the following tasks:
- Generate starter code for Shopify Functions.
- Use GraphQL to define the input of your function.
- Deploy functions to the Shopify platform.
- Review logs for your function.
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account.
- You've created a development store with the Checkout and Customer Accounts Extensibility developer preview enabled.
You've created an app that uses Shopify CLI 3.49.5 or higher. If you previously installed Shopify CLI, then make sure that you're using the latest version.
If you plan to create a UI for your extension, then start with the Remix app template.
You've installed Node.js 16 or higher.
You've installed your app on the development store with the Checkout and Customer Accounts Extensibility developer preview enabled.
Rust-specific requirements
Anchor link to section titled "Rust-specific requirements"The following requirements are specific to Rust-based development with Shopify Functions.
You've installed Rust.
On Windows, Rust requires the Microsoft C++ Build Tools. Make sure to select the Desktop development with C++ workload when installing the tools.
You've installed cargo-wasi:
Step 1: Create the validation function
Anchor link to section titled "Step 1: Create the validation function"To create your validation function, you need to use the Shopify CLI to generate a starter function, specify the inputs for your function using an input query, and implement your function logic using JavaScript or Rust.
Navigate to your app directory:
Run the following command to create a new validation extension:
Choose the language that you want to use. For this tutorial, you should select either Rust or JavaScript.
Shopify defaults to Rust as the most performant and recommended language choice to stay within the platform limits. For more information, refer to language considerations.
Navigate to
extensions/cart-checkout-validation
:Replace the contents of
src/run.graphql
file with the following code.run.graphql
defines the input for the function. You need the current cart lines' quantity and merchandise ID.If you're using JavaScript, then run the following command to regenerate types based on your input query:
Replace the
src/run.rs
orsrc/run.js
file with the following code.This function logic checks that the quantity of each cart line is not above 1. You can adjust the maximum quantity as needed.
If you're using Rust, then build the function's Wasm module:
If you encounter any errors, then ensure that you've installed Rust and cargo-wasi.
Step 2: Preview the validation on a development store
Anchor link to section titled "Step 2: Preview the validation on a development store"To test your validation, you need to make it available to your development store.
If you're developing a function in a language other than JavaScript or TypeScript, ensure you have configured
build.watch
in your function extension configuration.Navigate back to your app root:
Use the Shopify CLI
dev
command to start app preview:You can keep the preview running as you work on your function. When you make changes to a watched file, Shopify CLI rebuilds your function and updates the function extension's drafts, so you can immediately test your changes.
Follow the CLI prompts to preview your app, and install it on your development store.
Step 3: Turn on the validation
Anchor link to section titled "Step 3: Turn on the validation"- From the Shopify admin, go to Settings > Checkout.
Under Checkout rules, click Add rule: a new page will open and show a list of checkout rules.
Find the
cart-checkout-validation
function that you want to test and select it.To enable this validation and install it on the shop, click Turn on and then Save.
Optional: Control how checkout behaves when encountering runtime exceptions by selecting the validation under Checkout rules and toggling Allow all customers to complete checkout.
Step 4: Test the validation
Anchor link to section titled "Step 4: Test the validation"- From your online store, without logging in, create a cart with more than a single quantity in merchandise. If your validation prevents you from creating an invalid cart, go back to Settings > Checkout > Checkout rules and temporarily turn it off.
- Checkout and verify that your error message displays.
- Verify that checkout progress is blocked. Clicking the Continue to shipping in 3-page checkout, or the Pay now button in 1-page checkout, shouldn't redirect the user.
- Using the Storefront API
cartLinesAdd
mutation, confirm that the mutation'suserErrors
field contains the function's error message, and that executing the mutation was unsuccessful. - To debug your function, or view its output, you can review its logs in your Partner Dashboard.
- Log in to your Partner Dashboard and navigate to Apps > {your app} > Extensions > cart-checkout-validation.
- Click on any function run to view its input, output, and any logs written to
STDERR
.
- Add configuration to your validation using metafields.