> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discount Entitlements

> Apply dynamic discounts to products in Layers search and browse results through the Abra Promotions integration, including price overrides and badge logic.

## 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](https://abrapromotions.com/?ref=docs.uselayers.com), 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.

```json theme={null}
{
  "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:

<ParamField body="all" type="boolean">
  When `true`, applies the discount to all products in the catalog. When `false`, discount is limited to specified products, variants, or collections.
</ParamField>

<ParamField body="products" type="string[]">
  Array of product IDs or handles that qualify for the discount. Can be empty if using `all: true` or targeting specific variants/collections.
</ParamField>

<ParamField body="variants" type="string[] | number[]">
  Array of variant IDs that qualify for the discount. Allows targeting specific product variants rather than entire products.
</ParamField>

<ParamField body="collections" type="string[]">
  Array of collection handles that qualify for the discount. All products within these collections will receive the discount.
</ParamField>

### Discount configuration

The `discount` object defines the discount to apply:

<ParamField body="type" 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
</ParamField>

<ParamField body="value" type="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.
</ParamField>

## Examples

### Store-wide percentage discount

Apply a 10% discount to all products:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
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:

```json theme={null}
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, Layers uses the most advantageous discount for the customer:

```json theme={null}
{
  "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

### 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 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.

## Related features

* [Browse API](/api-reference/browse) - Collection browsing with discount support
* [Search API](/api-reference/search) - Semantic search with discount support
* [Sorting](/platform/sorting) - Custom sort orders that work with discounted prices
* [Filtering](/engine/filtering) - Price filtering with discount awareness
* [Abra Promotions](https://abrapromotions.com/?ref=docs.uselayers.com) - Partner platform for advanced promotional strategies