Build a Discounts Allocator Function

Feature Preview

This Function API is available only in the Discounts Allocator feature 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 Partner account

Create a development store

Create an app

Create a React Router app that has the write_discounts and read_products access scopes, using the latest version of Shopify CLI.

Install Node.js

Install Node.js 22 or higher.

Install the app

Install your app on the development store.

Project

Extension:

View on GitHub

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

Add the write_discounts_allocator_functions scope to your app's shopify.app.toml file.

shopify.app.toml

# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration

client_id = "7e1ce6ae588ac87953ac011795fbecb9"

name = "build-a-discount-function"

handle = "build-a-discount-function"

application_url = "https://costa-tariff-quarter-mega.trycloudflare.com"

embedded = true

[build]

automatically_update_urls_on_dev = true

dev_store_url = "quickstart-3a22a586.myshopify.com"

include_config_on_deploy = true

[access_scopes]

scopes = "write_products, write_discounts, write_discounts_allocator_functions, read_products"

[auth]

redirect_urls = [

"https://costa-tariff-quarter-mega.trycloudflare.com/auth/callback",

"https://costa-tariff-quarter-mega.trycloudflare.com/auth/shopify/callback",

"https://costa-tariff-quarter-mega.trycloudflare.com/api/auth/callback"

]

[webhooks]

api_version = "2024-07"

[pos]

embedded = false

[discount.metafields.app.single_discount_cap]

name = "Single Discount Cap"

description = "Maximum reduction value for a single discount"

type = "number_decimal"

validations.min = 0

[shop.metafields.app.per_cart_cap]

name = "Maximum Discount Per Cart"

description = "Maximum discount value applied to a single cart"

type = "number_decimal"

validations.min = 0

Anchor to Start your app to preview changesStart your app to preview changes

Save your updated configuration TOML file.
Start app dev if it's not already running:

Terminal
shopify app dev

The configuration TOML file changes will be applied automatically on the development 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

This 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.

extensions/discounts-allocator-js/src/run.graphql

query RunInput {

discounts {

title

code

discountApplicationStrategy

discountProposals

{

handle

message

value {

__typename

... on FixedAmount {

amount

appliesToEachItem

}

... on Percentage {

value

}

targets{

cartLineId

quantity

}

metafield(namespace: "$app", key: "single_discount_cap") {

value

}

presentmentCurrencyRate

cart {

lines {

quantity

cost {

amountPerQuantity {

amount

}

merchandise {

__typename

... on ProductVariant {

title

product {

title

}

shop {

metafield(namespace: "$app", key: "per_cart_cap") {

value

}

Navigate to your extension's directory:

Terminal

cd extensions/discounts-allocator

Run the following command to regenerate types based on your input query:

Terminal

shopify app function typegen

Anchor to Update the function logicUpdate the function logic

Anchor to Replace the content of ,[object Object], , file.Replace the content of `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.

extensions/discounts-allocator-js/src/run.js

import { Decimal } from "decimal.js";

const TOTAL_DISCOUNTS_CAP_REACHED =

"Maximum discount limit reached for this cart";

const SINGLE_DISCOUNT_CAP_REACHED =

"Maximum discount limit reached for this discount";

// Helper function to extract the line index from a target's cartLineId

function getTargetLineIndex(target) {

return parseInt(target.cartLineId.slice(-1));

}

// Helper function to calculate the price for a specific target based on its quantity

function calculateCurrentTargetPrice(inputCartLines, target) {

const targetLineIndex = getTargetLineIndex(target);

const targetLine = inputCartLines[targetLineIndex];

return targetLine.cost.amountPerQuantity.amount * target.quantity;

}

export function run(input) {

  // Read the total discounts cap from the shop's metafield, defaulting to -1 if not set

let totalDiscountsCap = parseFloat(input.shop.metafield?.value ?? "-1");

let totalDiscount = 0.0;

// Initialize the output structure for line discounts

let allLinesOutputDiscounts = input.cart.lines.map((line) => ({

cartLineId: line.id,

quantity: line.quantity,

allocations: [],

}));

let displayableErrors = [];

// Iterate over each discount in the input

for (const discount of input.discounts) {

    // Read the cap for the current discount from its metafield, defaulting to -1 if not set

let currentDiscountCap = parseFloat(discount.metafield?.value ?? "-1");

let currentDiscountTotal = 0.0;

// Process each discount proposal within the current discount

for (const proposal of discount.discountProposals) {

// Calculate the total price of all targets affected by the current proposal

const totalTargetsPrice = proposal.targets.reduce((total, target) => {

return total + calculateCurrentTargetPrice(input.cart.lines, target);

}, 0);

// Apply the discount to each target

for (const target of proposal.targets) {

const currentTargetPrice = calculateCurrentTargetPrice(

input.cart.lines,

target,

);

const currentTargetRatio = currentTargetPrice / totalTargetsPrice;

let lineDiscountAmount = 0.0;

if (proposal.value.__typename == "FixedAmount") {

if (proposal.value.appliesToEachItem) {

lineDiscountAmount = proposal.value.amount * target.quantity;

} else {

lineDiscountAmount = proposal.value.amount * currentTargetRatio;

}

} else if (proposal.value.__typename == "Percentage") {

lineDiscountAmount =

(proposal.value.value / 100.0) *

totalTargetsPrice *

currentTargetRatio;

}

// Check and apply caps on the discount amount

if (

currentDiscountCap >= 0.0 &&

currentDiscountTotal + lineDiscountAmount > currentDiscountCap

) {

lineDiscountAmount = currentDiscountCap - currentDiscountTotal;

displayableErrors.push({

discountId: discount.id.toString(),

reason: SINGLE_DISCOUNT_CAP_REACHED,

});

}

if (

totalDiscountsCap >= 0.0 &&

totalDiscount + lineDiscountAmount > totalDiscountsCap

) {

lineDiscountAmount = totalDiscountsCap - totalDiscount;

displayableErrors.push({

discountId: discount.id.toString(),

reason: TOTAL_DISCOUNTS_CAP_REACHED,

});

}

if (lineDiscountAmount === 0.0) {

continue;

}

totalDiscount += lineDiscountAmount;

currentDiscountTotal += lineDiscountAmount;

const targetLineIndex = getTargetLineIndex(target);

const targetAllocation = {

discountProposalId: proposal.handle,

amount: new Decimal(lineDiscountAmount),

};

allLinesOutputDiscounts[targetLineIndex].allocations.push(

targetAllocation,

);

}

// Filter out lines that have no allocations

const lineDiscounts = allLinesOutputDiscounts.filter(

(outputDiscount) => outputDiscount.allocations.length > 0,

);

// Prepare the final output structure

const output = {

lineDiscounts,

displayableErrors,

};

return output;

}

Anchor to Define discount metafieldsDefine discount metafields

Anchor to Add metafield definitions to your app configurationAdd metafield definitions to your app configuration

Add metafield definitions to your app's shopify.app.toml file to track discount caps at the discount and shop levels.

shopify.app.toml

# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration

client_id = "7e1ce6ae588ac87953ac011795fbecb9"

name = "build-a-discount-function"

handle = "build-a-discount-function"

application_url = "https://costa-tariff-quarter-mega.trycloudflare.com"

embedded = true

[build]

automatically_update_urls_on_dev = true

dev_store_url = "quickstart-3a22a586.myshopify.com"

include_config_on_deploy = true

[access_scopes]

scopes = "write_products, write_discounts, write_discounts_allocator_functions, read_products"

[auth]

redirect_urls = [

"https://costa-tariff-quarter-mega.trycloudflare.com/auth/callback",

"https://costa-tariff-quarter-mega.trycloudflare.com/auth/shopify/callback",

"https://costa-tariff-quarter-mega.trycloudflare.com/api/auth/callback"

]

[webhooks]

api_version = "2024-07"

[pos]

embedded = false

[discount.metafields.app.single_discount_cap]

name = "Single Discount Cap"

description = "Maximum reduction value for a single discount"

type = "number_decimal"

validations.min = 0

[shop.metafields.app.per_cart_cap]

name = "Maximum Discount Per Cart"

description = "Maximum discount value applied to a single cart"

type = "number_decimal"

validations.min = 0

Anchor to Deploy your app configurationDeploy your app configuration

Deploy the metafield definitions with your app:

Terminal

shopify app deploy

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.

Caution

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 React Router 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}.

app/routes/app.discounts-allocator.$functionId.jsx

import { useEffect } from "react";

import { json } from "@remix-run/node";

import { useActionData, useNavigate, useSubmit } from "@remix-run/react";

import { Page, Layout, BlockStack, Card, Banner, Text } from "@shopify/polaris";

import { authenticate } from "../shopify.server";

export const action = async ({ params, request }) => {

const functionExtensionId = params.functionId;

const registerDiscountsAllocatorMutation = `

#graphql

mutation registerDiscountsAllocator($functionExtensionId: String!) {

discountsAllocatorFunctionRegister(functionExtensionId: $functionExtensionId) {

userErrors {

code

message

field

}

if (functionExtensionId !== null) {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(registerDiscountsAllocatorMutation, {

variables: {

functionExtensionId: functionExtensionId,

});

const responseJson = await response.json();

const errors =

responseJson.data.discountsAllocatorFunctionRegister?.userErrors;

return json({ errors });

}

return json({ errors: ["No functionExtensionId provided"] });

};

export default function DiscountsAllocator() {

const actionData = useActionData();

const submitForm = useSubmit();

const navigate = useNavigate();

useEffect(() => {

if (actionData?.errors && actionData?.errors.length === 0) {

shopify.toast.show(

"Discounts Allocator Function registered successfully!",

);

}

}, [actionData]);

const errorBanner = actionData?.errors.length ? (

<Layout.Section>

<Banner

title="There were some issues with your form submission"

tone="critical"

<ul>

{actionData?.errors?.map((error, index) => {

return <li key={`${index}`}>{error.message}</li>;

})}

</ul>

</Banner>

</Layout.Section>

) : null;

const actions = {

backAction: {

content: "Home",

onAction: () => navigate("/app"),

primaryAction: {

content: "Register Discounts allocator",

onAction: () => submitForm({}, { method: "post" }),

};

return (

<Layout.Section>

<Card>

Add more awesome details about your allocator here! (Like

ability to add metafields)

</Text>

</Card>

</Layout.Section>

{errorBanner}

</Layout>

</BlockStack>

</Page>

);

}

Anchor to Add an ,[object Object], function to handle form submissionAdd an `action` function to handle form submission

Add an action function to app.discounts-allocator.$functionId.jsx to handle the form submission. This function calls the discountsAllocatorFunctionRegister mutation to register the Discounts Allocator Function.

app/routes/app.discounts-allocator.$functionId.jsx

import { useEffect } from "react";

import { json } from "@remix-run/node";

import { useActionData, useNavigate, useSubmit } from "@remix-run/react";

import { Page, Layout, BlockStack, Card, Banner, Text } from "@shopify/polaris";

import { authenticate } from "../shopify.server";

export const action = async ({ params, request }) => {

const functionExtensionId = params.functionId;

const registerDiscountsAllocatorMutation = `

#graphql

mutation registerDiscountsAllocator($functionExtensionId: String!) {

discountsAllocatorFunctionRegister(functionExtensionId: $functionExtensionId) {

userErrors {

code

message

field

}

if (functionExtensionId !== null) {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(registerDiscountsAllocatorMutation, {

variables: {

functionExtensionId: functionExtensionId,

});

const responseJson = await response.json();

const errors =

responseJson.data.discountsAllocatorFunctionRegister?.userErrors;

return json({ errors });

}

return json({ errors: ["No functionExtensionId provided"] });

};

export default function DiscountsAllocator() {

const actionData = useActionData();

const submitForm = useSubmit();

const navigate = useNavigate();

useEffect(() => {

if (actionData?.errors && actionData?.errors.length === 0) {

shopify.toast.show(

"Discounts Allocator Function registered successfully!",

);

}

}, [actionData]);

const errorBanner = actionData?.errors.length ? (

<Layout.Section>

<Banner

title="There were some issues with your form submission"

tone="critical"

<ul>

{actionData?.errors?.map((error, index) => {

return <li key={`${index}`}>{error.message}</li>;

})}

</ul>

</Banner>

</Layout.Section>

) : null;

const actions = {

backAction: {

content: "Home",

onAction: () => navigate("/app"),

primaryAction: {

content: "Register Discounts allocator",

onAction: () => submitForm({}, { method: "post" }),

};

return (

<Layout.Section>

<Card>

Add more awesome details about your allocator here! (Like

ability to add metafields)

</Text>

</Card>

</Layout.Section>

{errorBanner}

</Layout>

</BlockStack>

</Page>

);

}

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.

app/routes/app.discounts-allocator.$functionId.jsx

import { useEffect } from "react";

import { json } from "@remix-run/node";

import { useActionData, useNavigate, useSubmit } from "@remix-run/react";

import { Page, Layout, BlockStack, Card, Banner, Text } from "@shopify/polaris";

import { authenticate } from "../shopify.server";

export const action = async ({ params, request }) => {

const functionExtensionId = params.functionId;

const registerDiscountsAllocatorMutation = `

#graphql

mutation registerDiscountsAllocator($functionExtensionId: String!) {

discountsAllocatorFunctionRegister(functionExtensionId: $functionExtensionId) {

userErrors {

code

message

field

}

if (functionExtensionId !== null) {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(registerDiscountsAllocatorMutation, {

variables: {

functionExtensionId: functionExtensionId,

});

const responseJson = await response.json();

const errors =

responseJson.data.discountsAllocatorFunctionRegister?.userErrors;

return json({ errors });

}

return json({ errors: ["No functionExtensionId provided"] });

};

export default function DiscountsAllocator() {

const actionData = useActionData();

const submitForm = useSubmit();

const navigate = useNavigate();

useEffect(() => {

if (actionData?.errors && actionData?.errors.length === 0) {

shopify.toast.show(

"Discounts Allocator Function registered successfully!",

);

}

}, [actionData]);

const errorBanner = actionData?.errors.length ? (

<Layout.Section>

<Banner

title="There were some issues with your form submission"

tone="critical"

<ul>

{actionData?.errors?.map((error, index) => {

return <li key={`${index}`}>{error.message}</li>;

})}

</ul>

</Banner>

</Layout.Section>

) : null;

const actions = {

backAction: {

content: "Home",

onAction: () => navigate("/app"),

primaryAction: {

content: "Register Discounts allocator",

onAction: () => submitForm({}, { method: "post" }),

};

return (

<Layout.Section>

<Card>

Add more awesome details about your allocator here! (Like

ability to add metafields)

</Text>

</Card>

</Layout.Section>

{errorBanner}

</Layout>

</BlockStack>

</Page>

);

}

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.

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 dev store.
In your dev store, navigate to /app/discounts-allocator/function-handle and register your Discounts Allocator Function.

Troubleshooting

If you receive a Could not find Function error, then confirm the following:

shopify app dev is running.
The function handle is correct.
Your app has the write_discounts access 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 dev 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.

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.

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.

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.

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_CAP value you set in the metafield.

Anchor to Deploy your appDeploy your app

When you're ready to release your changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

Navigate to your app directory.
Run the following command.

Optionally, you can provide a name or message for the version using the --version and --message flags.

Terminal
shopify app deploy

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Tip

If you want to create a version, but avoid releasing it to users, then run the deploy command with a --no-release flag. You can release the unreleased app version using Shopify CLI's release command, or through the Dev Dashboard.

shopify.app.toml

# Learn more about configuring your app at https://shopify.dev/docs/apps/tools/cli/configuration

client_id = "7e1ce6ae588ac87953ac011795fbecb9"

name = "build-a-discount-function"

handle = "build-a-discount-function"

application_url = "https://costa-tariff-quarter-mega.trycloudflare.com"

embedded = true

[build]

automatically_update_urls_on_dev = true

dev_store_url = "quickstart-3a22a586.myshopify.com"

include_config_on_deploy = true

[access_scopes]

scopes = "write_products, write_discounts, write_discounts_allocator_functions, read_products"

[auth]

redirect_urls = [

"https://costa-tariff-quarter-mega.trycloudflare.com/auth/callback",

"https://costa-tariff-quarter-mega.trycloudflare.com/auth/shopify/callback",

"https://costa-tariff-quarter-mega.trycloudflare.com/api/auth/callback"

]

[webhooks]

api_version = "2024-07"

[pos]

embedded = false

[discount.metafields.app.single_discount_cap]

name = "Single Discount Cap"

description = "Maximum reduction value for a single discount"

type = "number_decimal"

validations.min = 0

[shop.metafields.app.per_cart_cap]

name = "Maximum Discount Per Cart"

description = "Maximum discount value applied to a single cart"

type = "number_decimal"

validations.min = 0

extensions/discounts-allocator-js/src/run.graphql

query RunInput {

discounts {

title

code

discountApplicationStrategy

discountProposals

{

handle

message

value {

__typename

... on FixedAmount {

amount

appliesToEachItem

}

... on Percentage {

value

}

targets{

cartLineId

quantity

}

metafield(namespace: "$app", key: "single_discount_cap") {

value

}

presentmentCurrencyRate

cart {

lines {

quantity

cost {

amountPerQuantity {

amount

}

merchandise {

__typename

... on ProductVariant {

title

product {

title

}

shop {

metafield(namespace: "$app", key: "per_cart_cap") {

value

}

extensions/discounts-allocator-js/src/run.js

import { Decimal } from "decimal.js";

const TOTAL_DISCOUNTS_CAP_REACHED =

"Maximum discount limit reached for this cart";

const SINGLE_DISCOUNT_CAP_REACHED =

"Maximum discount limit reached for this discount";

// Helper function to extract the line index from a target's cartLineId

function getTargetLineIndex(target) {

return parseInt(target.cartLineId.slice(-1));

}

// Helper function to calculate the price for a specific target based on its quantity

function calculateCurrentTargetPrice(inputCartLines, target) {

const targetLineIndex = getTargetLineIndex(target);

const targetLine = inputCartLines[targetLineIndex];

return targetLine.cost.amountPerQuantity.amount * target.quantity;

}

export function run(input) {

// Read the total discounts cap from the shop's metafield, defaulting to -1 if not set

let totalDiscountsCap = parseFloat(input.shop.metafield?.value ?? "-1");

let totalDiscount = 0.0;

// Initialize the output structure for line discounts

let allLinesOutputDiscounts = input.cart.lines.map((line) => ({

cartLineId: line.id,

quantity: line.quantity,

allocations: [],

}));

let displayableErrors = [];

// Iterate over each discount in the input

for (const discount of input.discounts) {

// Read the cap for the current discount from its metafield, defaulting to -1 if not set

let currentDiscountCap = parseFloat(discount.metafield?.value ?? "-1");

let currentDiscountTotal = 0.0;

// Process each discount proposal within the current discount

for (const proposal of discount.discountProposals) {

// Calculate the total price of all targets affected by the current proposal

const totalTargetsPrice = proposal.targets.reduce((total, target) => {

return total + calculateCurrentTargetPrice(input.cart.lines, target);

}, 0);

// Apply the discount to each target

for (const target of proposal.targets) {

const currentTargetPrice = calculateCurrentTargetPrice(

input.cart.lines,

target,

);

const currentTargetRatio = currentTargetPrice / totalTargetsPrice;

let lineDiscountAmount = 0.0;

if (proposal.value.__typename == "FixedAmount") {

if (proposal.value.appliesToEachItem) {

lineDiscountAmount = proposal.value.amount * target.quantity;

} else {

lineDiscountAmount = proposal.value.amount * currentTargetRatio;

}

} else if (proposal.value.__typename == "Percentage") {

lineDiscountAmount =

(proposal.value.value / 100.0) *

totalTargetsPrice *

currentTargetRatio;

}

// Check and apply caps on the discount amount

if (

currentDiscountCap >= 0.0 &&

currentDiscountTotal + lineDiscountAmount > currentDiscountCap

) {

lineDiscountAmount = currentDiscountCap - currentDiscountTotal;

displayableErrors.push({

discountId: discount.id.toString(),

reason: SINGLE_DISCOUNT_CAP_REACHED,

});

}

if (

totalDiscountsCap >= 0.0 &&

totalDiscount + lineDiscountAmount > totalDiscountsCap

) {

lineDiscountAmount = totalDiscountsCap - totalDiscount;

displayableErrors.push({

discountId: discount.id.toString(),

reason: TOTAL_DISCOUNTS_CAP_REACHED,

});

}

if (lineDiscountAmount === 0.0) {

continue;

}

totalDiscount += lineDiscountAmount;

currentDiscountTotal += lineDiscountAmount;

const targetLineIndex = getTargetLineIndex(target);

const targetAllocation = {

discountProposalId: proposal.handle,

amount: new Decimal(lineDiscountAmount),

};

allLinesOutputDiscounts[targetLineIndex].allocations.push(

targetAllocation,

);

}

// Filter out lines that have no allocations

const lineDiscounts = allLinesOutputDiscounts.filter(

(outputDiscount) => outputDiscount.allocations.length > 0,

);

// Prepare the final output structure

const output = {

lineDiscounts,

displayableErrors,

};

return output;

}

app/routes/app.discounts-allocator.$functionId.jsx

import { useEffect } from "react";

import { json } from "@remix-run/node";

import { useActionData, useNavigate, useSubmit } from "@remix-run/react";

import { Page, Layout, BlockStack, Card, Banner, Text } from "@shopify/polaris";

import { authenticate } from "../shopify.server";

export const action = async ({ params, request }) => {

const functionExtensionId = params.functionId;

const registerDiscountsAllocatorMutation = `

#graphql

mutation registerDiscountsAllocator($functionExtensionId: String!) {

discountsAllocatorFunctionRegister(functionExtensionId: $functionExtensionId) {

userErrors {

code

message

field

}

if (functionExtensionId !== null) {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(registerDiscountsAllocatorMutation, {

variables: {

functionExtensionId: functionExtensionId,

});

const responseJson = await response.json();

const errors =

responseJson.data.discountsAllocatorFunctionRegister?.userErrors;

return json({ errors });

}

return json({ errors: ["No functionExtensionId provided"] });

};

export default function DiscountsAllocator() {

const actionData = useActionData();

const submitForm = useSubmit();

const navigate = useNavigate();

useEffect(() => {

if (actionData?.errors && actionData?.errors.length === 0) {

shopify.toast.show(

"Discounts Allocator Function registered successfully!",

);

}

}, [actionData]);

const errorBanner = actionData?.errors.length ? (

<Layout.Section>

<Banner

title="There were some issues with your form submission"

tone="critical"

<ul>

{actionData?.errors?.map((error, index) => {

return <li key={`${index}`}>{error.message}</li>;

})}

</ul>

</Banner>

</Layout.Section>

) : null;

const actions = {

backAction: {

content: "Home",

onAction: () => navigate("/app"),

primaryAction: {

content: "Register Discounts allocator",

onAction: () => submitForm({}, { method: "post" }),

};

return (

<Layout.Section>

<Card>

Add more awesome details about your allocator here! (Like

ability to add metafields)

</Text>

</Card>

</Layout.Section>

{errorBanner}

</Layout>

</BlockStack>

</Page>

);

}

extensions/discounts-allocator-js/shopify.extension.toml

api_version = "unstable"

[[extensions]]

handle = "discounts-allocator-js"

name = "t:name"

description = "t:description"

type = "function"

uid = "ccf7edf4-a12d-b60a-9d4a-1cb8691864d6ec6a83e2"

[[extensions.targeting]]

target = "purchase.discounts-allocator.run"

input_query = "src/run.graphql"

export = "run"

[extensions.build]

command = ""

path = "dist/function.wasm"

[extensions.ui.paths]

create = "/"

details = "/app/discounts-allocator/:functionId"

graphql_examples/singleCapDiscountMutation.graphql

mutation {

metafieldsSet(

metafields: [

{

key: "single_discount_cap"

namespace: "$app"

ownerId: "gid://shopify/DiscountNode/<DISCOUNT_ID>"

type: "number_decimal"

value: "<SINGLE_DISCOUNT_CAP>"

}

]

) {

metafields {

key

namespace

value

createdAt

updatedAt

}

userErrors {

field

message

code

}

graphql_examples/perCartDiscountMetafieldMutation.graphql

mutation {

metafieldsSet(

metafields: [

{

key: "per_cart_cap"

namespace: "$app"

ownerId: "gid://shopify/Shop/<SHOP_ID>"

type: "number_decimal"

value: "<PER_CART_CAP>"

}

]

) {

metafields {

key

namespace

value

createdAt

updatedAt

}

userErrors {

field

message

code

}

Anchor to Tutorial complete!Tutorial complete!

You've successfully created a Discounts Allocator Function that uses metafields to help define its custom allocation logic. Now, you can use this Function to apply discounts.

Anchor to Next StepsNext Steps

Build a UI extension to configure your discount Function

Add configuration to your discounts experience using metafields and build a user interface for your Function.

Build a React Router app to configure your discount Function

Add configuration to your discounts experience using metafields and build a user interface for your Function.

Review the UX guidelines

Review the UX guidelines to learn how to implement discounts in user interfaces.

Learn more about deploying app versions

Learn more about deploying app versions to Shopify

Was this page helpful?

Anchor to What you'll learnWhat you'll learn

Requirements

Project

Anchor to Update your app's access scopesUpdate your app's access scopes

Anchor to Update the ,[object Object], fileUpdate the shopify.app.toml file

Anchor to Start your app to preview changesStart your app to preview changes

Anchor to Create the Discounts Allocator FunctionCreate the Discounts Allocator Function

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

Anchor to Update the function logicUpdate the function logic

Anchor to Replace the content of ,[object Object], , file.Replace the content of run.js file.

Anchor to Define discount metafieldsDefine discount metafields

Anchor to Add metafield definitions to your app configurationAdd metafield definitions to your app configuration

Anchor to Deploy your app configurationDeploy your app configuration

Anchor to Create the frontend UI for registering your Discounts Allocator FunctionCreate the frontend UI for registering your Discounts Allocator Function

Anchor to Create a new route for the Discounts Allocator FunctionCreate a new route for the Discounts Allocator Function

Anchor to Add an ,[object Object], function to handle form submissionAdd an action function to handle form submission

Anchor to Create the UI for registering the Discounts Allocator FunctionCreate the UI for registering the Discounts Allocator Function

Anchor to Update the UI pathUpdate the UI path

Anchor to Register your Discounts Allocator FunctionRegister your Discounts Allocator Function

Anchor to Create a discount and build a cartCreate a discount and build a cart

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

Anchor to Replace the placeholdersReplace the placeholders

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

Anchor to Replace the placeholdersReplace the placeholders

Anchor to Test your Discounts Allocator Function with a Per Cart CapTest your Discounts Allocator Function with a Per Cart Cap

Anchor to Deploy your appDeploy your app

Anchor to Tutorial complete!Tutorial complete!

Anchor to Next StepsNext Steps

Anchor to Update the ,[object Object], fileUpdate the `shopify.app.toml` file

Anchor to Replace the content of the extension's ,[object Object], fileReplace the content of the extension's `run.graphql` file

Anchor to Replace the content of ,[object Object], , file.Replace the content of `run.js` file.

Anchor to Add an ,[object Object], function to handle form submissionAdd an `action` function to handle form submission