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 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.
For Platform PartnersThese 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 from the Dashboard. You need the
key_idandkey_secretto authenticate API requests. - Create the offers you want to give from the Dashboard.
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.Catalog Pattern Flow
- Sync the catalogue periodically, for example every night. Call Fetch Offers to get all active offers and store them on your server.
- Match offers at checkout. Compare the customer’s order with your cached offers.
- Create an order. Call the Orders API. To apply offers to specific products, also pass the cart’s SKUs in
line_items. - Validate the offers before payment. Call Validate Offers to confirm each offer for the order and the payment instrument.
- Create the payment. Call the Create Payment API and pass the validated offers.
- Fetch the order. Call Fetch Order with
expand[]=offersto confirm the applied offers. - Block the IMEIs (Brand Offers). If the brand requires it, call Block an IMEI for each device sold.
Runtime Pattern Flow
- Show offers before the customer pays. Call Match Offers without
criteria.payment_instrument. The response lists the offers that apply to the order across all payment instruments. - Create an order. Call the Orders API. To apply offers to specific products, also pass the cart’s SKUs in
line_items. - Show offers on the payment page. When the customer selects a payment instrument, call Match Offers again with
criteria.payment_instrument. - Validate the offers before payment. Call Validate Offers to confirm each offer for the order and the payment instrument.
- Create the payment. Call the Create Payment API and pass the validated offers.
- Fetch the order. Call Fetch Order with
expand[]=offersto confirm the applied offers. - Block the IMEIs (Brand Offers). If the brand requires it, call 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.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 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:
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
Feature RequestBrand 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.
To apply SKU and Brand Offers on Razorpay Standard Checkout instead, see SKU and Brand Offers on Standard Checkout.
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
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 or validity. Match Offers returns eligible and Validate Offers returns validity.
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. Validate Offers uses a different structure with a single value for each field.
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 and 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
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.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. 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). 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.POST /v1/offers/validate
Curl
Request Parameters
The payment instrument the customer is paying with. Pass a single object, with one value for each field.
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 areCREDIT,DEBITandPREPAID.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 areCONSUMERandBUSINESS.cobranding_partner: Co-branding partner.token: Token associated with the card.reference_number: Reference number of the card.
UPI details. Pass when
method is upi. Uses the same fields as the UPI conditions.Bank account details. Pass when
method is netbanking. Uses the same fields as the bank account conditions.Customer details used to check per-customer usage limits. Same fields as
criteria.customer in Match Offers.SKUs this offer is applied to. Required for SKU-level offers. Do not pass it for cart-level offers.
Quantity of the SKU the offer is applied to. Must be 1 or more. Required when you pass
line_items.Handy TipsThe 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.Response Parameters
Offers that passed every check:
entity (always collection), count and items. Each item has every offer field and validity.valid as true.Confirmed total discount from this benefit in paise. This is the final value. Use it to show the discount to the customer.
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.
Offers that failed validation:
entity (always collection), count and items. Each item has every offer field and a validity object.valid: Alwaysfalse.reason: Machine-readable reason. See 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 (POST /v1/payments/create/json) with the order_id.
- Pass
amountas the original order amount, before any discount. For the order in this example, pass15489900. - Pass the offers you validated in the
offersarray, exactly as you sent them to Validate Offers. Pass a cart-level offer as{"id": "offer_..."}with noline_items. Pass an SKU-level offer with theline_itemsit applies to.
offers parameter
Existing IntegrationsCreate Payment still accepts a single
offer_id for existing integrations. Use the offers array for new integrations.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, 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 and treatpayment.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 withexpand[]=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
Curl
Path Parameters
Query Parameters
Response
Response Parameters
Applied offers:
entity (always collection), count and items. Returned when you pass expand[]=offers.Benefits applied by this offer.
type: Benefit type. Possible values areinstant_discount,cashback,no_cost_emi,low_cost_emiandalready_discounted.applicable_on:line_itemorcart.calculated_benefit_value: Total benefit amount in paise.benefit_breakup: Benefit on each SKU, withsku,brand,applied_quantityandcalculated_benefit_value. Present only forline_itembenefits.
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.- Base your refund ceiling on
amount_paidfrom Fetch Order, never onamount. - 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.
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.- Block the IMEI after the payment is complete.
- If you refund or cancel the order, call 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.
Block an IMEI
POST /v1/orders/:id/line_items/product_block
Curl
Response
Unblock an IMEI
POST /v1/orders/:id/line_items/product_unblock
Curl
Response
Request Parameters
Both APIs take the same parameters.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.
Response Parameters
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.Present when the IMEI or serial number could not be blocked or unblocked. Contains
code, description, source, step and reason.block_status or error for each one.