Discount Entitlements

Overview

Discount Entitlements enable you to apply dynamic discounts to products in both Search and Browse API responses. This feature is part of Layers’ partnership with Abra Promotions, ensuring that sorting and filtering operations work correctly with dynamically discounted prices. When you provide discount entitlements in API requests, Layers automatically adjusts product pricing in the response. It also applies the discounts when sorting by price or filtering by price ranges. This ensures customers see accurate, discounted pricing throughout their shopping experience.

Use cases

Discount entitlements are ideal for scenarios where you need to:

Apply percentage-based discounts to specific products, variants, or collections
Offer fixed amount discounts on selected items
Implement store-wide sales or promotions
Create targeted discount campaigns for specific product categories
Ensure accurate price sorting and filtering with active promotions

Schema

The discount entitlements schema consists of two main components: the entitlement criteria and the discount configuration.

{
  "entitled": {
    "all": true | false,
    "products": ["product_id or handle"],
    "variants": ["variant_id"],
    "collections": ["collection_handle"],
    "conditions": {
      "conditional": "AND" | "OR",
      "expressions": [
        {
          "property": "tags",
          "operator": "contains",
          "values": ["sale"]
        }
      ]
    }
  },
  "discount": {
    "type": "PERCENTAGE" | "FIXED_AMOUNT",
    "value": number
  }
}

Entitlement criteria

The entitled object defines which products qualify for the discount:

all

boolean

When true, applies the discount to all products in the catalog. When false, discount is limited to specified products, variants, or collections.

products

string[]

Array of product IDs or handles that qualify for the discount. Can be empty if using all: true or targeting specific variants/collections.

variants

string[] | number[]

Array of variant IDs that qualify for the discount. Allows targeting specific product variants rather than entire products.

collections

string[]

Array of collection handles that qualify for the discount. All products within these collections will receive the discount.

conditions

object

A filter group that qualifies products for the discount based on their attributes (for example, tags, vendor, or any filterable property). Uses the same shape as the top-level filter_group parameter, with a conditional (AND or OR) and an array of expressions. Products matching the condition receive the discount in addition to any products targeted by all, products, variants, or collections on the same entitlement.

Discount configuration

The discount object defines the discount to apply:

type

string

The discount type. Must be either:

PERCENTAGE - Discount is a percentage off the original price
FIXED_AMOUNT - Discount is a fixed currency amount off the original price

value

number

The discount value. For PERCENTAGE type, this must be a number between 0 and 100 (e.g., 10 for 10% off). Values outside this range will be rejected with a validation error. For FIXED_AMOUNT type, this is the currency amount to deduct from the price.

Examples

Store-wide percentage discount

Apply a 10% discount to all products:

{
  "entitled": {
    "all": true,
    "products": [],
    "variants": [],
    "collections": []
  },
  "discount": {
    "type": "PERCENTAGE",
    "value": 10
  }
}

Fixed amount discount on specific products

Apply a $5.00 discount to specific products by handle:

{
  "entitled": {
    "all": false,
    "products": ["lip-balm", "lip-scrub"],
    "variants": [],
    "collections": []
  },
  "discount": {
    "type": "FIXED_AMOUNT",
    "value": 5.00
  }
}

Percentage discount on specific variants

Apply a 20% discount to specific product variants:

{
  "entitled": {
    "all": false,
    "products": [],
    "variants": [48307912376633, 48307001262393],
    "collections": []
  },
  "discount": {
    "type": "PERCENTAGE",
    "value": 20
  }
}

Collection-wide discount

Apply a 15% discount to all products in a collection:

{
  "entitled": {
    "all": false,
    "products": [],
    "variants": [],
    "collections": ["collection-handle"]
  },
  "discount": {
    "type": "PERCENTAGE",
    "value": 15
  }
}

Condition-based discount

Apply a 30% discount to every product tagged discount:30% off, without listing product IDs:

{
  "entitled": {
    "all": false,
    "products": [],
    "variants": [],
    "collections": [],
    "conditions": {
      "conditional": "AND",
      "expressions": [
        {
          "property": "tags",
          "operator": "contains",
          "values": ["discount:30% off"]
        }
      ]
    }
  },
  "discount": {
    "type": "PERCENTAGE",
    "value": 30
  }
}

Combine multiple expressions with AND to require every condition, or OR to match any. Conditions can also be paired with products, variants, or collections on the same entitlement — the discount applies to products matching any of those scopes.

{
  "entitled": {
    "all": false,
    "products": ["featured-product"],
    "variants": [],
    "collections": [],
    "conditions": {
      "conditional": "AND",
      "expressions": [
        {
          "property": "vendor",
          "operator": "eq",
          "values": ["Acme"]
        },
        {
          "property": "tags",
          "operator": "contains",
          "values": ["clearance"]
        }
      ]
    }
  },
  "discount": {
    "type": "PERCENTAGE",
    "value": 20
  }
}

See Filtering for the full list of supported properties and operators.

Using with Browse API

To apply discount entitlements when browsing a collection, include the discountEntitlements array in your Browse API request:

POST /browse/{collection_handle}
{
  "attributes": [
    "id",
    "handle",
    "title",
    "first_or_matched_variant"
  ],
  "filter_group": {
    "conditional": "AND",
    "expressions": [
      {
        "property": "options.title",
        "operator": "eq",
        "values": ["S"]
      }
    ]
  },
  "retrieveFacetCount": true,
  "pagination": {
    "page": 1,
    "limit": 10
  },
  "sort_order_code": "price_low_to_high",
  "discountEntitlements": [
    {
      "entitled": {
        "all": false,
        "products": ["my-handle"],
        "variants": [],
        "collections": []
      },
      "discount": {
        "type": "PERCENTAGE",
        "value": 50
      }
    }
  ]
}

Using with Search API

To apply discount entitlements when searching, include the discountEntitlements array in your Search API request:

POST /search/{searchQuery}/execute
{
  "attributes": [
    "id",
    "handle",
    "title",
    "price_range"
  ],
  "pagination": {
    "page": 1,
    "limit": 20
  },
  "sort_order_code": "price_low_to_high",
  "discountEntitlements": [
    {
      "entitled": {
        "all": false,
        "products": [],
        "variants": [12345],
        "collections": ["sale-items"]
      },
      "discount": {
        "type": "PERCENTAGE",
        "value": 25
      }
    }
  ]
}

To apply discount entitlements when fetching collection facets (for example, to render a discount-aware price slider), include the discountEntitlements array in your Facets API request. variants.price counts and ranges are computed from each variant’s discounted price:

POST /storefront/v1/summer-collection/facets
{
  "facets": ["vendor", "variants.price"],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "discountEntitlements": [
    {
      "entitled": {
        "all": false,
        "products": [],
        "variants": [],
        "collections": ["summer-collection"]
      },
      "discount": {
        "type": "PERCENTAGE",
        "value": 20
      }
    }
  ]
}

Multiple discount entitlements

You can provide multiple discount entitlements in a single request. When multiple entitlements apply to the same product, Layers uses the most advantageous discount for the customer:

{
  "discountEntitlements": [
    {
      "entitled": {
        "all": false,
        "products": [],
        "variants": [],
        "collections": ["summer-collection"]
      },
      "discount": {
        "type": "PERCENTAGE",
        "value": 15
      }
    },
    {
      "entitled": {
        "all": false,
        "products": ["featured-product"],
        "variants": [],
        "collections": []
      },
      "discount": {
        "type": "PERCENTAGE",
        "value": 25
      }
    }
  ]
}

Reading applied entitlements from the response

When a Search or Browse request has discount entitlements applied, the response _meta includes a discountEntitlements array that echoes each active entitlement. This covers entitlements you pass directly and entitlements attached by a matched request transform. Use the array to render discount badges or labels on the storefront without re-deriving which entitlements matched. The key is omitted entirely when no entitlements are applied, so you can treat its presence as the signal that a discount is active.

{
  "_meta": {
    "discountEntitlements": [
      {
        "entitled": { "all": true },
        "discount": { "type": "PERCENTAGE", "value": 15 }
      },
      {
        "entitled": { "products": ["featured-product"] },
        "discount": { "type": "FIXED_AMOUNT", "value": 5 }
      }
    ]
  }
}

Each entry mirrors the shape you send in the request: an entitled object describing the scope and a discount object with type and value.

Important considerations

Percentage discount validation

When using the PERCENTAGE discount type, the value must be between 0 and 100. The API returns a validation error if the percentage is outside this range. For example, a value of 10 means 10% off, and a value of 100 means 100% off (free).

Price sorting

When discount entitlements are applied, price-based sort orders will use the discounted prices. This ensures products are correctly ordered according to their effective prices after discounts.

Price filtering

Price range filters will also respect discount entitlements. When filtering by price, products will be evaluated based on their discounted prices, not their original prices.

Product response

The product response reflects the discounted pricing in the price field of first_or_matched_variant, entries in the variants array, and the from/to bounds of price_range whenever a variant matches an entitlement. This keeps search and browse results consistent with what customers see on product pages.

Compare-at pricing

For every variant that matches an entitlement, compare_at_price is set to the higher of the variant’s existing compare-at price and its pre-discount price. This applies to first_or_matched_variant.compare_at_price, each entry in variants[].compare_at_price, and price_range.compare_at_price, so storefronts can render a strikethrough original price alongside the discounted price without extra bookkeeping.

If the variant had no compare-at price, the pre-discount price is used.
If the variant already had a compare-at price higher than the pre-discount price, the existing compare-at price is preserved.
Variants that do not match an entitlement are unchanged — an existing compare-at price stays as it was, and a null value stays null.

For example, a variant priced at $100 with no compare-at price that receives a 20% entitlement discount returns price: 80 and compare_at_price: 100. The same variant with an existing compare-at price of $150 returns price: 80 and compare_at_price: 150. When a product has a mix of entitled and unentitled variants, price_range.compare_at_price reflects the lowest non-null compare-at price across the product’s variants.

Browse API - Collection browsing with discount support
Search API - Semantic search with discount support
Facets API - Discount-aware facet counts and ranges
Sorting - Custom sort orders that work with discounted prices
Filtering - Price filtering with discount awareness
Abra Promotions - Partner platform for advanced promotional strategies

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

Discount Entitlements

Overview

Use cases

Schema

Entitlement criteria

Discount configuration

Examples

Store-wide percentage discount

Fixed amount discount on specific products

Percentage discount on specific variants

Collection-wide discount

Condition-based discount

Using with Browse API

Using with Search API

Using with Facets API

Multiple discount entitlements

Reading applied entitlements from the response

Important considerations

Percentage discount validation

Price sorting

Price filtering

Product response

Compare-at pricing

​Overview

​Use cases

​Schema

​Entitlement criteria

​Discount configuration

​Examples

​Store-wide percentage discount

​Fixed amount discount on specific products

​Percentage discount on specific variants

​Collection-wide discount

​Condition-based discount

​Using with Browse API

​Using with Search API

​Using with Facets API

​Multiple discount entitlements

​Reading applied entitlements from the response

​Important considerations

​Percentage discount validation

​Price sorting

​Price filtering

​Product response

​Compare-at pricing

​Related features

Overview

Use cases

Schema

Entitlement criteria

Discount configuration

Examples

Store-wide percentage discount

Fixed amount discount on specific products

Percentage discount on specific variants

Collection-wide discount

Condition-based discount

Using with Browse API

Using with Search API

Using with Facets API

Multiple discount entitlements

Reading applied entitlements from the response

Important considerations

Percentage discount validation

Price sorting

Price filtering

Product response

Compare-at pricing

Related features