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_idandkey_secretto authenticate API requests. - Create the offers you want to give from the Dashboard.
Choose an API
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.criteria.includeslists the conditions that must all be true for the offer to apply.criteria.excludeslists 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
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
Query Parameters
Response
Response Parameters
List of offer objects.
Offer Object
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.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 areDAILY,WEEKLY,FORTNIGHTLY,MONTHLY,MONTH_WEEKLY,YEARLY,CALENDAR_MONTHLYandCALENDAR_YEARLY.interval: Interval values for the period. For example,[1]for the 1st of every month.starts_atandends_at: Unix timestamps for the start and end of the schedule.days_of_week: Days of the week, fromSUNDAYtoSATURDAY.dates_of_month: Dates of the month, fromDATE_1toDATE_31.months_of_year: Months, fromJANUARYtoDECEMBER.weeks_of_month: Weeks of the month, fromFIRSTtoSIXTH.
Types of benefit the offer gives. Possible values are
instant_discount, cashback, already_discounted, no_cost_emi and low_cost_emi.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 areOFFER,MOBILE,EMAIL,CARD_NUMBERandCUSTOMER_ID.limit_type:BUDGETfor an amount cap orCOUNTfor a redemption cap.limit_value: The limit. A count, or an amount in paise.frequency_type: The window the limit applies to. Possible values areDAILY,WEEKLY,FORTNIGHTLY,MONTHLY,MONTH_WEEKLY,YEARLY,CALENDAR_MONTHLYandCALENDAR_YEARLY.frequency_value: Multiplier forfrequency_type. For example,2withMONTHLYmeans 2 months.tracking_level:TRACKING_LEVEL_OFFERorTRACKING_LEVEL_PUBLISHER.
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.
Collection of rule objects:
entity (always collection), count and items.eligible. Match Offers returns it.
Rule Object
Conditions that must all be true for the offer to apply. Contains
payment_instrument and order.Conditions that disqualify a transaction. Same structure as
criteria.includes. It is {} when no exclusions are set.Payment instrument conditions. See payment instrument conditions.
SKU conditions. Present only when
applies_to is line_items.skus: The eligible SKUs.typeislistandvalueshas 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.
Collection of benefit objects:
entity (always collection), count and items.Payment Instrument Conditions
The same structure appears in an offer’s rules and incriteria.payment_instrument of the Match Offers request.
Payment methods. Possible values are
card, upi, netbanking, wallet and emi. For example, ["card"].Card conditions. Present when
methods is ["card"].saved: Whentrue, only saved cards are eligible.international: Whether international cards are eligible.issuers: Issuing banks. For example,["HDFC", "Axis"].types: Card types. Possible values areCREDIT,DEBITandPREPAID.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 areCONSUMERandBUSINESS.cobranding_partners: Co-branding partners. For example,["onecard"].tokens: Tokens associated with the card.reference_number: Reference number of the card.
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 areBANK,WALLETandCREDIT_CARD.flow: UPI flows. Possible values areCOLLECT,INTENTandIN_APP.payer_account_bins: Payer account BINs.
Bank account conditions:
account_numbers, ifscs and names (account holder names). Present when methods is ["netbanking"].Wallet conditions:
providers, the eligible wallet providers. Present when methods is ["wallet"].Benefit Object
Benefit type. Possible values are
instant_discount, cashback, low_cost_emi, no_cost_emi and already_discounted.Size of the benefit. Percentage points when
unit is PERCENTAGE (for example, 10 for 10%) or an amount in paise when it is FIXED.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
Curl
Request Parameters
Inputs used to evaluate eligibility. If you do not pass it, Razorpay evaluates all active offers without filters.
IDs of specific offers to evaluate. Maximum 20. If you do not pass it, all active offers are evaluated.
Brand of the product. Not case-sensitive. Required when you pass
line_items. Brand offers are evaluated correctly only when you pass it.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.Customer details used to check per-customer usage limits.
id: Customer ID.contact: Customer’s phone number.mobile_numberis accepted as an alias.email: Customer’s email address.card_number: Customer’s card number.upi_vpa: Customer’s UPI ID.
Response
The sample shows only the key fields of each offer. The API returns every offer field.Response Parameters
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.Total discount from this benefit in paise. Use this value. Do not add up
benefit_breakup yourself.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.
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.