Build a Discounts Allocator Function
This Function API is available only in the Discounts Allocator developer preview.
The Discounts Allocator Function will be available only to Shopify Plus merchants.
Building a Discounts Allocator Function allows for greater customization in defining discount strategies, like implementing custom logic to distribute discounts across line items in an order.
Anchor to What you'll learnWhat you'll learn
In this tutorial, you'll create a Discounts Allocator Function that uses metafields to help define its custom allocation logic.
The first metafield is applied at the order level. It sets a cap on the discount, ensuring that a 50% discount won't exceed a specified dollar amount.
The second metafield is applied at the shop level. It sets a maximum discounted amount for a cart.
Requirements
Create a Remix app that has the write_discounts and read_products access
scopes, using Shopify CLI 3.72.1 or
higher.
Install Node.js 22 or higher.
Install your app on the development store.
Project
Anchor to Update your app's access scopesUpdate your app's access scopes
Your app requires the write_discounts_allocator_functions access scope to create and update discounts.
Anchor to Update the ,[object Object], fileUpdate the shopify.app.toml file
shopify.app.toml fileAdd the write_discounts_allocator_functions scope to your app's shopify.app.toml file.
Error loading file. Please try again later.
Anchor to Deploy your app with new access scopesDeploy your app with new access scopes
-
Deploy your updated configuration to Shopify:
Terminal
shopify app deploy -
Restart your app development server:
Terminal
shopify app dev -
Open or reinstall your app using the URL provided by Shopify CLI. To preview your extensions, press
pin the terminal window where you started your app. -
Accept the new access scope permissions in your store.
Anchor to Create the Discounts Allocator FunctionCreate the Discounts Allocator Function
- Navigate to your app's directory:
Terminal
cd directory - Run the following command to create a new Discounts Allocator Function:
Terminal
shopify app generate extension --template discounts_allocator --name discounts-allocator - Choose the language that you want to use. For this tutorial, select
JavaScript.
Anchor to Update the configurationUpdate the configuration
Anchor to Replace the content of the extension's ,[object Object], fileReplace the content of the extension's run.graphql file
run.graphql fileThis GraphQL query is structured to retrieve all necessary data for applying discounts to shopping cart items, including discount details, cart line items, and shop metafields.
It ensures the function has access to discount rules, item specifics, and cap limits to accurately calculate and apply discounts according to predefined policies.
Error loading file. Please try again later.
Navigate to your extension's directory:
Terminal
Run the following command to regenerate types based on your input query:
Terminal
Anchor to Update the function logicUpdate the function logic
Anchor to Replace the content of ,[object Object], ,[object Object], file.Replace the content of run.js file.
run.js file.This function applies discounts to shopping cart items according to set rules and limits.
It calculates discount amounts, enforces caps to prevent excessive reductions, and compiles the results and any errors into a structured output, ensuring fair and policy-compliant discount application.
Error loading file. Please try again later.
Anchor to Define discount metafields for orders and the shopDefine discount metafields for orders and the shop
Use the GraphiQL app to create metafield definitions for the discount and shop.
Anchor to Create the discount metafield definitionCreate the discount metafield definition
To set the maximum discount amount for each discount, use the metafieldDefinitionCreate mutation with ownerType: "DISCOUNT".
Error loading file. Please try again later.
Anchor to Create the shop metafield definitionCreate the shop metafield definition
To set the maximum discount amount for the cart, use the metafieldDefinitionCreate mutation with ownerType: "SHOP".
Error loading file. Please try again later.
Anchor to Create the frontend UI for registering your Discounts Allocator FunctionCreate the frontend UI for registering your Discounts Allocator Function
After a merchant installs your app, they'll need to register the Discounts Allocator Function to actively allocate discounts.
You're replacing the Shopify discount engine with the Discounts Allocator Function. Your Function will take precedence over most discount features that are built by Shopify.
Anchor to Create a new route for the Discounts Allocator FunctionCreate a new route for the Discounts Allocator Function
In app/routes, create a new file named app.discounts-allocator.$functionId.jsx.
The Shopify Remix app template uses file-based routing, so the filename determines the page's URL. The $ prefix indicates that functionId is a dynamic segment. The path for this page is /app/discounts-allocator/{functionId}.
Error loading file. Please try again later.
Anchor to Add a Remix ,[object Object], function to handle form submissionAdd a Remix action function to handle form submission
action function to handle form submissionAdd a Remix action to app.discounts-allocator.$functionId.jsx to handle the form submission. This function calls the discountsAllocatorFunctionRegister mutation to register the Discounts Allocator Function.
Error loading file. Please try again later.
Anchor to Create the UI for registering the Discounts Allocator FunctionCreate the UI for registering the Discounts Allocator Function
Use the primaryAction in the Page component to expose a button that calls the action function. This button allows merchants to register the Discounts Allocator Function.
Error loading file. Please try again later.
Anchor to Update the UI pathUpdate the UI path
In extensions/discounts-allocator/shopify.extension.toml, populate the create and details setting in the [extensions.ui.paths] section. This change is automatically applied as long as you're running dev.
The settings in the shopify.extension.toml file define the URLs that Shopify uses to enable merchants to create and edit discounts based on your Function. Shopify automatically fills in any dynamic tokens in these URLs.
Error loading file. Please try again later.
Anchor to Register your Discounts Allocator FunctionRegister your Discounts Allocator Function
- If your app isn't already running, then start it using Shopify CLI:
Terminal
shopify app dev - Follow the CLI prompts to preview your app, and install or view it on your development store.
-
In your development store, navigate to
/app/discounts-allocator/:functionIdand register your Discounts Allocator Function.
The functionId is a dynamic segment in the route. It's used to identify the Discounts Allocator Function that the merchant is registering. You can find your functionId in your app's .env file or in your Partner Dashboard if you navigate to Apps > "your app" > Extensions > discounts-allocator-js.
Troubleshooting
If you receive a Could not find Function error, then confirm the following:
- The Function ID is correct.
- You've installed the app on your development store.
- Development store preview is enabled in the Partner Dashboard.
- Your app has the
write_discountsaccess scope.
Anchor to Create a discount and build a cartCreate a discount and build a cart
To test the single-discount-cap capability of your allocator, prepare an automatic discount and build a cart to apply the discount.
- In your Shopify admin, go to Discounts.
- Click the Create discount button near the top right of your page and select Amount off products. Fill in the values for the discount:
- For Method, use Automatic.
- For Discount percentage, use 50.
- Open your development store and build a cart with some eligible products. The discount amount applied should be 50 percent off.
Anchor to Test your Discounts Allocator Function with a Single Discount CapTest your Discounts Allocator Function with a Single Discount Cap
Anchor to Set the maximum eligible amount for individual discountsSet the maximum eligible amount for individual discounts
Use the metafieldsSet mutation to set the single-discount-cap metafield for the discount you created.
Error loading file. Please try again later.
Anchor to Replace the placeholdersReplace the placeholders
Replace DISCOUNT_ID with the ID of the discount you created and replace SINGLE_DISCOUNT_CAP with the desired cap, for example 500.
Error loading file. Please try again later.
Notice that the discount amount applied to your cart is capped at the value you set in the metafield when you refresh the cart.
Anchor to Create a maximum discount amount for a cartCreate a maximum discount amount for a cart
Anchor to Set the maximum discount amount for a cartSet the maximum discount amount for a cart
Use the metafieldsSet mutation in your shop to utilize the per-cart-cap capability of your allocator.
Error loading file. Please try again later.
Anchor to Replace the placeholdersReplace the placeholders
Replace SHOP_ID with the ID of your shop and replace PER_CART_CAP with the desired per cart cap, for example 50.
Error loading file. Please try again later.
Anchor to Test your Discounts Allocator Function with a Per Cart CapTest your Discounts Allocator Function with a Per Cart Cap
- Click the Create discount button and select Amount off order. Fill in the values for the discount:
- For Method, use Automatic.
- For Fixed Amount, use 500 or any amount higher than your
PER_CART_CAP.
- Go to the cart you created and refresh the page, the total savings will be capped at the
PER_CART_CAPvalue you set in the metafield.
