Discounts Allocator Function
Building a Discounts Allocator Function will enable you to have a higher degree of customization when you define discount allocation strategies. With this Function, you can implement custom logic to distribute discounts across line items.
What you'll learn
Anchor link to section titled "What you'll learn"In this example, you create a Discounts Allocator Function that uses two metafields to help define its custom allocation logic. The first metafield will be applied to a discount, setting a max amount per discount application. If the discount is 50 percent off, then a max amount can be set to not exceed X number of dollars. The second metafield will be applied to the shop, setting a max discounted amount per cart.
Refer to a sample app with a completed example
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account.
- You've created a development store.
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.
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: Update your app access scopes
Anchor link to section titled "Step 1: Update your app access scopes"You must request the write_discounts_allocator_functions
access scope to give your app the permissions it needs to create and update discounts.
In
shopify.app.toml
, located in the root of your app, add thewrite_discounts_allocator_functions
scope:Deploy your updated configuration to Shopify:
Restart your app:
Use the URL provided by Shopify CLI to open or re-install your app. You should be prompted to accept the new access scope permissions in your store.
Step 2: Create the Discounts Allocator Function
Anchor link to section titled "Step 2: Create the Discounts Allocator Function"To create your Discounts Allocator Function, you'll do the following: - Generate a starter Function with Shopify CLI. - Specify the inputs for your Function with an input query. - Implement the Function logic using either JavaScript or Rust.
Navigate to your app directory:
Run the following command to create a new Discounts Allocator Function extension:
Choose the language that you want to use. For this tutorial, select either JavaScript or Rust.
Navigate to
extensions/discounts-allocator
.Replace the contents of
src/run.graphql
file with the following code:run.graphql
defines the input for the Function target. The query is slightly different in JavaScript and Rust due to code generation requirements.If you're using JavaScript, then run the following command to regenerate types based on your input query:
Replace the content of the
src/run.js
orsrc/run.rs
file with the following code:
Step 3: Setting Shop and Discount Metafield Definitions
Anchor link to section titled "Step 3: Setting Shop and Discount Metafield Definitions"Using GraphiQL App (Install it from here) run the following mutations in your shop:
Create the discount metafield definition:
Create the shop metafield definition:
Step 4: Create the frontend UI for registering your Allocator Function
Anchor link to section titled "Step 4: Create the frontend UI for registering your Allocator Function"After a merchant installs your app, they will need to register the allocator function in order for it to be actively allocating discounts. This takes precedence over most discount features that are built by Shopify.
In
app/routes
, create a new file namedapp.discounts-allocator.$functionId.jsx
.
The Shopify Remix app template uses file-based routing, so the filename determines the page's URL. The $
prefix indicates functionId
is a dynamic segment. The path for this page is /app/discounts-allocator/{functionId}
.
- Add the following code in
app.discounts-allocator.$functionId.jsx
:
The action
function handles submitting the form data to Shopify to create the discount. The DiscountsAllocator
function renders the page and form components using Polaris components, and Remix hooks.
Step 5: Configure the details UI path for your Function
Anchor link to section titled "Step 5: Configure the details UI path for your Function"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.
In extensions/discounts-allocator/shopify.extension.toml
, populate the create and module setting in the [ui] section. This change is automatically applied as long as you're running dev
.
Step 6: Test your Discounts Allocator Function
Anchor link to section titled "Step 6: Test your Discounts Allocator Function"If your app isn't already running, then start it using Shopify CLI.
From your Shopify admin, go to Discounts.
If you have existing discounts from previous tutorials, then click the checkbox next to each of them, and then click Deactivate discounts.
Click the Create discount button near the top right of your page and select Amount off products. Now 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 and notice the discount amount applied is 50 percent off.
To utilize the
single-discount-cap
capability of your allocator, go to the GraphiQL App and run the following mutation in your shop:
Go to the cart you created and refresh the page, notice the discounts will be capped at the
SINGLE_DISCOUNT_CAP
value you set in the metafield.Now to utilize the
per-cart-cap
capability of your allocator, go to the GraphiQL App and run the following mutation in your shop: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, notice the total savings will be capped at the
PER_CART_CAP
value you set in the metafield.