Anchor to Discount Function APIDiscount Function API
The Discount Function API provides a unified schema for creating Function extensions. A single Function processes one discount (either code-based or automatic), but can apply savings across three discount classes: product, order, and shipping.
For example, one discount can simultaneously reduce both order total and delivery costs.
Shopify Functions enable you to customize Shopify's backend logic. The Discount Function API integrates this logic into the checkout flow.
You can activate a maximum of 25 Discount Functions on each store. All Discount Functions run concurrently, and have no knowledge of each other. The potential discount that a Function outputs can be combined with the candidate from another discount, in alignment with the combination and stacking rules set on the discount node.
Anchor to Use casesUse cases
- Exclusions, where the discount doesn't apply to some cart lines in the order.
- Tiered discounts on products, orders, and shipping when orders include qualifying item, subtotal, and delivery requirements.
- Discount to cartlines that contain specific properties, such as an engraving on a ring.
The fetch target is limited to custom apps installed on Shopify Plus and Enterprise stores. You'll also need to request network access for Functions, as it's not currently available on development stores or in a development preview.
Anchor to Getting startedGetting started
Scaffolding the Function using Shopify CLI automatically configures your TOML file. You can alter the default configuration to customize the way your Function operates.
Anchor to TargetsTargets
A target is an identifier in shopify.extension.toml
that specifies where you're injecting code into Shopify Function APIs, or other parts of the Shopify platform. Each target is composed of three to four namespaces. The name begins with a broad Shopify context and ends with the behavior of the extensible element.
You can't configure discount classes from a checkout UI extension.
Discount classes are assigned based on their associated Discount Function targets:
OrderDiscountCandidateTarget
,
ProductDiscountCandidateTarget
, and
DeliveryDiscountCandidateTarget
.
Anchor to Cart run targetCart run target
cart.lines.discounts.generate.run
The run target calculates and applies discounts to cart lines, orders, and shipping based on the provided cart context and discount configuration, including metafields.
When your Function is executed, Shopify provides the cart context as input to the run target, including details about cart lines, prices, quantities, buyer identity, and optionally fetch results from external providers. The target returns an ordered list of operations for calculating discounts.
For example, you might use this to generate product and order discounts, and validate discounts.
- Anchor to InputInputOBJECT
The
Input
object is the complete GraphQL schema that your Function can query as an input to generate discounts. Your Function only receives the fields that you request in the input query. To optimize performance, we highly recommend that you request only the fields that your Function requires.- Anchor to cartcart•Cart!non-null
The cart where the Function is running. A cart contains the merchandise that a customer intends to purchase and information about the customer, such as the customer's email address and phone number.
- Anchor to attributeattribute•Attribute
The custom attributes associated with a cart to store additional information. Cart attributes allow you to collect specific information from customers on the Cart page, such as order notes, gift wrapping requests, or custom product details. Attributes are stored as key-value pairs.
- •String
The key of the cart attribute to retrieve. For example,
.
Arguments
- •String!non-null
The key or name of the attribute. For example,
.
- Anchor to valuevalue•String
The value of the attribute. For example,
"true"
.
Fields
- •
- Anchor to buyerIdentitybuyer•
Identity BuyerIdentity Information about the customer that's interacting with the cart. It includes details such as the customer's email and phone number, and the total amount of money the customer has spent in the store. This information helps personalize the checkout experience and ensures that accurate pricing and delivery options are displayed to customers.
- Anchor to customercustomer•Customer
The customer that's interacting with the cart. A customer is a buyer who has an account with the store.
- Anchor to amountSpentamount•
Spent Moneynon-nullV2! The total amount that the customer has spent on orders. The amount is converted from the shop's currency to the currency of the cart using a market rate.
- Anchor to amountamount•Decimal!non-null
A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.
- Anchor to currencyCodecurrency•
Code Currencynon-nullCode! The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.
AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STN, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
- Anchor to displayNamedisplay•
Name String!non-null The full name of the customer, based on the values for
and
. If
and
aren't specified, then the value is the customer's email address. If the email address isn't specified, then the value is the customer's phone number.
- Anchor to emailemail•String
The customer's email address.
- Anchor to firstNamefirst•
Name String The customer's first name.
- Anchor to hasAnyTaghas•
Any Tag Boolean!non-null Whether the customer is associated with any of the specified tags. The customer must have at least one tag from the list to return
true
.- Anchor to hasTagshas•
Tags [Hasnon-nullTag Response!]! Whether the customer is associated with the specified tags. The customer must have all of the tags in the list to return
true
.- •[String!]!required
A comma-separated list of searchable keywords that are associated with the customer. For example,
returns customers with both the
and
Gold
tags.
Arguments
- Anchor to hasTaghas•
Tag Boolean!non-null Whether the Shopify resource has the tag.
- •String!non-null
A searchable keyword that's associated with a Shopify resource, such as a product or customer. For example, a merchant might apply the
sports
andsummer
tags to products that are associated with sportswear for summer.
Fields
- •
- •ID!non-null
A globally-unique ID for the customer.
- Anchor to lastNamelast•
Name String The customer's last name.
- Anchor to metafieldmetafield•Metafield
A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.
- Anchor to namespacenamespace•String
A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.
- •String!required
The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format
namespace.key
.
Arguments
- Anchor to jsonValuejson•
Value JSON!non-null The data that's stored in the metafield, using JSON format.
- Anchor to typetype•String!non-null
The type of data that the metafield stores in the
value
field.- Anchor to valuevalue•String!non-null
The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.
Fields
- Anchor to numberOfOrdersnumber•
Of Orders Int!non-null The total number of orders that the customer has made at the store.
- Anchor to emailemail•String
The email address of the customer that's interacting with the cart.
- Anchor to isAuthenticatedis•
Authenticated Boolean!non-null Whether the customer is authenticated through their customer account. If the customer is authenticated, then the
customer
field returns the customer's information. If the customer isn't authenticated, then thecustomer
field returnsnull
.- Anchor to phonephone•String
The phone number of the customer that's interacting with the cart.
- Anchor to purchasingCompanypurchasing•
Company PurchasingCompany The company of a B2B customer that's interacting with the cart. Used to manage and track purchases made by businesses rather than individual customers.
- Anchor to companycompany•Company!non-null
The company associated to the order or draft order.
- Anchor to createdAtcreated•
At Datenon-nullTime! The date and time (ISO 8601 format) at which the company was created in Shopify.
- Anchor to externalIdexternal•
Id String A unique externally-supplied ID for the company.
- •ID!non-null
The ID of the company.
- Anchor to metafieldmetafield•Metafield
A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.
- Anchor to namespacenamespace•String
A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.
- •String!required
The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format
namespace.key
.
Arguments
- Anchor to jsonValuejson•
Value JSON!non-null The data that's stored in the metafield, using JSON format.
- Anchor to typetype•String!non-null
The type of data that the metafield stores in the
value
field.- Anchor to valuevalue•String!non-null
The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.
Fields
- Anchor to namename•String!non-null
The name of the company.
- Anchor to updatedAtupdated•
At Datenon-nullTime! The date and time (ISO 8601 format) at which the company was last modified.
- Anchor to contactcontact•Company
Contact The company contact associated to the order or draft order.
- Anchor to createdAtcreated•
At Datenon-nullTime! The date and time (ISO 8601 format) at which the company contact was created in Shopify.
- •ID!non-null
The ID of the company.
- Anchor to localelocale•String
The company contact's locale (language).
- Anchor to titletitle•String
The company contact's job title.
- Anchor to updatedAtupdated•
At Datenon-nullTime! The date and time (ISO 8601 format) at which the company contact was last modified.
- Anchor to locationlocation•Companynon-null
Location! The company location associated to the order or draft order.
- Anchor to createdAtcreated•
At Datenon-nullTime! The date and time (ISO 8601 format) at which the company location was created in Shopify.
- Anchor to externalIdexternal•
Id String A unique externally-supplied ID for the company.
- •ID!non-null
The ID of the company.
- Anchor to localelocale•String
The preferred locale of the company location.
- Anchor to metafieldmetafield•Metafield
A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.
- Anchor to namespacenamespace•String
A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.
- •String!required
The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format
namespace.key
.
Arguments
- Anchor to jsonValuejson•
Value JSON!non-null The data that's stored in the metafield, using JSON format.
- Anchor to typetype•String!non-null
The type of data that the metafield stores in the
value
field.- Anchor to valuevalue•String!non-null
The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.
Fields
- Anchor to namename•String!non-null
The name of the company location.
- Anchor to updatedAtupdated
At