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

# Offers - S2S Integration

> Fetch, match and validate offers from your server and apply them to a payment using Razorpay APIs, for the whole order or for specific products.

Available in
🇮🇳 India

Use Razorpay's server-to-server (S2S) Offers APIs to find the offers that apply to a customer's order, validate them and apply them to the payment. Use them when you build your own checkout. If you use Razorpay Standard Checkout, follow [Integrate Offers with Standard Checkout](https://razorpay.com/docs/payments/offers/standard-integration) instead.

The APIs work for offers on the whole order (cart-level offers). They also let you apply offers to specific products in the cart (SKU-level offers). For example, a customer buying an iPhone and a Galaxy phone in the same order can get a separate offer on each device, processed in a single payment. Know more about how to [apply offers to specific products](#apply-offers-to-specific-products).

> [!NOTE]
>
> **For Platform Partners**
>
> These are the same APIs whether a merchant integrates directly or a platform integrates on the merchant's behalf. Same endpoints, same auth, keyed by the merchant account. There is nothing partner-specific to build against.

## Prerequisites

* [Generate the API keys](https://razorpay.com/docs/payments/dashboard/account-settings/api-keys.md) from the Dashboard. You need the `key_id` and `key_secret` to authenticate API requests.
* [Create the offers](https://razorpay.com/docs/payments/offers/create.md) you want to give from the Dashboard.

> [!NOTE]
>
> **Need an Offer the Dashboard Doesn't Cover?**
>
> The Dashboard handles merchant-funded offers. For bank-funded or brand-funded campaigns, SKU-level offers, and richer configurations (usage limits, hidden offers, schedules), your Razorpay team sets them up for you: reach out to your Key Account Manager and they will take it from there. Offer creation is not available over the API yet.

## Integration Patterns

Choose the pattern that suits how your checkout decides which offers to show.

| Pattern | APIs used | Best for |
| - | - | - |
| Catalog (offers matched on your server) | [Fetch Offers](#fetch-offers) → [Validate Offers](#validate-offers) → [Create a Payment](#create-a-payment-with-offers) | Businesses that cache the full offer catalogue on their servers and match eligibility themselves. |
| Runtime (offers matched by Razorpay) | [Match Offers](#match-offers) → [Validate Offers](#validate-offers) → [Create a Payment](#create-a-payment-with-offers) | Businesses that call Razorpay at run time to find the eligible offers. |

### Catalog Pattern Flow

1. **Sync the catalogue periodically**, for example every night. Call [Fetch Offers](#fetch-offers) to get all active offers and store them on your server.
2. **Match offers at checkout.** Compare the customer's order with your cached offers.
3. **Create an order.** Call the [Orders API](https://razorpay.com/docs/api/orders/create.md). To apply offers to specific products, also pass the cart's SKUs in `line_items`.
4. **Validate the offers before payment.** Call [Validate Offers](#validate-offers) to confirm each offer for the order and the payment instrument.
5. **Create the payment.** Call the [Create Payment API](#create-a-payment-with-offers) and pass the validated offers.
6. **Fetch the order.** Call [Fetch Order](#fetch-an-order-with-applied-offers) with `expand[]=offers` to confirm the applied offers.
7. **Block the IMEIs (Brand Offers).** If the brand requires it, call [Block an IMEI](#block-an-imei) for each device sold.

### Runtime Pattern Flow

1. **Show offers before the customer pays.** Call [Match Offers](#match-offers) without `criteria.payment_instrument`. The response lists the offers that apply to the order across all payment instruments.
2. **Create an order.** Call the [Orders API](https://razorpay.com/docs/api/orders/create.md). To apply offers to specific products, also pass the cart's SKUs in `line_items`.
3. **Show offers on the payment page.** When the customer selects a payment instrument, call [Match Offers](#match-offers) again with `criteria.payment_instrument`.
4. **Validate the offers before payment.** Call [Validate Offers](#validate-offers) to confirm each offer for the order and the payment instrument.
5. **Create the payment.** Call the [Create Payment API](#create-a-payment-with-offers) and pass the validated offers.
6. **Fetch the order.** Call [Fetch Order](#fetch-an-order-with-applied-offers) with `expand[]=offers` to confirm the applied offers.
7. **Block the IMEIs (Brand Offers).** If the brand requires it, call [Block an IMEI](#block-an-imei) for each device sold.

## Key Concepts

### Offer Structure

Every offer has one or more rules. Each rule has eligibility criteria and the benefits the customer gets when the criteria are met.

```text theme={null}
Offer
├── display_name, description, currency, terms
├── schedules[], benefits_types[]
├── usage_limits[], display_config
└── rules
    └── Rule
        ├── criteria
        │   ├── includes   (conditions that must all be true)
        │   │   ├── payment_instrument
        │   │   └── order   (order amount and SKU conditions)
        │   └── excludes   (conditions that disqualify the transaction)
        └── benefits
            └── items[]
                ├── type, applicable_on, value, max_benefit_value
                ├── limit_type, unit, tenures[]
                ├── calculated_benefit_value   (Match and Validate only)
                └── benefit_breakup[]          (Match and Validate only)
```

* `criteria.includes` lists the conditions that must all be true for the offer to apply.
* `criteria.excludes` lists the conditions that disqualify a transaction. It is an empty object `{}` when no exclusions are set.
* Razorpay evaluates the rules in an offer independently. Each rule applies either to the whole cart or to line items, never both.

### Cart-Level vs SKU-Level Offers

Offers come in two shapes, and every API in this guide handles both: cart-level offers discount the order total, SKU-level offers discount specific products. The difference shows up in these fields:

| Field | Cart-level offer | SKU-level offer |
| - | - | - |
| `criteria.includes.order.applies_to` | `cart` | `line_items` |
| `criteria.includes.order.line_item` | Absent | Present. Contains `skus`, `brands`, `min_quantity` and `min_price`. |
| `benefits.items[].applicable_on` | `cart` | `line_item` |
| `benefits.items[].calculated_benefit_value` | Flat reduction on the order total. | Sum of the discount on each eligible SKU. |
| `benefits.items[].benefit_breakup` | Absent | Present. Shows the discount on each SKU. |

All amounts in these APIs are in paise. For example, pass `150000` for ₹1,500.

## SKU-Level Offers: Merchant and Brand

SKU-level offers apply to specific products (SKUs) in the cart instead of the whole order.

### Offer Types

| Offer type | Created by | Who decides the eligible SKUs |
| - | - | - |
| Merchant offer | You, from the Razorpay Dashboard | You define which SKUs qualify. |
| Brand offer | Razorpay, on behalf of a brand such as Apple or Samsung | The brand defines the SKU list and which SKUs qualify. |

> [!NOTE]
>
> **Feature Request**
>
> Brand offers are an on-demand feature. Contact your Razorpay account manager to enable them on your account. Razorpay configures the brand offers for you.

### What to Pass

Pass the cart's SKUs at each step so Razorpay can match and apply offers to them.

| Step | What to pass |
| - | - |
| [Create an order](https://razorpay.com/docs/payments/offers/sku-offers.md#step-1-create-an-order-with-line-items) | Every SKU in the cart in `line_items`, with its unit price and quantity. The order `amount` must equal the total of `price` × `quantity` across all line items. |
| [Match Offers](#match-offers) | The SKUs in `criteria.order.line_items`, with `brand`, `price` and `quantity`. |
| [Validate Offers](#validate-offers) | For each SKU-level offer, the SKUs it applies to in `offers[].line_items`. |
| [Create a payment](#create-a-payment-with-offers) | The same `offers` array you sent to Validate Offers. |
| [Fetch the order](#fetch-an-order-with-applied-offers) | Nothing extra. `benefit_breakup` in the response shows the discount on each SKU. |

To apply SKU and Brand Offers on Razorpay Standard Checkout instead, see [SKU and Brand Offers on Standard Checkout](https://razorpay.com/docs/payments/offers/sku-offers.md).

## Fetch Offers

Use this API to fetch the complete catalogue of active offers on your account. Use the response to build a local cache and match eligibility on your server (Catalog pattern). For SKU-level offers, the eligible SKUs are returned inline.

`GET /v1/offers`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET 'https://api.razorpay.com/v1/offers?status=active&count=10&skip=0'
```

### Query Parameters

**status** `string`

Filter offers by status. Possible values are `active` (default) and `inactive`.

**starts\_at** `integer`

Unix timestamp. Returns offers that start on or after this time.

**ends\_at** `integer`

Unix timestamp. Returns offers that end on or before this time.

**count** `integer`

Number of offers to return. Default is `10`. Maximum is `100`.

**skip** `integer`

Number of offers to skip. Use it with `count` to paginate. Default is `0`.

### Response

```json theme={null}
{
  "entity": "collection",
  "count": 2,
  "has_more": false,
  "items": [
    {
      "entity": "offer",
      "id": "offer_MULTISKU_001",
      "name": "10% off on Apple devices with HDFC Bank cards",
      "status": "ACTIVE",
      "starts_at": 1738368600,
      "ends_at": 1740960600,
      "display_name": "10% Off on Apple Devices",
      "description": "Get 10% off up to ₹1,500 on Apple iPhone and iPad purchases with HDFC Bank cards.",
      "currency": "INR",
      "terms": {
        "tnc": "Valid on Apple iPhone and iPad purchases only.",
        "url": "https://example.com/offers/apple-hdfc/tnc"
      },
      "benefits_types": ["instant_discount"],
      "usage_limits": [
        {
          "on": "CARD_NUMBER",
          "limit_type": "COUNT",
          "limit_value": 5,
          "frequency_type": "MONTHLY",
          "frequency_value": 2,
          "tracking_level": "TRACKING_LEVEL_OFFER"
        }
      ],
      "display_config": {
        "offer_display_priority": 1,
        "should_validate": true,
        "is_hidden": false,
        "auto_apply": false
      },
      "rules": {
        "entity": "collection",
        "count": 1,
        "items": [
          {
            "criteria": {
              "includes": {
                "payment_instrument": {
                  "methods": ["card"],
                  "card": {
                    "issuers": ["HDFC"],
                    "types": ["CREDIT", "DEBIT"],
                    "networks": ["Visa", "Mastercard"]
                  }
                },
                "order": {
                  "applies_to": "line_items",
                  "min_amount": 3000000,
                  "line_item": {
                    "skus": {
                      "type": "list",
                      "values": ["IPHONE16_128", "IPHONE16_256", "IPAD_AIR_M2"]
                    },
                    "brands": ["apple"],
                    "min_quantity": 1,
                    "min_price": 3000000
                  }
                }
              },
              "excludes": {}
            },
            "benefits": {
              "entity": "collection",
              "count": 1,
              "items": [
                {
                  "type": "instant_discount",
                  "applicable_on": "line_item",
                  "value": 10,
                  "max_benefit_value": 150000,
                  "calculated_benefit_value": 0,
                  "benefit_breakup": [],
                  "limit_type": "UPTO",
                  "unit": "PERCENTAGE",
                  "tenures": []
                }
              ]
            }
          }
        ]
      }
    },
    {
      "entity": "offer",
      "id": "offer_CART_002",
      "name": "Flat ₹2,000 off on orders above ₹1,00,000 with HDFC Bank credit cards",
      "status": "ACTIVE",
      "starts_at": 1738368600,
      "ends_at": 1740960600,
      "display_name": "₹2,000 Off with HDFC Bank Credit Cards",
      "description": "Flat ₹2,000 off on orders above ₹1,00,000 with HDFC Bank credit cards.",
      "currency": "INR",
      "terms": {
        "tnc": "Valid on HDFC Bank credit card transactions.",
        "url": "https://example.com/offers/hdfc-cart/tnc"
      },
      "benefits_types": ["instant_discount"],
      "display_config": {
        "offer_display_priority": 2,
        "should_validate": true,
        "is_hidden": false,
        "auto_apply": false
      },
      "rules": {
        "entity": "collection",
        "count": 1,
        "items": [
          {
            "criteria": {
              "includes": {
                "payment_instrument": {
                  "methods": ["card"],
                  "card": {
                    "issuers": ["HDFC"],
                    "types": ["CREDIT"]
                  }
                },
                "order": {
                  "applies_to": "cart",
                  "min_amount": 10000000
                }
              },
              "excludes": {}
            },
            "benefits": {
              "entity": "collection",
              "count": 1,
              "items": [
                {
                  "type": "instant_discount",
                  "applicable_on": "cart",
                  "value": 200000,
                  "max_benefit_value": 200000,
                  "calculated_benefit_value": 0,
                  "benefit_breakup": [],
                  "limit_type": "FLAT",
                  "unit": "FIXED",
                  "tenures": []
                }
              ]
            }
          }
        ]
      }
    }
  ]
}
```

### Response Parameters

**entity** `string`

Always `collection`.

**count** `integer`

Number of offers returned on this page.

**has\_more** `boolean`

`true` if more offers exist beyond this page.

**items** `array`

List of [offer objects](#offer-object).

### Offer Object

**entity** `string`

Always `offer`.

**id** `string`

Unique identifier of the offer. For example, `offer_MULTISKU_001`.

**name** `string`

Internal name of the offer.

**display\_name** `string`

Customer-facing name of the offer.

**description** `string`

Short explanation of the offer, usually shown alongside it.

**terms** `object`

Structured terms and conditions: `tnc`, the text, and `url`, a link to the full terms.

**status** `string`

Status of the offer. Possible values are `ACTIVE` and `INACTIVE`.

**inactivation\_reason** `string`

Why the offer was deactivated. Present only when the offer is inactive. Possible values are `INACTIVATION_REASON_UNSPECIFIED`, `EXPIRED`, `EXHAUSTED`, `ON_DEMAND`, `ADVERTISER_ON_DEMAND`, `ADVERTISER_EXPIRED` and `DISCONTINUED`.

**starts\_at** `integer`

Unix timestamp when the offer becomes active.

**ends\_at** `integer`

Unix timestamp when the offer expires.

**currency** `string`

Currency of the offer. For example, `INR`.

**schedules** `array`

Time windows in which the offer is available, for example the 1st of every month or weekdays only.

* `period`: How often the window recurs. Possible values are `DAILY`, `WEEKLY`, `FORTNIGHTLY`, `MONTHLY`, `MONTH_WEEKLY`, `YEARLY`, `CALENDAR_MONTHLY` and `CALENDAR_YEARLY`.
* `interval`: Interval values for the period. For example, `[1]` for the 1st of every month.
* `starts_at` and `ends_at`: Unix timestamps for the start and end of the schedule.
* `days_of_week`: Days of the week, from `SUNDAY` to `SATURDAY`.
* `dates_of_month`: Dates of the month, from `DATE_1` to `DATE_31`.
* `months_of_year`: Months, from `JANUARY` to `DECEMBER`.
* `weeks_of_month`: Weeks of the month, from `FIRST` to `SIXTH`.

**benefits\_types** `array`

Types of benefit the offer gives. Possible values are `instant_discount`, `cashback`, `already_discounted`, `no_cost_emi` and `low_cost_emi`.

**usage\_limits** `array`

Usage restrictions on the offer, for example a maximum of 5 redemptions per card in 2 months.

* `on`: What the limit is tracked on. Possible values are `OFFER`, `MOBILE`, `EMAIL`, `CARD_NUMBER` and `CUSTOMER_ID`.
* `limit_type`: `BUDGET` for an amount cap or `COUNT` for a redemption cap.
* `limit_value`: The limit. A count, or an amount in paise.
* `frequency_type`: The window the limit applies to. Possible values are `DAILY`, `WEEKLY`, `FORTNIGHTLY`, `MONTHLY`, `MONTH_WEEKLY`, `YEARLY`, `CALENDAR_MONTHLY` and `CALENDAR_YEARLY`.
* `frequency_value`: Multiplier for `frequency_type`. For example, `2` with `MONTHLY` means 2 months.
* `tracking_level`: `TRACKING_LEVEL_OFFER` or `TRACKING_LEVEL_PUBLISHER`.

**display\_config** `object`

How to present the offer.

* `offer_display_priority`: Display priority. A higher number means a higher priority.
* `should_validate`: Whether to validate the offer before you show it.
* `is_hidden`: Whether the offer is hidden.
* `auto_apply`: Whether to apply the offer automatically, without the customer selecting it.

**rules** `object`

Collection of [rule objects](#rule-object): `entity` (always `collection`), `count` and `items`.

Fetch Offers does not return `eligible` or `validity`. [Match Offers](#match-offers) returns `eligible` and [Validate Offers](#validate-offers) returns `validity`.

### Rule Object

**criteria.includes** `object`

Conditions that must all be true for the offer to apply. Contains `payment_instrument` and `order`.

**criteria.excludes** `object`

Conditions that disqualify a transaction. Same structure as `criteria.includes`. It is `{}` when no exclusions are set.

**criteria.includes.payment\_instrument** `object`

Payment instrument conditions. See [payment instrument conditions](#payment-instrument-conditions).

**criteria.includes.order.applies\_to** `string`

Scope of the rule. `cart` for a cart-level offer or `line_items` for an SKU-level offer.

**criteria.includes.order.min\_amount** `integer`

Minimum order amount in paise.

**criteria.includes.order.max\_amount** `integer`

Maximum order amount in paise. Absent if there is no upper limit.

**criteria.includes.order.line\_item** `object`

SKU conditions. Present only when `applies_to` is `line_items`.

* `skus`: The eligible SKUs. `type` is `list` and `values` has the SKU identifiers.
* `brands`: Eligible brands. For example, `["apple"]`.
* `min_quantity`: Minimum quantity of each eligible SKU.
* `min_price`: Minimum price of the eligible line items, in paise.

**benefits** `object`

Collection of [benefit objects](#benefit-object): `entity` (always `collection`), `count` and `items`.

### Payment Instrument Conditions

The same structure appears in an offer's rules and in `criteria.payment_instrument` of the Match Offers request. Validate Offers uses a [different structure](#validate-offers) with a single value for each field.

**methods** `array`

Payment methods. Possible values are `card`, `upi`, `netbanking`, `wallet` and `emi`. For example, `["card"]`.

**card** `object`

Card conditions. Present when `methods` is `["card"]`.

* `saved`: When `true`, only saved cards are eligible.
* `international`: Whether international cards are eligible.
* `issuers`: Issuing banks. For example, `["HDFC", "Axis"]`.
* `types`: Card types. Possible values are `CREDIT`, `DEBIT` and `PREPAID`.
* `networks`: Card networks. For example, `["Visa", "Mastercard"]`.
* `categories`: Card categories. For example, `["Platinum"]`.
* `iins`: Card IINs, the first 6 digits of the card number.
* `subtype`: Card subtypes. Possible values are `CONSUMER` and `BUSINESS`.
* `cobranding_partners`: Co-branding partners. For example, `["onecard"]`.
* `tokens`: Tokens associated with the card.
* `reference_number`: Reference number of the card.

**upi** `object`

UPI conditions. Present when `methods` is `["upi"]`.

* `psps`: Payment service providers. For example, `["PHONEPE", "GPAY"]`.
* `vpa_handle`: UPI ID handles.
* `payer_account_types`: Possible values are `BANK`, `WALLET` and `CREDIT_CARD`.
* `flow`: UPI flows. Possible values are `COLLECT`, `INTENT` and `IN_APP`.
* `payer_account_bins`: Payer account BINs.

**bank\_account** `object`

Bank account conditions: `account_numbers`, `ifscs` and `names` (account holder names). Present when `methods` is `["netbanking"]`.

**netbanking** `object`

Netbanking conditions: `banks`, the eligible banks. Present when `methods` is `["netbanking"]`.

**emi** `object`

EMI conditions: `durations`, the eligible tenures in months. Present when `methods` is `["emi"]`.

**wallet** `object`

Wallet conditions: `providers`, the eligible wallet providers. Present when `methods` is `["wallet"]`.

### Benefit Object

**type** `string`

Benefit type. Possible values are `instant_discount`, `cashback`, `low_cost_emi`, `no_cost_emi` and `already_discounted`.

**applicable\_on** `string`

Where the benefit applies: `cart` or `line_item`.

**value** `integer`

Size of the benefit. Percentage points when `unit` is `PERCENTAGE` (for example, `10` for 10%) or an amount in paise when it is `FIXED`.

**max\_benefit\_value** `integer`

Maximum benefit in paise.

**limit\_type** `string`

`FLAT` or `UPTO`.

**unit** `string`

`FIXED` or `PERCENTAGE`.

**tenures** `array`

EMI tenures in months that the benefit applies to, if any.

**calculated\_benefit\_value** `integer`

The calculated discount in paise. Empty in Fetch Offers. Populated by [Match Offers](#match-offers) and [Validate Offers](#validate-offers).

## Match Offers

Use this API during checkout to find the offers that apply to the customer's order and, optionally, their payment instrument. The response lists the matched offers with the calculated discount, including the discount on each SKU for SKU-level offers. It can also include the offers that did not match.

`POST /v1/offers/match`

### When to Call

| Checkout stage | What to pass | What you get |
| - | - | - |
| Before the customer selects a payment instrument, for example on the product or cart page | `criteria.order` only. Do not pass `criteria.payment_instrument`. | All offers that apply to the order across payment instruments. Use them to show offer badges. |
| Payment page | `criteria.order` and `criteria.payment_instrument` | Offers that apply to this order and the selected payment instrument. |
| Card number entry | `criteria.payment_instrument.card.iins` with the IIN the customer enters | Offers that apply to that specific card. |

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/offers/match \
-H "Content-Type: application/json" \
-d '{
  "criteria": {
    "offers": ["offer_MULTISKU_001", "offer_MULTISKU_002", "offer_CART_002"],
    "order": {
      "amount": 15489900,
      "currency": "INR",
      "line_items": [
        {
          "sku": "IPHONE16_128",
          "brand": "apple",
          "quantity": 1,
          "price": 7990000
        },
        {
          "sku": "SAMSUNG_S24",
          "brand": "samsung",
          "quantity": 1,
          "price": 7499900
        }
      ]
    },
    "customer": {
      "contact": "+919000090000",
      "email": "gaurav.kumar@example.com"
    },
    "payment_instrument": {
      "methods": ["card"],
      "card": {
        "issuers": ["HDFC"],
        "types": ["CREDIT"],
        "networks": ["Visa"]
      }
    }
  },
  "ineligible": {
    "include": true
  },
  "count": 10,
  "skip": 0
}'
```

### Request Parameters

**criteria** `object`

Inputs used to evaluate eligibility. If you do not pass it, Razorpay evaluates all active offers without filters.

**criteria.offers** `array`

IDs of specific offers to evaluate. Maximum 20. If you do not pass it, all active offers are evaluated.

**criteria.order\_id** `string`

Order ID for the request.

**criteria.order** `object`

Cart details used to evaluate eligibility.

**criteria.order.amount** `integer`

Total cart amount in paise.

**criteria.order.currency** `string`

Currency code. For example, `INR`.

**criteria.order.notes** `object`

Key-value pairs of notes for the order.

**criteria.order.line\_items** `array`

Products in the cart. Required to evaluate SKU-level offers.

**criteria.order.line\_items\[].sku** `string`

SKU identifier of the product. Required when you pass `line_items`.

**criteria.order.line\_items\[].brand** `string`

Brand of the product. Not case-sensitive. Required when you pass `line_items`. Brand offers are evaluated correctly only when you pass it.

**criteria.order.line\_items\[].quantity** `integer`

Quantity in the cart. Must be 1 or more. Required when you pass `line_items`.

**criteria.order.line\_items\[].price** `integer`

Unit price of the product in paise. Required when you pass `line_items`.

**criteria.order.line\_items\[].notes** `object`

Key-value pairs of notes for the line item.

**criteria.payment\_instrument** `object`

Payment instrument to filter offers by. If you do not pass it, offers are returned for all instruments. Pass `methods`, required when you pass an instrument, and the [conditions for that method](#payment-instrument-conditions).

**criteria.customer** `object`

Customer details used to check per-customer usage limits.

* `id`: Customer ID.
* `contact`: Customer's phone number. `mobile_number` is accepted as an alias.
* `email`: Customer's email address.
* `card_number`: Customer's card number.
* `upi_vpa`: Customer's UPI ID.

**ineligible** `object`

Pass `{"include": true}` to also return the offers that did not match.

**count** `integer`

Number of offers to return. Default is `10`. Maximum is `100`.

**skip** `integer`

Number of offers to skip. Default is `0`.

### Response

The sample shows only the key fields of each offer. The API returns every [offer field](#offer-object).

```json theme={null}
{
  "matched": {
    "entity": "collection",
    "count": 2,
    "items": [
      {
        "entity": "offer",
        "id": "offer_MULTISKU_001",
        "display_name": "10% Off on Apple Devices",
        "status": "ACTIVE",
        "benefits_types": ["instant_discount"],
        "eligible": true,
        "rules": {
          "entity": "collection",
          "count": 1,
          "items": [
            {
              "criteria": {
                "includes": {
                  "payment_instrument": {
                    "methods": ["card"],
                    "card": {
                      "issuers": ["HDFC"],
                      "types": ["CREDIT", "DEBIT"]
                    }
                  },
                  "order": {
                    "applies_to": "line_items",
                    "min_amount": 3000000,
                    "line_item": {
                      "skus": {
                        "type": "list",
                        "values": ["IPHONE16_128", "IPHONE16_256", "IPAD_AIR_M2"]
                      },
                      "brands": ["apple"],
                      "min_quantity": 1,
                      "min_price": 3000000
                    }
                  }
                },
                "excludes": {}
              },
              "benefits": {
                "entity": "collection",
                "count": 1,
                "items": [
                  {
                    "type": "instant_discount",
                    "applicable_on": "line_item",
                    "value": 10,
                    "max_benefit_value": 150000,
                    "limit_type": "UPTO",
                    "unit": "PERCENTAGE",
                    "calculated_benefit_value": 150000,
                    "benefit_breakup": [
                      {
                        "sku": "IPHONE16_128",
                        "brand": "apple",
                        "eligible_quantity": 1,
                        "calculated_benefit_value": 150000
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      },
      {
        "entity": "offer",
        "id": "offer_CART_002",
        "display_name": "₹2,000 Off with HDFC Bank Credit Cards",
        "status": "ACTIVE",
        "benefits_types": ["instant_discount"],
        "eligible": true,
        "rules": {
          "entity": "collection",
          "count": 1,
          "items": [
            {
              "criteria": {
                "includes": {
                  "payment_instrument": {
                    "methods": ["card"],
                    "card": {
                      "issuers": ["HDFC"],
                      "types": ["CREDIT"]
                    }
                  },
                  "order": {
                    "applies_to": "cart",
                    "min_amount": 10000000
                  }
                },
                "excludes": {}
              },
              "benefits": {
                "entity": "collection",
                "count": 1,
                "items": [
                  {
                    "type": "instant_discount",
                    "applicable_on": "cart",
                    "value": 200000,
                    "max_benefit_value": 200000,
                    "limit_type": "FLAT",
                    "unit": "FIXED",
                    "calculated_benefit_value": 200000
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  },
  "ineligible": {
    "entity": "collection",
    "count": 1,
    "items": [
      {
        "entity": "offer",
        "id": "offer_MULTISKU_002",
        "display_name": "5% Off on OnePlus Phones",
        "status": "ACTIVE",
        "benefits_types": ["instant_discount"],
        "eligible": false,
        "rules": {
          "entity": "collection",
          "count": 1,
          "items": [
            {
              "criteria": {
                "includes": {
                  "payment_instrument": {
                    "methods": ["card"],
                    "card": {
                      "issuers": ["HDFC"],
                      "types": ["CREDIT"]
                    }
                  },
                  "order": {
                    "applies_to": "line_items",
                    "min_amount": 2000000,
                    "line_item": {
                      "skus": {
                        "type": "list",
                        "values": ["ONEPLUS_13_256", "ONEPLUS_13_512"]
                      },
                      "brands": ["oneplus"],
                      "min_quantity": 1,
                      "min_price": 2000000
                    }
                  }
                },
                "excludes": {}
              },
              "benefits": {
                "entity": "collection",
                "count": 1,
                "items": [
                  {
                    "type": "instant_discount",
                    "applicable_on": "line_item",
                    "value": 5,
                    "max_benefit_value": 100000,
                    "limit_type": "UPTO",
                    "unit": "PERCENTAGE"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}
```

### Response Parameters

**matched** `object`

Offers that match the cart and payment instrument: `entity` (always `collection`), `count` and `items`. Each item has every [offer field](#offer-object) and `eligible`, which is always `true`. The benefits in each item include the calculated fields below.

**matched.items\[].rules.items\[].benefits.items\[].calculated\_benefit\_value** `integer`

Total discount from this benefit in paise. Use this value. Do not add up `benefit_breakup` yourself.

**matched.items\[].rules.items\[].benefits.items\[].benefit\_breakup** `array`

Discount on each SKU. Present only for SKU-level offers when you pass `criteria.order.line_items`.

* `sku`: SKU identifier from the request.
* `brand`: Brand from the request.
* `eligible_quantity`: Units eligible for the offer. It can be lower than the cart quantity if a per-customer limit applies.
* `calculated_benefit_value`: Discount in paise for the eligible units of this SKU.

**ineligible** `object`

Offers that do not apply to this order: `entity` (always `collection`), `count` and `items`. An offer is ineligible when, for example, no SKU in the cart matches it, the payment instrument does not meet its conditions or the order amount is below its minimum. Present only when you pass `ineligible.include` as `true`. Each item has every [offer field](#offer-object) and `eligible` as `false`. `benefit_breakup` is empty for these offers.

## Create an Order

Create the Razorpay order before you validate or pay: `POST /v1/orders` with the amount (in paise) and currency, as described in the [Orders API](https://razorpay.com/docs/api/orders.md). Validate Offers reads the amount and currency from this order, so it has to exist first.

For SKU-level and brand offers, pass the cart's SKUs in the order's `line_items`, the same way you pass them to Match Offers (see [What to Pass](#what-to-pass)). An order created without line items cannot carry a SKU-level offer.

## Validate Offers

Call this API just before you create the payment. Pass the offers you plan to apply and, for SKU-level offers, the SKUs each one applies to. Razorpay confirms the offers are valid for the order and payment instrument, and calculates the final discount.

> [!WARNING]
>
> **Watch Out!**
>
> Validate Offers confirms offers you have already chosen. It does not discover offers. Use [Fetch Offers](#fetch-offers) or [Match Offers](#match-offers) to find them.

`POST /v1/offers/validate`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/offers/validate \
-H "Content-Type: application/json" \
-d '{
  "order_id": "order_NeSp2Hbm2xvDpC",
  "payment_instrument": {
    "method": "card",
    "card": {
      "saved": false,
      "international": false,
      "issuer": "HDFC",
      "type": "CREDIT",
      "network": "Visa",
      "iin": "411111"
    }
  },
  "customer": {
    "contact": "+919000090000",
    "email": "gaurav.kumar@example.com"
  },
  "offers": [
    {
      "id": "offer_MULTISKU_001",
      "line_items": [
        {
          "sku": "IPHONE16_128",
          "brand": "apple",
          "price": 7990000,
          "quantity": 1
        }
      ]
    },
    {
      "id": "offer_CART_002"
    }
  ]
}'
```

### Request Parameters

**order\_id** `string` *required*

Razorpay order ID. Razorpay reads the order amount and currency from the order.

**payment\_instrument** `object` *required*

The payment instrument the customer is paying with. Pass a single object, with one value for each field.

**payment\_instrument.method** `string` *required*

Payment method. Possible values are `card`, `upi`, `netbanking`, `wallet` and `emi`.

**payment\_instrument.card** `object`

Card details. Pass when `method` is `card`.

* `saved`: Whether the card is a saved card.
* `international`: Whether the card is international.
* `issuer`: Issuing bank. For example, `HDFC`.
* `type`: Card type. Possible values are `CREDIT`, `DEBIT` and `PREPAID`.
* `network`: Card network. For example, `Visa`.
* `category`: Card category. For example, `Platinum`.
* `iin`: Card IIN, the first 6 digits of the card number.
* `subtype`: Card subtype. Possible values are `CONSUMER` and `BUSINESS`.
* `cobranding_partner`: Co-branding partner.
* `token`: Token associated with the card.
* `reference_number`: Reference number of the card.

**payment\_instrument.upi** `object`

UPI details. Pass when `method` is `upi`. Uses the same fields as the [UPI conditions](#payment-instrument-conditions).

**payment\_instrument.bank\_account** `object`

Bank account details. Pass when `method` is `netbanking`. Uses the same fields as the [bank account conditions](#payment-instrument-conditions).

**payment\_instrument.netbanking.bank** `string`

Bank used for netbanking. Pass when `method` is `netbanking`.

**payment\_instrument.emi.duration** `integer`

EMI tenure in months. Pass when `method` is `emi`.

**payment\_instrument.wallet.provider** `string`

Wallet provider. Pass when `method` is `wallet`.

**customer** `object`

Customer details used to check per-customer usage limits. Same fields as `criteria.customer` in [Match Offers](#match-offers).

**offers** `array` *required*

Offers to validate. Maximum 20.

**offers\[].id** `string` *required*

Offer ID.

**offers\[].line\_items** `array`

SKUs this offer is applied to. Required for SKU-level offers. Do not pass it for cart-level offers.

**offers\[].line\_items\[].sku** `string`

SKU identifier. Required when you pass `line_items`.

**offers\[].line\_items\[].price** `integer`

Unit price of the SKU in paise. Required when you pass `line_items`.

**offers\[].line\_items\[].brand** `string`

Brand of the SKU. Not case-sensitive. Required when you pass `line_items`.

**offers\[].line\_items\[].quantity** `integer`

Quantity of the SKU the offer is applied to. Must be 1 or more. Required when you pass `line_items`.

> [!NOTE]
>
> **Handy Tips**
>
> The same SKU can be eligible for two different offers. Listing the `line_items` under each offer tells Razorpay exactly which offer you apply to which SKU.

### Response

The sample shows only the key fields of each offer. The API returns every [offer field](#offer-object).

```json theme={null}
{
  "valid_offers": {
    "entity": "collection",
    "count": 2,
    "items": [
      {
        "entity": "offer",
        "id": "offer_MULTISKU_001",
        "display_name": "10% Off on Apple Devices",
        "status": "ACTIVE",
        "benefits_types": ["instant_discount"],
        "validity": {
          "valid": true
        },
        "rules": {
          "entity": "collection",
          "count": 1,
          "items": [
            {
              "benefits": {
                "entity": "collection",
                "count": 1,
                "items": [
                  {
                    "type": "instant_discount",
                    "applicable_on": "line_item",
                    "value": 10,
                    "max_benefit_value": 150000,
                    "limit_type": "UPTO",
                    "unit": "PERCENTAGE",
                    "calculated_benefit_value": 150000,
                    "benefit_breakup": [
                      {
                        "sku": "IPHONE16_128",
                        "brand": "apple",
                        "eligible_quantity": 1,
                        "calculated_benefit_value": 150000
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      },
      {
        "entity": "offer",
        "id": "offer_CART_002",
        "display_name": "₹2,000 Off with HDFC Bank Credit Cards",
        "status": "ACTIVE",
        "benefits_types": ["instant_discount"],
        "validity": {
          "valid": true
        },
        "rules": {
          "entity": "collection",
          "count": 1,
          "items": [
            {
              "benefits": {
                "entity": "collection",
                "count": 1,
                "items": [
                  {
                    "type": "instant_discount",
                    "applicable_on": "cart",
                    "value": 200000,
                    "max_benefit_value": 200000,
                    "limit_type": "FLAT",
                    "unit": "FIXED",
                    "calculated_benefit_value": 200000
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  },
  "invalid_offers": {
    "entity": "collection",
    "count": 0,
    "items": []
  }
}
```

### Response Parameters

**valid\_offers** `object`

Offers that passed every check: `entity` (always `collection`), `count` and `items`. Each item has every [offer field](#offer-object) and `validity.valid` as `true`.

**valid\_offers.items\[].rules.items\[].benefits.items\[].calculated\_benefit\_value** `integer`

Confirmed total discount from this benefit in paise. This is the final value. Use it to show the discount to the customer.

**valid\_offers.items\[].rules.items\[].benefits.items\[].benefit\_breakup** `array`

Confirmed discount on each SKU. Present only for SKU-level offers.

* `sku`: SKU identifier from the request.
* `brand`: Brand from the request.
* `eligible_quantity`: Quantity confirmed as eligible. It can be lower than the quantity you sent if a per-customer limit applies.
* `calculated_benefit_value`: Confirmed discount in paise for the eligible quantity of this SKU. This is the figure used for settlement.

**invalid\_offers** `object`

Offers that failed validation: `entity` (always `collection`), `count` and `items`. Each item has every [offer field](#offer-object) and a `validity` object.

* `valid`: Always `false`.
* `reason`: Machine-readable reason. See [validation failure reasons](#validation-failure-reasons).
* `description`: Human-readable explanation.
* `field`: Path to the field in the request that failed. For example, `offers[1].line_items[0].sku`.

## Create a Payment With Offers

Create the payment using the [S2S Create Payment API](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/json/v1/build-integration/cards#1-2-create-a-payment) (`POST /v1/payments/create/json`) with the `order_id`.

* Pass `amount` as the **original order amount**, before any discount. For the order in this example, pass `15489900`.
* Pass the offers you validated in the `offers` array, exactly as you sent them to [Validate Offers](#validate-offers). Pass a cart-level offer as `{"id": "offer_..."}` with no `line_items`. Pass an SKU-level offer with the `line_items` it applies to.

```json offers parameter theme={null}
"offers": [
  {
    "id": "offer_MULTISKU_001",
    "line_items": [
      {
        "sku": "IPHONE16_128",
        "brand": "apple",
        "price": 7990000,
        "quantity": 1
      }
    ]
  },
  {
    "id": "offer_CART_002"
  }
]
```

> [!NOTE]
>
> **Existing Integrations**
>
> Create Payment still accepts a single `offer_id` for existing integrations. Use the `offers` array for new integrations.

After the customer completes the payment, [verify the payment signature](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/json/v1/build-integration/cards#1-4-verify-payment-signature) on your server before you fulfil the order.

### If an Offer Fails at Payment Time

Budget caps, per-card usage limits, and offer expiry are enforced at payment time, not at match time. An offer can pass Validate and still fail here: the budget ran out in the gap, a concurrent payment hit the usage limit, or the offer expired mid-session.

What happens next is a setting on the offer, chosen when it is created: either the payment fails with an offer error, or the payment completes without the offer. Know which way your offers are configured and build for it. On failure, re-run Match Offers and let the customer retry without the offer on the same order (OFR-07). On continue-without-offer, make sure totals and invoices come from [Fetch Order](#fetch-an-order-with-applied-offers), where the offer will be absent.

Retries are safe. Offer application is keyed on the (offer ID, payment ID) pair: for a given payment, an offer's usage counter and budget are decremented at most once, so client or network retries of the same create-payment call cannot burn the offer twice. If a payment fails after the offer was applied, the application is rolled back and counters restored. The customer can retry on the same order and still get the offer (OFR-12).

## Listen for the payment.captured Webhook

Subscribe to [webhooks](https://razorpay.com/docs/webhooks) and treat `payment.captured` (or `order.paid`) as the trigger for the next step: fetching the order with its applied offers. Don't fulfil from the browser callback alone. There are no offer-specific webhook events; the standard payment events are the signal.

When you reconcile, assert `amount_paid = amount − Σ calculated_benefit_value` of redeemed `instant_discount` and `no_cost_emi` offers (a No-Cost EMI benefit is the interest applied as an upfront discount). Cashback does not reduce `amount_paid`.

## Fetch an Order With Applied Offers

Fetch the order with `expand[]=offers` to see the offers applied and, for SKU-level offers, the discount on each SKU. Use it for fulfilment and reconciliation.

`GET /v1/orders/:id?expand[]=offers`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET 'https://api.razorpay.com/v1/orders/order_NeSp2Hbm2xvDpC?expand[]=offers'
```

### Path Parameters

**id** `string` *required*

The order ID.

### Query Parameters

**expand\[]** `string`

Pass `offers` to include `offers_applied` with the discount on each SKU.

### Response

```json theme={null}
{
  "id": "order_NeSp2Hbm2xvDpC",
  "entity": "order",
  "amount": 15489900,
  "amount_paid": 15139900,
  "amount_due": 0,
  "currency": "INR",
  "receipt": "rcpt_2025_001",
  "status": "paid",
  "attempts": 1,
  "notes": {},
  "offers": ["offer_MULTISKU_001", "offer_CART_002"],
  "offers_applied": {
    "entity": "collection",
    "count": 2,
    "items": [
      {
        "id": "offer_MULTISKU_001",
        "status": "redeemed",
        "benefits": [
          {
            "type": "instant_discount",
            "applicable_on": "line_item",
            "calculated_benefit_value": 150000,
            "benefit_breakup": [
              {
                "sku": "IPHONE16_128",
                "brand": "apple",
                "applied_quantity": 1,
                "calculated_benefit_value": 150000
              }
            ]
          }
        ]
      },
      {
        "id": "offer_CART_002",
        "status": "redeemed",
        "benefits": [
          {
            "type": "instant_discount",
            "applicable_on": "cart",
            "calculated_benefit_value": 200000
          }
        ]
      }
    ]
  },
  "created_at": 1738368600
}
```

### Response Parameters

**id** `string`

Order ID.

**amount** `integer`

Order amount in paise, before discounts.

**amount\_paid** `integer`

Amount paid in paise, after discounts.

**amount\_due** `integer`

Amount still due in paise.

**status** `string`

Status of the order. Possible values are `created`, `attempted` and `paid`.

**notes** `object`

Key-value pairs of notes for the order.

**offers** `array`

IDs of the offers on the order, including the ones in `offers_applied`.

**offers\_applied** `object`

Applied offers: `entity` (always `collection`), `count` and `items`. Returned when you pass `expand[]=offers`.

**offers\_applied.items\[].id** `string`

Offer ID.

**offers\_applied.items\[].status** `string`

`redeemed` when the offer was applied.

**offers\_applied.items\[].benefits** `array`

Benefits applied by this offer.

* `type`: Benefit type. Possible values are `instant_discount`, `cashback`, `no_cost_emi`, `low_cost_emi` and `already_discounted`.
* `applicable_on`: `line_item` or `cart`.
* `calculated_benefit_value`: Total benefit amount in paise.
* `benefit_breakup`: Benefit on each SKU, with `sku`, `brand`, `applied_quantity` and `calculated_benefit_value`. Present only for `line_item` benefits.

The API returns these responses without an error:

| Scenario | Behaviour |
| - | - |
| `expand[]=offers` is not passed | `offers_applied` is not included. |
| No offers were applied to the order | `offers_applied.count` is `0`. |
| The order is in `created` state and the payment is not complete | Order details are returned and `offers_applied` is empty. |

### Refunds on Offer-Discounted Payments

A refund is always capped at the payment amount, what the customer actually paid, never the original order amount. The discount portion was never collected by Razorpay, so it cannot be refunded.

| Order amount | Discount | Customer paid | Full refund | Partial refunds |
| - | - | - | - | - |
| ₹100 | ₹10 | ₹90 | ₹90 | Any amounts, cumulative ≤ ₹90 |

* Base your refund ceiling on `amount_paid` from Fetch Order, never on `amount`.
* Multiple partial refunds are allowed as long as the cumulative total stays within the payment amount.
* The customer's offer usage slot is not restored after a refund. A refunded redemption still counts against per-card and per-customer usage limits.
* **EMI offers**: a refund credits the customer's card or account, but it does not automatically cancel the bank's EMI schedule. The customer must request foreclosure from their bank, and foreclosure terms are bank-specific. Partial refunds on EMI transactions are bank-dependent.

Test coverage: OFR-18.

## Block and Unblock IMEIs for Brand Offers

For Brand Offers, you may need to block the IMEI or serial number of each device you sell against the order. Blocking records the sale of that device with the brand. Unblocking reverses it, for example when the order is refunded or cancelled.

> [!WARNING]
>
> **Watch Out!**
>
> For certain brands, the brand-funded offer amount is not settled to you unless you block the IMEI of each device sold. Check with your account manager whether this applies to the brands you sell.

* Block the IMEI after the payment is complete.
* If you refund or cancel the order, call [Unblock an IMEI](#unblock-an-imei). Refunding the payment does not unblock it.
* You can also block and unblock IMEIs from the Dashboard. Know more about [blocking IMEIs from the Dashboard](https://razorpay.com/docs/payments/offers/sku-offers.md#block-and-unblock-imeis-for-brand-offers).

### Block an IMEI

`POST /v1/orders/:id/line_items/product_block`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/orders/order_NeSp2Hbm2xvDpC/line_items/product_block \
-H "content-type: application/json" \
-d '{
  "line_items": [
    {
      "sku": "IPHONE16_128",
      "brand": "apple",
      "dealer_code": "DLR-4021",
      "serial_numbers": ["356789012345671"]
    }
  ]
}'
```

```json Response theme={null}
{
  "line_items": [
    {
      "sku": "IPHONE16_128",
      "brand": "apple",
      "serial_numbers": [
        {
          "serial_number": "356789012345671",
          "block_status": "blocked"
        }
      ]
    }
  ]
}
```

### Unblock an IMEI

`POST /v1/orders/:id/line_items/product_unblock`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/orders/order_NeSp2Hbm2xvDpC/line_items/product_unblock \
-H "content-type: application/json" \
-d '{
  "line_items": [
    {
      "sku": "IPHONE16_128",
      "brand": "apple",
      "dealer_code": "DLR-4021",
      "serial_numbers": ["356789012345671"]
    }
  ]
}'
```

```json Response theme={null}
{
  "line_items": [
    {
      "sku": "IPHONE16_128",
      "brand": "apple",
      "serial_numbers": [
        {
          "serial_number": "356789012345671",
          "block_status": "unblocked"
        }
      ]
    }
  ]
}
```

### Request Parameters

Both APIs take the same parameters.

**id** `string` *required*

The ID of the order the devices were sold against.

**line\_items** `array` *required*

The products whose IMEIs or serial numbers you want to block or unblock.

**line\_items\[].sku** `string` *required*

SKU of the product. It must match a `line_items[].sku` on the order.

**line\_items\[].brand** `string` *required*

Brand of the product. Maximum 14 characters.

**line\_items\[].serial\_numbers** `array` *required*

IMEIs or serial numbers of the devices. Pass the 15-digit IMEI for phones and the serial number for other devices. Pass one for each unit sold.

**line\_items\[].dealer\_code** `string`

The dealer code issued to you by the brand, if you have one.

### Response Parameters

**line\_items\[].sku** `string`

SKU of the product.

**line\_items\[].brand** `string`

Brand of the product.

**line\_items\[].serial\_numbers\[].serial\_number** `string`

The IMEI or serial number.

**line\_items\[].serial\_numbers\[].block\_status** `string`

Status of the IMEI or serial number. Possible values are `blocked`, `unblocked` and `failed`. Not returned if the request for this serial number fails validation. Check `error` in that case.

**line\_items\[].serial\_numbers\[].error** `object`

Present when the IMEI or serial number could not be blocked or unblocked. Contains `code`, `description`, `source`, `step` and `reason`.

Each IMEI or serial number is processed separately, so one response can have both successful and failed entries. Check `block_status` or `error` for each one.

## Related Information

* [About Offers](https://razorpay.com/docs/payments/offers)
* [Create Offers](https://razorpay.com/docs/payments/offers/create.md)
* [Integrate Offers with Standard Checkout](https://razorpay.com/docs/payments/offers/standard-integration)
* [Fetch and Match Offers APIs](https://razorpay.com/docs/payments/offers/fetch-match-offers.md)
* [SKU and Brand Offers on Standard Checkout](https://razorpay.com/docs/payments/offers/sku-offers.md)
* [Orders API](https://razorpay.com/docs/api/orders.md)
* [Test Offers](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/offers.md)
