---
gid: 60bd9a24-c5ec-4aa0-97af-b58496bd6fae
title: Build a Discount Function
description: Use Shopify Functions to discount cart lines, order subtotals, and shipping rates using a single discount.
---
import RequirementPartial from 'app/views/partials/apps/discounts/requirements_partial.mdx';
import CreateFunction from 'app/views/partials/apps/discounts/create-function.mdx';
import DeployAndReinstallApp from 'app/views/partials/apps/discounts/deploy-and-reinstall-app.mdx';
import RegenerateTypes from 'app/views/partials/apps/discounts/regenerate-types.mdx';
import ReviewFunctionExecution from 'app/views/partials/apps/app-extensions/review-function-execution.md';
import TroubleshootingFunction from 'app/views/partials/apps/discounts/troubleshooting-function.mdx';
import NextStepsDiscounts from 'app/views/partials/apps/discounts/next-steps-discounts.mdx';
With [Shopify Functions](/docs/apps/build/functions), you can create a new type of discount that applies to cart lines, order subtotal, and shipping rates.
In this tutorial, you'll use Shopify Functions to create a new type of discount that does three things:
- Reduces the price of a cart line by 20%
- Discounts the order subtotal by 10%
- Provides free shipping
After creating the discount, you can test it out in your store.
To learn how to migrate your existing Discount Functions to use the [Discount API](/docs/api/functions/reference/discount), refer to [Migrate to the Discount API](/docs/apps/build/discounts/migrate-discount-api).
## What you'll learn
In this tutorial, you'll learn how to do the following tasks:
- Use the Shopify CLI to add a Discount Function to an app
- Review the configuration of your discount function
- Review the input queries associated with your discount function
- Review the function logic associated with your discount function
- Deploy your updated app with new access scopes
- Use GraphiQL to create a discount and configure it to work with your function
- Test your discount function and view its logs
Create an that has the `write_discounts` and `read_products` [access
scopes](/docs/api/usage/access-scopes), using [Shopify CLI 3.72.1 or
higher](/docs/api/shopify-cli#upgrade).
Install Node.js 22 or higher.
On Windows, Rust requires the [Microsoft C++ Build Tools](https://docs.microsoft.com/en-us/windows/dev-environment/rust/setup). Make sure to select the **Desktop development with C++** workload when installing the tools.
To ensure compatibility with the latest version of Rust, install the `wasm32-wasip1` target.
```bash
shopify app generate extension --template discount --name discount-function-rs
```
```bash
shopify app generate extension --template discount --name discount-function-js
```
Steps 2-4 review the generated code. To proceed directly to deploying and testing your Discount Function, jump to [Step 5](#update-your-app's-access-scopes).
## Review the Discount Function Configuration
The `shopify.extension.toml` file defines the Discount Function's metadata, targets, and build configuration.
### Metadata
The `[[extensions]]` section defines the Function metadata. This includes the Function's handle, name, description, and type. The `name` and `description` are displayed on the **Discount** page of your Shopify admin.
Shopify provides localization tools, and you can use them to localize the name and description of Discount Functions. To learn more, refer to [localizing your Shopify app](/docs/apps/build/localize-your-app).
### Targets
The `[[extensions.targeting]]` sections define the Function targets. Each section includes a `target`, `input_query`, and `export` property.
The [`target`](/docs/apps/build/app-extensions/configure-app-extensions#targets) property defines where the Function is applied. The Discount API has two [`run` targets](/docs/api/functions/reference/discount/graphql):
- `cart.lines.discounts.generate.run` - The Function can apply discounts to cart lines and order subtotals.
- `cart.delivery-options.discounts.generate.run` - The Function can apply discounts to shipping rates.
The `input_query` property is the path to the Function's input query file. This file defines the Function's [input parameters](/docs/api/functions/reference/discount/graphql/input).
The `export` property specifies the build entrypoint that will run for a specified target. This will usually be the function name of your main export.
### Build configuration
The `[extensions.build]` section defines the build configuration for your Function. This includes the build `command`, the build `path` and a `watch` property which allows you to watch for changes to the Function. Refer to [Shopify Functions extensions](/docs/apps/build/app-extensions/configure-app-extensions#shopify-functions-extensions) for more information.
Depending on your app type, you may have to define the `[extensions.ui]` or `[extensions.ui.paths]` section.
Refer to [Build a discounts UI with Admin UI Extensions](/docs/apps/build/discounts/build-ui-extension) or [Build a discounts UI with Remix](/docs/apps/build/discounts/build-ui-with-remix) to learn more about building UIs to configure Functions.
## Review the input queries for your Function
[Input queries](/docs/apps/build/functions/input-output) are used to define the input that the Discount Function needs. The result of those queries will be given as input parameters to the export functions.
### `cart_lines_discounts_generate_run.graphql` input
The result of this query is provided as input to the `cart.lines.discounts.generate.run` target. Refer to [Discount API](/docs/api/functions/reference/discount) for more information about the input data available to your Function.
### `cart_delivery_options_discounts_generate_run.graphql` input
The result of this query is provided as input to the `cart.delivery-options.discounts.generate.run` Function. Refer to [Discount API](/docs/api/functions/reference/discount) for more information about the input data available to your Function.
## Review the logic of your Function
To specify how a Discount Function should apply discounts, update its logic. This logic can make use of the input parameters provided to the Function, and should output discount operations.
Your Function should only return operations for `discountClasses` that the discount applies to. For example, if the discount is configured to apply to `PRODUCT` and `ORDER`, but not `SHIPPING`, your Function should only return operations for `PRODUCT` and `ORDER`.
### Review your cart run Function logic
This is the entry point for cart line and order subtotal discount calculation logic. The name must match the `export` property in the `[[extensions.targeting]]` section of your Function's configuration and must output [`CartOperations`](/docs/api/functions/reference/discount/graphql/common-objects/cartoperation).
In this example, the Function checks whether the discount applies to `PRODUCT` and `ORDER` and applies two discounts: 10% off the entire order subtotal, plus an additional 20% off the highest cart line subtotal.
### Review your delivery run Function logic
This is the entry point for shipping rate discount calculation logic. The name must match the `export` property in the `[[extensions.targeting]]` section of your Function's configuration and must output [`DeliveryOperations`](/docs/api/functions/reference/discount/graphql/common-objects/deliveryoperation).
In this example, the Function checks whether the discount applies to `SHIPPING` and reduces the first delivery group by 100%, offering free shipping.
## Update your app's access scopes
You must request the `write_discounts` [access scope](/docs/api/usage/access-scopes) to give your app the permissions that it needs to create and update discounts.
In `shopify.app.toml`, located in the root of your app, add the `write_discounts` scope to the `access_scopes` array.
The development server automatically watches files that match the [build.watch](/docs/api/functions/configuration#properties) glob pattern. When it detects a change, it builds your Function and updates the Function extension's draft so that you can preview changes immediately.
## Create a discount in your store
In this step, you'll use GraphiQL, an in-browser tool for testing GraphQL, to create a discount that applies a line-item price adjustment, an order-wide percentage discount, and free shipping. Then you'll link this discount to the Function that you deployed in the previous step.
GraphiQL is an in-browser tool for writing, validating, and testing GraphQL queries.
You can also build a discount interface using [Admin UI Extensions](/docs/apps/build/discounts/build-ui-extension) and configure your Functions using [Metafields](/docs/api/functions/reference/discount/graphql/common-objects/metafield).
### Open the GraphiQL interface for the Shopify Admin API
1. Open the GraphiQL interface by pressing `g` in the terminal window where you started your app.
1. On the GraphiQL interface, for **API Version**, select the latest stable release.
### Get the ID of your Function
To get the ID of your Function, use the [`shopifyFunctions`](/docs/api/admin-graphql/latest/queries/shopifyFunctions) query. You'll use this ID to associate your Functions with the newly created discount.
The result contains a node with your Function's ID.
```json
{
"app": {
"title": "your-app-name-here"
},
"apiType": "discounts",
"title": "discount-function-js",
"id": "YOUR_FUNCTION_ID_HERE"
}
```
### Create the discount
To create a discount in your store, use the [`discountAutomaticAppCreate`](/docs/api/admin-graphql/latest/mutations/discountAutomaticAppCreate) mutation.
1. For `functionId`, provide the Function ID from the [previous step](#get-the-id-of-your-function).
1. Add the [`discountClasses`](/docs/api/functions/reference/discount/graphql/common-objects/discountclass) field to your mutation based on the business requirements.
You should receive a GraphQL response that includes the ID of the created discount.
If the response includes any `userErrors`, then review them, check that your mutation and `functionId` are correct, and try the request again.
## Test the Discount Function
### View your discount
In your Shopify admin, go to **Discounts**. You should now see the **Cart line, Order, and Shipping discount** that you created.
### Deactivate other discounts
Deactivate or delete all other discounts, to ensure that the **Cart line, Order, and Shipping** discount is the only active discount.
### Build a cart
Open your development store and build a cart with a single item in it.
### Validate discount application
On the cart page, you should see that your Discount Function has applied a discount to a cart line and the order subtotal.
Once you navigate to the checkout page and fill in your shipping address, you will see the discounts applied to the shipping rates.
