> ## 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.

# Test Offers - S2S Integration

> Test the S2S Offers APIs in Test Mode: scenarios to run before go-live, common integration gaps, best practices and error handling.

Available in
🇮🇳 India

## Test Mode

Test mode runs the same endpoints against simulated banks and NPCI. No real money moves. Switch the Dashboard to Test Mode, generate `rzp_test_` keys, and use them in the same requests.

### Before You Test

1. Generate test keys: **Account & Settings → API Keys → Generate Test Key**.
2. [Create your test offers](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/offers.md#prerequisites) in the test-mode Dashboard. Offers exist per mode: live offers don't appear in test mode. For full scenario coverage you need five: a cart-level flat discount, a SKU-level percentage discount with a cap (SKU offers are not self-serve on the Dashboard; ask your Razorpay team to set one up in test mode), an offer with a per-card usage limit of 1, an expired offer and a No-Cost EMI offer.
3. Have the payment test kit below ready. Offer flows end in a payment, and you drive the payment's outcome with test credentials.

### Test Kit: Driving Payment Outcomes

The offer APIs themselves have no special test credentials; their outcome depends on the offers you configured and the request you send. The payment at the end of the flow is where you pick success or failure:

| Method | Success | Failure |
| - | - | - |
| Cards | A [test card](https://razorpay.com/docs/payments/payments/test-card-details.md), completing the mock bank page | A failure flow on the mock bank page |
| UPI | `success@razorpay` | `failure@razorpay` |

Test credentials are documented on the [test cards](https://razorpay.com/docs/payments/payments/test-card-details.md) and [test UPI](https://razorpay.com/docs/payments/payments/test-upi-details.md) pages; this guide only needs a success trigger and a failure trigger per method.

### What You Can Test in Test Mode, and What You Can't

| Area | Test mode | How it works |
| - | - | - |
| Offer creation | Supported | Same Dashboard wizard in test mode. Test offers are separate from live offers. |
| Fetch, Match, Validate | Supported | Same evaluation logic as live, run against your test-mode offers. |
| Payment with offers, discount math | Supported | Simulated banks. Drive the outcome with the test kit; `amount_paid` reflects the discount exactly as in live. |
| Usage limits and budget exhaustion | Supported | Enforced the same way on test offers. A per-card limit of 1 lets you simulate exhaustion on the second attempt. |
| Refund behaviour with offers | Supported | Refund the test payment; the cap is the paid (discounted) amount. |
| Cashback payout and settlement | Live only | Money movement, bank funding and settlement run only in live mode. |
| Brand-offer IMEI validation | Live only | Confirm setup with your Razorpay team. |
| Rate limiting (429), server errors (5xx) | Live only | Can't be triggered on demand in test mode. Test your handling with stubs. |

### Simulating Failures

These are examples of each failure class, not an exhaustive list. Anything driven by your own request or your offer setup can be reproduced in test mode.

**Failures you can reproduce in test mode**

| What you want to see | How to set it up |
| - | - |
| `input_validation_failed` (HTTP 400) | Send an invalid request on purpose: more than 20 offer IDs in one request (20 is the array maximum), a line item without a `sku`, `quantity: 0`, or Validate without a `payment_instrument`. |
| `offer_expired` | Validate an offer whose end date has passed. |
| `order_amount_below_minimum` | Create the order below the offer's minimum amount. |
| `sku_not_mapped_to_offer` | Pass a SKU the offer does not cover. |
| `instrument_not_eligible` | Validate with a card or method the offer does not cover. |
| `quantity_exceeds_offer_limit` | Give the test offer a per-card limit of 1 and use it once. |
| Payment failure after an offer is applied | Pay with a failure trigger from the [test kit](#test-kit-driving-payment-outcomes). |
| Offer lost between Validate and payment | Use the limit-1 offer from two sessions; the second hits the limit at payment time. |

**Failures you cannot reproduce in test mode**

* **429 rate limiting and 5xx server errors.** To test your handling, stand in for the API in your own environment: point the Match call at a stub server that returns these errors or times out, and check the checkout still renders and payment still works (OFR-16).
* **Live-account errors.** In live mode, API calls fail if your account is not activated, or if you call from an IP address outside the allowlist configured on the Dashboard (the error reads as an authentication failure). Test keys skip both checks.
* **Settlement and cashback payout failures.** Money movement runs only in live mode.

## Scenarios to Test Your Integration

19 scenarios in three groups. **Must-have**: run these before go-live; money is wrong or payments break if they fail. **Other common scenarios**: real situations your integration will meet in week one. **Error scenarios**: make sure bad inputs and failures are handled, not just the happy path. Set up the five test offers from [Before You Test](#before-you-test) first.

### Must-Have

<table>
  <colgroup>
    <col width="71" />

    <col width="240" />

    <col width="235" />

    <col width="325" />

    <col width="133" />
  </colgroup>

  <thead>
    <tr>
      <th>ID</th>
      <th>Scenario</th>
      <th>Setup</th>
      <th>Steps</th>
      <th>Criticality</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>OFR-01</td>
      <td>Match returns the right offers for a cart and card</td>
      <td>The SKU-level test offer; a cart and card that qualify for it</td>
      <td>Call Match with the order, `line_items`, and instrument. Check the offer is in `matched` with `eligible: true`. Check the discount math: `calculated_benefit_value` equals the percentage of the price, capped at `max_benefit_value`, and `benefit_breakup` adds up to it.</td>
      <td>Must pass</td>
    </tr>

    <tr>
      <td>OFR-02</td>
      <td>Match without an instrument, for the payment page</td>
      <td>Same cart, no instrument selected yet</td>
      <td>Call Match without `payment_instrument`. Check offers across all payment methods come back. Render the offer strip from this list.</td>
      <td>Must pass</td>
    </tr>

    <tr>
      <td>OFR-03</td>
      <td>Validate at Pay and show the final amount</td>
      <td>Order created; the offer from OFR-01 selected</td>
      <td>Call Validate with `order_id`, the instrument (single values), and `offers[]`. Check the offer is in `valid_offers` with `validity.valid: true`. Check the amount you show the customer equals the order amount minus the sum of `calculated_benefit_value`.</td>
      <td>Must pass</td>
    </tr>

    <tr>
      <td>OFR-04</td>
      <td>Pay with offers end to end, then confirm on the order</td>
      <td>OFR-03, then a successful test payment</td>
      <td>Create the payment with the original amount and the same `offers[]` you validated. Complete it with a success trigger from the [test kit](#test-kit-driving-payment-outcomes) and capture. Fetch the order with `expand[]=offers`. Every offer shows `status: redeemed`, `amount_paid` equals amount minus discounts, and `applied_quantity` matches what you validated.</td>
      <td>Must pass</td>
    </tr>

    <tr>
      <td>OFR-05</td>
      <td>Send the original amount, never the discounted amount</td>
      <td>Deliberately break the rule: send `amount = order total − discount`</td>
      <td>Review the code path that sets the payment `amount`: it must always come from the order, never from the discounted display price. The protection lives in your code. As a probe, create a payment with the discounted amount and record what the API returns.</td>
      <td>Must pass</td>
    </tr>

    <tr>
      <td>OFR-06</td>
      <td>Customer switches cards after you validated</td>
      <td>Validate with a qualifying card, then switch to one that doesn't qualify</td>
      <td>Validate with card A. It passes. The customer switches to card B. Validate again. Check the offer moves to `invalid_offers` with `reason: instrument_not_eligible`, and your UI removes the discount and re-shows the payable amount before payment. Check no payment is ever created carrying offers validated against a different instrument.</td>
      <td>Must pass</td>
    </tr>

    <tr>
      <td>OFR-07</td>
      <td>Offer runs out between Validate and payment</td>
      <td>The per-card-limit-1 test offer, used up by a second session in parallel</td>
      <td>Validate successfully in session one. Consume the offer's last slot from a second session. Create the payment in session one. What happens depends on how the offer was configured at creation: the payment fails, or it completes without the offer. Handle both outcomes: on failure, re-run Match and let the customer retry without the offer on the same order; on success without the offer, make sure totals come from Fetch Order, not from the validated discount.</td>
      <td>Must pass</td>
    </tr>
  </tbody>
</table>

### Other Common Scenarios

<table>
  <colgroup>
    <col width="65" />

    <col width="245" />

    <col width="230" />

    <col width="348" />

    <col width="155" />
  </colgroup>

  <thead>
    <tr>
      <th>ID</th>
      <th>Scenario</th>
      <th>Setup</th>
      <th>Steps</th>
      <th>Criticality</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>OFR-12</td>
      <td>Payment fails, customer retries with the same offer</td>
      <td>An offer is applied, then a payment fails with a failure trigger</td>
      <td>Validate, create the payment with the offer, and fail it using a failure trigger. Retry on the same order with the same offer. Check Validate passes again and the retry succeeds with the discount. The failed attempt must not have consumed the offer. Fetch the order and check that exactly one redemption is recorded.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-13</td>
      <td>Show locked offers as nudges</td>
      <td>`ineligible.include: true`, with a cart just below an offer's minimum</td>
      <td>Call Match with `ineligible.include: true`. Check the offer appears under `ineligible` with `eligible: false` and its full rules. Build the nudge ("Add ₹500 more to unlock") from `rules[].criteria.includes`, and make sure an ineligible offer can never be selected.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-15</td>
      <td>Two offers on one payment</td>
      <td>The cart-level and SKU-level test offers, both eligible on one order</td>
      <td>Validate both in one call. Both come back valid. Create the payment with both; fetch the order and check both show `redeemed`. Check `amount_paid` equals the amount minus both discounts, and the invoice shows both lines.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-17</td>
      <td>No-Cost EMI tenures</td>
      <td>The NCE test offer, restricted to specific tenures</td>
      <td>Validate with `method: emi` and a covered `emi.duration`. It passes, and the EMI plan shows zero-interest math. Validate with a tenure the offer doesn't cover. It fails with `instrument_not_eligible`. Check the discount math: the NCE benefit reduces `amount_paid` (the interest applied as an upfront discount). Confirm your order summary matches [Fetch Order](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/offers.md#fetch-an-order-with-applied-offers).</td>
      <td>Good to have</td>
    </tr>

    <tr>
      <td>OFR-18</td>
      <td>Refund a discounted payment</td>
      <td>The captured payment from OFR-04; a full refund</td>
      <td>Refund the payment in full. Check that the refund amount is the paid (discounted) amount, not the original order amount. Check your refund ledger reconciles against `amount_paid`and note the customer's usage slot is not restored ([refund rules](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/offers.md#refunds-on-offer-discounted-payments)).</td>
      <td>Good to have</td>
    </tr>

    <tr>
      <td>OFR-19</td>
      <td>Offers shown on home, product, and cart pages match checkout</td>
      <td>An offer surfaced pre-checkout via Match ([When to Call](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/offers.md#when-to-call))</td>
      <td>Call Match with no `criteria.order` (home page) and with an inline one-item `order` (product page). The offer returns; render it from `display_name` and terms, with no price math. Go to checkout with the same item. Checkout re-runs Match and shows the same offer, or no longer shows it if it expired in between. Check no discounted price appears anywhere before Validate runs at Pay.</td>
      <td>Good to have</td>
    </tr>
  </tbody>
</table>

### Error Scenarios

<table>
  <colgroup>
    <col width="60" />

    <col width="246" />

    <col width="235" />

    <col width="325" />

    <col width="155" />
  </colgroup>

  <thead>
    <tr>
      <th>ID</th>
      <th>Scenario</th>
      <th>Setup</th>
      <th>Steps</th>
      <th>Criticality</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>OFR-08</td>
      <td>Expired or disabled offer</td>
      <td>The expired test offer, and one you disable by hand</td>
      <td>Validate each. Check `invalid_offers` carries `reason: offer_expired` and `offer_inactive` respectively. Check your UI no longer shows the offer and checkout continues at full price.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-09</td>
      <td>Cart edits drop the order below the offer minimum</td>
      <td>Match with a qualifying cart, then remove an item</td>
      <td>Match shows the offer. Remove an item so the order falls below `min_amount`, and validate. Check `reason: order_amount_below_minimum` with `field: order.amount`. Check you re-run Match on every cart change, so a stale offer never reaches Pay.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-10</td>
      <td>Wrong SKU or brand on a SKU-level offer</td>
      <td>The SKU-level test offer; a SKU it doesn't cover, then a wrong brand</td>
      <td>Validate with a `sku` outside the offer's list. Check `reason: sku_not_mapped_to_offer`, with `field` pointing at the exact line item. Repeat with a mismatched `brand`. Check `brand_not_matched`. Check brand matching ignores case: `"Apple"` and `"apple"` both pass when the brand is right.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-11</td>
      <td>Usage limit reached, or partially reached</td>
      <td>The per-card-limit test offer; a customer near the cap</td>
      <td>Validate with a `quantity` above the customer's remaining allowance, passing `customer` identifiers. Check `eligible_quantity` comes back lower than requested, your price math uses the lower number, and the UI explains the partial discount. Use up the limit fully and check `quantity_exceeds_offer_limit`.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-14</td>
      <td>Invalid requests return 400 and name the failing field</td>
      <td>Bad inputs, one at a time</td>
      <td>Send a few deliberately invalid requests, for example: more than 20 offer IDs (20 is the most you can pass in the `offers` array in one request); an `offers[]` entry without an `id`; a SKU-level offer without `line_items`; `quantity: 0`; Validate without `payment_instrument`. Check each returns HTTP 400 with `reason: input_validation_failed` and a precise `field`. Check your code logs these as integration bugs and never shows them to the customer as payment failures.</td>
      <td>Should pass</td>
    </tr>

    <tr>
      <td>OFR-16</td>
      <td>Offers service is unavailable</td>
      <td>Razorpay test mode cannot produce an outage, so stand in for the API yourself: in your test environment, point the Match call at a stub server that returns errors or times out ([Simulating Failures](#simulating-failures))</td>
      <td>Run the checkout against the failing stub. Check the checkout renders without offers and payment still works end to end. Check retries back off instead of looping.</td>
      <td>Good to have</td>
    </tr>
  </tbody>
</table>

## Common Integration Gaps to Avoid

| Gap | What goes wrong | Do instead |
| - | - | - |
| Sending the discounted amount to Create Payment | Amount mismatch failures, or double discounting | Always send the original order amount; Razorpay applies the discount (OFR-05). |
| Treating Match as a reservation | The customer sees an offer, loses it at pay time, and the payment fails unexpectedly | Match is a preview. Validate at Pay, and handle pay-time offer failure with a clean retry path (OFR-07). |
| Not re-validating after instrument or cart changes | Stale offers ride into the payment and fail, or the customer is overcharged relative to the displayed price | Re-run Match on cart change, re-run Validate on instrument change (OFR-06, OFR-09). |
| Matching on `description` text | Writing conditions against the display text, like checking whether the description contains "expired". The text is customer-facing copy and can be reworded any time, so the check breaks silently. | Branch on `validity.reason` / `error.reason` and `field`; those are stable. |
| Fulfilling discounts from the Match or Validate response | Ledger drift when the applied set differs from the previewed set | Reconcile from Fetch Order `offers_applied` where `status = redeemed` (OFR-04). |
| `offers[]` drift between Validate and Create Payment | Undefined application behaviour, support escalations | Pass the identical array to both calls. |
| Omitting `line_items` for SKU-level offers | SKU offers silently never match, which looks like "offers don't work" | Send the full cart in Match and the offer's qualifying lines in Validate and Create Payment. |
| Skipping `customer` identifiers | Match checks per-customer usage limits only when identifiers are present. Without them it can show offers this customer has already exhausted, and the failure surfaces only at pay time. | Pass `contact`, `email`, `card_number` whenever available. |
| Hard-coding offer IDs in checkout logic | Breaks every time an offer campaign rotates | Drive the UI entirely from the Match response. |

## Best Practices

* **Decide upfront what happens when an offer fails at payment time.** The offer's configuration controls it: fail the payment, or continue without the offer. If your offers fail the payment, build the retry path (OFR-07). Separately, keep the display path safe: wrap Match in a timeout (1 to 2 seconds) and render the checkout without offers if it errors.
* **Call Match again whenever the cart changes.** Results are specific to the cart you sent. If the call included `customer` identifiers, the results are specific to that customer too, so never reuse them for another customer.
* **Validate once the full instrument is known.** Running it as soon as the card number is complete is common and fine. Re-validate if the instrument or the cart changes after that, and avoid firing it on every keystroke.
* **Display price = order amount − Σ valid `calculated_benefit_value` of `instant_discount` and `no_cost_emi` benefits.** Cashback changes the messaging, not the charged amount.
* **Reconcile after capture**: once the payment is captured, fetch the order with `expand[]=offers` and persist `offers_applied` against your order. Treat that record as the source of truth for invoices and refunds.
* **Log `validity.reason` distributions** in production. A spike in `instrument_not_eligible` or cap-exhaustion failures is your earliest signal of a misconfigured campaign.

### Go-Live Checklist

1. All seven [must-have scenarios](#must-have) pass.
2. Live keys replace test keys; the offers you tested against exist in live mode (test and live offers are separate).
3. Payment `amount` is always the original order amount, never the discounted amount.
4. Validation runs once the full instrument is known, and again after any instrument switch or cart edit.
5. You know your offers' pay-time failure configuration (fail the payment vs continue without the offer) and have tested the path you chose (OFR-07).
6. Fulfilment and invoicing read from Fetch Order `offers_applied`, not from Match or Validate responses.
7. Refund ceilings come from `amount_paid`.

## Errors

### API 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` | — |
| Validate Offers | 400 | `offers` is missing or has more than 20 entries. | `input_validation_failed` | `offers` |
| Validate Offers | 400 | An offer `id` is missing. | `input_validation_failed` | `offers[n].id` |
| Validate Offers | 400 | A line item `sku` or `brand` is missing. | `input_validation_failed` | `offers[n].line_items[m].sku` or `offers[n].line_items[m].brand` |
| Validate Offers | 400 | A line item `quantity` is less than 1. | `input_validation_failed` | `offers[n].line_items[m].quantity` |
| Validate Offers | 400 | `payment_instrument` is missing. | `input_validation_failed` | `payment_instrument` |
| Fetch Order | 400 | `expand[]` has an unsupported value. | `input_validation_failed` | `expand` |
| Fetch Order | 404 | The order does not exist or belongs to another account. | `order_not_found` | — |
| All | 401 | The API key is invalid or missing. | `authentication_failed` | — |

```json Sample Error Response theme={null}
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "offers[0].line_items[0].sku is required",
    "source": "business",
    "step": "offer_validate",
    "reason": "input_validation_failed",
    "field": "offers[0].line_items[0].sku",
    "metadata": {}
  }
}
```

### Validation Failure Reasons

When an offer fails an eligibility check, Validate Offers returns HTTP `200` and lists the offer in `invalid_offers` with a `validity` object.

| `reason` | Scenario | `validity.field` |
| - | - | - |
| `sku_not_mapped_to_offer` | The SKU is not in the offer's eligible SKU list. | `offers[n].line_items[m].sku` |
| `brand_not_matched` | The brand does not match the offer's brands. | `offers[n].line_items[m].brand` |
| `quantity_below_minimum` | The quantity is below the offer's `min_quantity`. | `offers[n].line_items[m].quantity` |
| `quantity_exceeds_offer_limit` | The quantity is above the per-SKU limit for this customer. | `offers[n].line_items[m].quantity` |
| `offer_expired` | The offer's `ends_at` has passed. | `offers[n].id` |
| `offer_inactive` | The offer is not active. | `offers[n].id` |
| `offer_budget_exhausted` | The offer's total budget is used up. | `offers[n].id` |
| `offer_not_found` | The offer does not exist or belongs to another account. | `offers[n].id` |
| `instrument_not_eligible` | The payment instrument does not meet the offer's conditions. | `payment_instrument` |
| `order_amount_below_minimum` | The order amount is below the offer's `min_amount`. | `order.amount` |
| `order_amount_above_maximum` | The order amount is above the offer's `max_amount`. | `order.amount` |

```json Sample Response theme={null}
{
  "valid_offers": {
    "entity": "collection",
    "count": 0,
    "items": []
  },
  "invalid_offers": {
    "entity": "collection",
    "count": 1,
    "items": [
      {
        "entity": "offer",
        "id": "offer_CART_002",
        "validity": {
          "valid": false,
          "reason": "order_amount_below_minimum",
          "description": "Order amount ₹95,000 is below the minimum required amount of ₹1,00,000 for this offer.",
          "field": "order.amount"
        }
      }
    ]
  }
}
```

## Related Information

* [Offers - S2S Integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/offers.md)
* [About Offers](https://razorpay.com/docs/payments/offers)
* [Create Offers](https://razorpay.com/docs/payments/offers/create.md)
* [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)
