Migrate from deprecated discount APIs to the Discount API

Anchor to Update the API versionUpdate the API version

In your shopify.extension.toml file, update to the latest stable API version. This example uses 2025-04.

Anchor to Update your Function targetsUpdate your Function targets

The Discount API enables you to target multiple discount classes with a single discount, so you can create one discount that reduces costs on orders, products, and shipping. To update your existing Discount Functions to use the Discount API, you'll need to update the run targets.

The following are the new run targets define where your discount can be applied:

• cart.lines.discounts.generate.run: Applies discounts to cart lines and order subtotal.
• cart.delivery-options.discounts.generate.run: Applies discounts to delivery options.

For detailed specifications of these targets see the targets documentation.

Anchor to Update the Function logic for cart DiscountsUpdate the Function logic for cart Discounts

The Discount API requires you to update your Function. This example returns operations which contain orderDiscountsAdd and productDiscountsAdd.

Anchor to Update the Function logic for delivery DiscountsUpdate the Function logic for delivery Discounts

The new Discount API requires you to update function. This example returns operations which contain deliveryDiscountsAdd.

Anchor to Update the input query fieldsUpdate the input query fields

If your Function's input query requests discountNode, then update the field from discountNode to discount.

Anchor to Re-generate the schemaRe-generate the schema

If you modified your Function's input or output, you must regenerate the new Discount API schema to support the new properties that are available to the Function input and output.

Anchor to Create the discount with GraphiQLCreate the discount with GraphiQL

In this step, you'll use the GraphiQL interface to create a product, order and shipping discount backed by the Function you deployed in the previous step. This involves querying your Function's ID and using it to create the discount with the appropriate GraphQL mutation.

Anchor to Use the GraphiQL interface to create a discountUse the GraphiQL interface to create a discount

1. Open the GraphiQL interface using the Shopify CLI by pressing g.
2. In the GraphiQL interface, in the API Version field, select version 2025-10 or higher.

Anchor to Get the handle of your FunctionGet the handle of your Function

1. Use your function handle in GraphQL mutations instead of querying for the function ID.

   Your function handle is defined in shopify.extension.toml as handle:

   shopify.extension.toml

   Copy

   9

   1

   2

   3

   4

   5

   [[extensions]]

   name = "discount-function"

   handle = "discount-function-rs"

   type = "function"

   uid = "3d664979-ccd6-e9dd-4497-41289ece62373715032a"
   Note

   If you're upgrading to API version 2025-10 or later, you no longer need to query for function IDs. Use your stable function handle instead, which remains consistent across environments.

Anchor to Create the discountCreate the discount

Use the discountAutomaticAppCreate mutation to create an automatic discount.

1. Add the Shopify Function handle from the previous step as the value for the functionHandle input.

2. Add the discountClasses field to your mutation.

   
   

You should receive a GraphQL response that includes the ID of the created product discount. If the response includes any messages under userErrors, then review the errors, check that your mutation and functionHandle are correct, and try the request again.

After using GraphiQL to create the discount, you can test the discount and the newly migrated function.

Anchor to Trigger the discount on your dev storeTrigger the discount on your dev store

1. From your Shopify admin, click Discounts. You should now see the Cart line, order and shipping that you created.
   

2. Deactivate or delete all other discounts to ensure that the Cart line, order and shipping discount is the only active discount.

3. Open your dev store and build a cart with a single item in it. After you navigate to the checkout page and fill in your shipping address, you'll see the discounts applied to the shipping rates.

Anchor to Review the Function executionReview the Function execution

1. In the terminal where shopify app dev is running, review your Function executions.

   When testing Functions on development stores, the dev output shows Function executions, debug logs you've added, and a link to a local file containing full execution details.

2. In a new terminal window, use the Shopify CLI command app function replay to replay a Function execution locally. This lets you debug your Function without triggering it again on Shopify.

   Terminal

   Copy

   $

   $

   shopify app function replay

3. Select the Function execution from the top of the list. Press q to quit when you are finished debugging.