Fetch and Match Offers Using APIs

Available in🇮🇳 India

Use the Fetch Offers and Match Offers APIs to show offers on your own website or app. For example, show offer badges on product pages or list the offers a customer can get on your payment page. The APIs work for offers on the whole order (cart-level offers) and for offers on specific products in the cart (SKU-level offers).

Prerequisites

Generate the API keys from the Dashboard. You need the key_id and key_secret to authenticate API requests.
Create the offers you want to give from the Dashboard.

Choose an API

API	Use it to
Fetch Offers	Get the full catalogue of active offers on your account. Cache it on your server and match offers to orders yourself.
Match Offers	Get the offers that apply to a specific order and, optionally, a payment instrument. Razorpay does the matching and calculates the discount.

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.

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 Offers only)
                └── benefit_breakup[]          (Match Offers 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 and SKU-Level Offers

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.

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. For SKU-level offers, the eligible SKUs are returned inline. GET /v1/offers

Curl

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

Query Parameters

string

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

integer

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

integer

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

integer

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

integer

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

Response

{
  "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

string

Always collection.

integer

Number of offers returned on this page.

boolean

true if more offers exist beyond this page.

array

List of offer objects.

Offer Object

string

Always offer.

string

Unique identifier of the offer. For example, offer_MULTISKU_001.

string

Internal name of the offer.

string

Customer-facing name of the offer.

string

Short explanation of the offer, usually shown alongside it.

object

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

string

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

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.

integer

Unix timestamp when the offer becomes active.

integer

Unix timestamp when the offer expires.

string

Currency of the offer. For example, INR.

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.

array

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

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.

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.

object

Collection of rule objects: entity (always collection), count and items.

Fetch Offers does not return eligible. Match Offers returns it.

Rule Object

object

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

object

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

object

Payment instrument conditions. See payment instrument conditions.

string

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

integer

Minimum order amount in paise.

integer

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

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.

object

Collection of benefit objects: 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.

array

Payment methods. Possible values are card, upi, netbanking, wallet and emi. For example, ["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.

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.

object

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

object

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

object

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

object

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

Benefit Object

string

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

string

Where the benefit applies: cart or line_item.

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.

integer

Maximum benefit in paise.

string

FLAT or UPTO.

string

FIXED or PERCENTAGE.

array

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

integer

The calculated discount in paise. Empty in Fetch Offers. Populated by Match 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.

Curl

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

object

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

array

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

string

Order ID for the request.

object

Cart details used to evaluate eligibility.

integer

Total cart amount in paise.

string

Currency code. For example, INR.

object

Key-value pairs of notes for the order.

array

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

string

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

string

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

integer

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

integer

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

object

Key-value pairs of notes for the line item.

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.

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.

object

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

integer

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

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.

{
  "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

object

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

integer

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

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.

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 and eligible as false. benefit_breakup is empty for these offers.

Errors

API	HTTP status	Scenario	`reason`	`field`
Fetch Offers	400	`status` is not a supported value.	`input_validation_failed`	`status`
Fetch Offers	400	`ends_at` is before `starts_at`.	`input_validation_failed`	`ends_at`
Fetch Offers	400	`count` is more than 100.	`input_validation_failed`	`count`
Match Offers	400	`criteria.offers` has more than 20 entries.	`input_validation_failed`	`criteria.offers`
Match Offers	400	A line item `quantity` is less than 1.	`input_validation_failed`	`criteria.order.line_items[n].quantity`
Match Offers	429	Rate limit exceeded.	`rate_limit_exceeded`	—
Both	401	The API key is invalid or missing.	`authentication_failed`	—

​Prerequisites

​Choose an API

​Key Concepts

​Offer Structure

​Cart-Level and SKU-Level Offers

​Fetch Offers

​Query Parameters

​Response

​Response Parameters

​Offer Object

​Rule Object

​Payment Instrument Conditions

​Benefit Object

​Match Offers

​When to Call

​Request Parameters

​Response

​Response Parameters

​Errors

​Related Information

Prerequisites

Choose an API

Key Concepts

Offer Structure

Cart-Level and SKU-Level Offers

Fetch Offers

Query Parameters

Response

Response Parameters

Offer Object

Rule Object

Payment Instrument Conditions

Benefit Object

Match Offers

When to Call

Request Parameters

Response

Response Parameters

Errors

Related Information