Skip to main content
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

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

  1. Sync the catalogue periodically, for example every night. Call 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. To apply offers to specific products, also pass the cart’s SKUs in line_items.
  4. Validate the offers before payment. Call Validate Offers to confirm each offer for the order and the payment instrument.
  5. Create the payment. Call the Create Payment API and pass the validated offers.
  6. Fetch the order. Call Fetch Order with expand[]=offers to confirm the applied offers.
  7. Block the IMEIs (Brand Offers). If the brand requires it, call Block an IMEI for each device sold.

Runtime Pattern Flow

  1. 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.
  2. Create an order. Call the Orders API. 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 again with criteria.payment_instrument.
  4. Validate the offers before payment. Call Validate Offers to confirm each offer for the order and the payment instrument.
  5. Create the payment. Call the Create Payment API and pass the validated offers.
  6. Fetch the order. Call Fetch Order with expand[]=offers to confirm the applied offers.
  7. 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.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: 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

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

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 or validity. Match Offers returns eligible and Validate Offers returns validity.

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. Validate Offers uses a different structure with a single value for each field.
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 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

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.

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.

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.
Watch Out!Validate Offers confirms offers you have already chosen. It does not discover offers. Use Fetch Offers or Match Offers to find them.
POST /v1/offers/validate
Curl

Request Parameters

string
required
Razorpay order ID. Razorpay reads the order amount and currency from the order.
object
required
The payment instrument the customer is paying with. Pass a single object, with one value for each field.
string
required
Payment method. Possible values are card, upi, netbanking, wallet and emi.
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.
object
UPI details. Pass when method is upi. Uses the same fields as the UPI conditions.
object
Bank account details. Pass when method is netbanking. Uses the same fields as the bank account conditions.
string
Bank used for netbanking. Pass when method is netbanking.
integer
EMI tenure in months. Pass when method is emi.
string
Wallet provider. Pass when method is wallet.
object
Customer details used to check per-customer usage limits. Same fields as criteria.customer in Match Offers.
array
required
Offers to validate. Maximum 20.
string
required
Offer ID.
array
SKUs this offer is applied to. Required for SKU-level offers. Do not pass it for cart-level offers.
string
SKU identifier. Required when you pass line_items.
integer
Unit price of the SKU in paise. Required when you pass line_items.
string
Brand of the SKU. Not case-sensitive. Required when you pass line_items.
integer
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

object
Offers that passed every check: entity (always collection), count and items. Each item has every offer field and validity.valid as true.
integer
Confirmed total discount from this benefit in paise. This is the final value. Use it to show the discount to the customer.
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.
object
Offers that failed validation: entity (always collection), count and items. Each item has every offer field and a validity object.
  • valid: Always false.
  • 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 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. Pass a cart-level offer as {"id": "offer_..."} with no line_items. Pass an SKU-level offer with the line_items it applies to.
offers parameter
Existing IntegrationsCreate 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 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, 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 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
Curl

Path Parameters

string
required
The order ID.

Query Parameters

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

Response

Response Parameters

string
Order ID.
integer
Order amount in paise, before discounts.
integer
Amount paid in paise, after discounts.
integer
Amount still due in paise.
string
Status of the order. Possible values are created, attempted and paid.
object
Key-value pairs of notes for the order.
array
IDs of the offers on the order, including the ones in offers_applied.
object
Applied offers: entity (always collection), count and items. Returned when you pass expand[]=offers.
string
Offer ID.
string
redeemed when the offer was applied.
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:

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_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.
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. 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.
string
required
The ID of the order the devices were sold against.
array
required
The products whose IMEIs or serial numbers you want to block or unblock.
string
required
SKU of the product. It must match a line_items[].sku on the order.
string
required
Brand of the product. Maximum 14 characters.
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.
string
The dealer code issued to you by the brand, if you have one.

Response Parameters

string
SKU of the product.
string
Brand of the product.
string
The IMEI or serial number.
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.
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.
Last modified on November 17, 2026