Discount Values & Targets

Every rule group must define what discount to apply and where to apply it. This is handled through two complementary configurations: the discount value (how much to discount) and the target (what to discount). This page covers the schema, behavior, and configuration options for both.

Discount Value Types

The discount value defines the type and magnitude of the discount applied when a rule group’s conditions are met.

Schema

Field	Type	Required	Description
`type`	`string`	Yes	The discount calculation method
`value`	`number`	Yes	The discount amount or percentage
`maxDiscountAmount`	`number`	No	Maximum discount cap (in cart currency)
`message`	`string`	No	Customer-facing discount message

Supported Types

Type	Description	Value Interpretation
`percentage`	Percentage off the original price	`value` is the percentage (e.g., `10` = 10% off)
`fixedAmount`	Fixed monetary amount off	`value` is the currency amount to subtract
`fixedPrice`	Set a fixed price (reserved)	`value` is the target price per unit

Mapping to Shopify Operations

Each discount value type maps to a specific Shopify discount operation:

Discount Type	Shopify Operation	Behavior
`percentage`	`Percentage`	Reduces price by the given percentage
`fixedAmount`	`FixedAmount`	Subtracts a flat amount from the price
`fixedPrice`	`FixedAmount` (calculated)	Calculates the difference to reach the target price, then applies as a fixed amount

JSON Examples

Percentage discount:

{
  "type": "percentage",
  "value": 15,
  "message": "15% off your order"
}

Fixed amount discount with cap:

{
  "type": "fixedAmount",
  "value": 25,
  "maxDiscountAmount": 25,
  "message": "$25 off"
}

Percentage discount with maximum cap:

{
  "type": "percentage",
  "value": 20,
  "maxDiscountAmount": 50,
  "message": "20% off (up to $50)"
}

Fixed price (reserved):

{
  "type": "fixedPrice",
  "value": 9.99,
  "message": "Special price: $9.99"
}

Target Types

The target defines which items in the cart receive the discount. There are three target types corresponding to the three discount function categories: product, order, and shipping.

Product Target

Product targets apply discounts to individual cart line items. They provide fine-grained control over which products are discounted and how many units are affected.

Schema

Field	Type	Required	Description
`scope`	`string`	Yes	Determines which products are targeted
`specificVariantIds`	`string[]`	Conditional	Required when scope is `specific`
`excludedVariantIds`	`string[]`	No	Variant GIDs to exclude from the discount
`maxAffectedItems`	`number`	No	Maximum number of items to discount

Scope Behavior

Scope	Description
`all`	All cart lines are eligible for the discount
`filtered`	Only lines that pass the rule group’s product-level conditions are eligible
`specific`	Only the explicitly listed variant IDs are eligible

JSON Examples

All products:

{
  "scope": "all"
}

Filtered by conditions:

{
  "scope": "filtered",
  "maxAffectedItems": 5
}

Specific variants with exclusions:

{
  "scope": "specific",
  "specificVariantIds": [
    "gid://shopify/ProductVariant/111111111",
    "gid://shopify/ProductVariant/222222222"
  ],
  "excludedVariantIds": [
    "gid://shopify/ProductVariant/333333333"
  ]
}

All products, limited quantity:

{
  "scope": "all",
  "maxAffectedItems": 3,
  "excludedVariantIds": [
    "gid://shopify/ProductVariant/999999999"
  ]
}

Order Target

Order targets apply discounts to the order subtotal rather than individual line items.

Schema

Field	Type	Required	Description
`excludedVariantIds`	`string[]`	No	Variant GIDs to exclude from the order subtotal calculation

The order target maps to the Shopify OrderSubtotal target. The discount is applied to the overall order rather than distributed across individual lines.

JSON Examples

Simple order discount:

{}

Order discount with exclusions:

{
  "excludedVariantIds": [
    "gid://shopify/ProductVariant/444444444",
    "gid://shopify/ProductVariant/555555555"
  ]
}

Shipping Target

Shipping targets apply discounts to delivery options. They provide extensive control over which shipping methods are discounted.

Schema

Field	Type	Required	Description
`scope`	`string`	Yes	Determines which shipping options are targeted
`maxShippingPrice`	`number`	No	Maximum shipping price to discount (caps the discount)
`shippingOptionNames`	`string[]`	Conditional	Required when scope is `byName`
`shippingNameOperator`	`string`	Conditional	Required when scope is `byName`

Shipping Scopes

Scope	Description
`all`	All delivery options receive the discount
`first`	Only the first delivery option
`cheapest`	Only the cheapest delivery option
`mostExpensive`	Only the most expensive delivery option
`byName`	Only delivery options matching the specified names
`none`	No shipping discount (effectively disables shipping targeting)

Name Matching Operators

When using the byName scope, the shippingNameOperator field controls how shipping option names are matched:

Operator	Description
`equals`	Exact match against the shipping option name
`contains`	Substring match within the shipping option name
`startsWith`	Shipping option name must start with the given string
`endsWith`	Shipping option name must end with the given string

JSON Examples

Free shipping on all methods:

{
  "scope": "all"
}

Discount on cheapest option with cap:

{
  "scope": "cheapest",
  "maxShippingPrice": 10
}

Free shipping by name:

{
  "scope": "byName",
  "shippingOptionNames": ["Standard Shipping", "Economy"],
  "shippingNameOperator": "equals"
}

Discount on most expensive option:

{
  "scope": "mostExpensive",
  "maxShippingPrice": 15
}

Name matching with contains:

{
  "scope": "byName",
  "shippingOptionNames": ["Express"],
  "shippingNameOperator": "contains"
}