Skip to main content

​
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 discount entitlements are provided in API requests, Layers automatically adjusts product pricing in the response and 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"]
  },
  "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.

​
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 is the percentage (e.g., 10 for 10% off). 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
  }
}

​
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
      }
    }
  ]
}

​
Multiple Discount Entitlements

You can provide multiple discount entitlements in a single request. When multiple entitlements apply to the same product, the system will use 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
      }
    }
  ]
}

​
Important Considerations

​
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 will reflect the discounted pricing in the first_or_matched_variant.price field when discount entitlements are applied. This ensures consistency between what customers see in search/browse results and what they’ll see on product pages. The first_or_matched_variant.compare_at_price is not updated.
  • Browse API - Collection browsing with discount support
  • Search API - Semantic search with discount support
  • Sorting - Custom sort orders that work with discounted prices
  • Filtering - Price filtering with discount awareness
  • Abra Promotions - Partner platform for advanced promotional strategies