Body
Offer List
API for listing the ACTIVE offers at a particular point in time based on the configurations in the offers operations dashboard.
List Offers API filters through the complete set of Merchant offers configured in the DB and provides key details per offer such as:
Offer description and terms
Offer eligibility for the current transaction
Offer benefits with calculation rules (Discount / Cashback / EMI Discount Value)
Order amount pre/post discount
Eligible payment instruments/methods for an offer
Eligible Products along with offer breakup for each of the product
Note
Optimistic Behaviour : List Offers API has an Optimistic behaviour wherein if any param is not passed in the request, Offer engine will assume that this param will be received in the later part of the journey and hence response will be given without evaluating this param at that point.
This is due to the fact that ListOffers can be called at any point in the consumer Journey like Home page, Product details page, Cart, Payment page etc. where certain information might not be available.
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/v1/offers/list
Production Link
POST
https://api.juspay.in/v1/offers/list
Authorization Header
Basic Auth
*
Base64 Encoded Username:Password
Mandatory
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
x-merchantid
*
string
Required
The merchant id that a merchant hold at Juspay.
Content-Type
String
application/json
x-routing-id
*
String
Required
We recommend passing the customer_id as the x-routing-id. If the customer is checking out as a guest, you can pass an alternative ID that helps track the payment session lifecycle. For example, this could be an Order ID or Cart ID.
Warning
This ID is associated with the customer. It plays a key role in ensuring consistency and maintaining connections across different systems. If you fail to pass the same x-routing-id for the same customer in all related API calls, it could lead to issues with API functionality. Therefore, it’s crucial that you use the same x-routing-id for all requests tied to the same customer.
Example:- customer_1122
Query Params
?emi=true
string
Used when there are offers configured for EMI Option. For displaying EMI based offers, ?emi=true should be sent in API request. If not sent, then EMI based offers will not be returned in the response even if EMI offers were configured on the dashboard
Parameters
order
object
Order level details
order_id
string
Unique ID generated by JusPay for the given order
amount
*
string
Required
Order Amount
currency
*
string
Required
Currency passed during order creation
payment_channel
string
Payment channel used for making transaction. Possible values ANDROID, IOS, WEB and MWEB
udf1
string
The user defined fields passed during order creation
udf2
string
The user defined fields passed during order creation
udf3
string
The user defined fields passed during order creation
udf4
string
The user defined fields passed during order creation
udf5
string
The user defined fields passed during order creation
udf6
string
The user defined fields passed during order creation
udf7
string
The user defined fields passed during order creation
udf8
string
The user defined fields passed during order creation
udf9
string
The user defined fields passed during order creation
udf10
string
The user defined fields passed during order creation
basket
Stringified Array of Objects
List of Products/SKU details for Offer application
id
*
String
Mandatory
Unique ID for the product where offer eligibility/applicability checks needs to be performed
quantity
*
integer
Mandatory
Number of items against a particular product
unitPrice
*
Double
Mandatory
Price of the individual product
split_amount
String
Amount of the split transaction. Should be passed only for split transaction flows
amount_info
Stringified Object
Contains Price breakup of the cart amount. Can be used when Offer shouldn’t be applied on components like tax, delivery fees etc.
Note :
Sum of the amounts in amount_info should be equal to the order amount
base_amount
*
String
Mandatory
Base price value of the cart
add_on_amounts
Array of Objects
Any additional components of the cart. Eg : tax, delivery fees etc
name
*
String
Mandatory
Name of the additional component
Supported Values : DELIVERYCHARGE, DELIVERYTIP, DONATION, SURCHARGE, TAX, OTHERCHARGES, PACKINGCHARGE
amount
*
String
Mandatory
Amount of the corresponding additional component
payment_method_info
object
Array of Payment Method Information
payment_method_reference
*
string
Required
Unique identifier that can be sent by the merchant for the respective Payment Instruments
payment_method_type
string
Payment Method Type of the transaction. Possible values are "CARD" | "NB" | "UPI" | "WALLET" | "REWARD"
payment_method
string
Payment Method of the transaction
card_number
string
Valid Card Number
card_token
string
A valid card token obtained using /card/list API
card_alias
string
Unique identifier received from Payv3 (Only for Payv3 integrations).
card_type
string
Card type of the valid card.(Only for Payv3 integrations).
bank_code
string
Bank Code
card_bin
string
Card bin of the valid card
card_sub_type
string
Card subtype of the valid card
upi_vpa
string
Valid VPA of the customer
upi_app
string
UPI App package name
txn_type
string
UPI transaction type. Possible values are UPI_PAY, UPI_COLLECT
is_emi
String
To Fetch EMI Offer for that praticular intsrument
Example:- True/False
customer
object
id
string
Customer id passed during order creation
email
string
Email Id of the customer passed during order creation
phone
string
Phone number of the customer passed during order creation
offer_code
string
Coupon code configured on Juspay Dashboard
200 : Success
Response Body
best_offer_combinations
Object
Contains details of the best offers against an order, mapped to eligible payment types sent in the request
payment_method_reference
String
Unique payment method reference ID sent in request body
offers
Object
Offer details for the best offer available against the above payment_method_reference
offer_id
*
String
Mandatory
Unique offer ID of the eligible offer
cashback_amount
*
String
Mandatory
Cashback amount benefit associated with the offer
discount_amount
*
String
Mandatory
Discount amount benefit associated with the offer
merchant_discount_amount
*
String
Mandatory
Offer amount that needs to be validated for a given order. Merchant discount benefit is used to validate offer and order amount in the backend and payment locking in the payment page
total_offered_amount
String
Total offer benefit amount associated with the offer ID
order_breakup
*
String
Mandatory
Order details breakup
order_amount
*
String
Required
Order amount before offer is applied (for merchant discount benefit, this is the amount post application of offer)
applicable_order_amount
*
String
Required
Order amount applicable for calculation of offer
final_order_amount
*
String
Required
Final order amount after offer has been applied
discount_amount
*
String
Required
Discount amount applied on order
merchant_discount_amount
*
String
Required
Offer discount amount that should be validated in the back end
cashback_amount
*
String
Required
Cashback amount applied on order
offer_amount
*
String
Required
Total offer amount applicable on the order
benefits
*
Object
Required
Breakdown of benefits on the order
type
Enum
Benefits type, can be either CASHBACK | DISCOUNT | MERCHANT_DISCOUNT | EMI_DISCOUNT | EMI_CASHBACK
calculation_rule
Enum
Calculation rule for offer, can be either PERCENTAGE | ABSOLUTE
amount_info
String
List of strings that shows order amount elements on which offer has been applied
product_discounts
Object
Product level offer breakdown
product_id
String
Unique identifier for products
product_quantity
Integer
Quantity of product in an order
product_applicable_quantity
Integer
Applicable product quantity to calculate offer
unit_price
String
Price per unit of offer
discount_amount
String
Discount applicable on order amount
cashback_amount
String
Cashback applicable on order amount
merchant_discount_amount
String
Amount to be validated in the backend for a product
capped_instant_discount_amount
String
Maximum discount applicable on a product
capped_cashback_amount
String
Maximum cashback applicable on a product
emi_discount
Object
EMI discount/cashback applicable on a product based on tenure and interest rate
offers
Object
Breakdown of active offers based on offers configured on the dashboard by merchant
offer_id
*
String
Mandatory
Unique ID associated with active offers
status
*
String
Mandatory
Status of the offer, can be either ACTIVE or INACTIVE
offer_code
*
String
Mandatory
Offer code configured by merchant on the offers dashboard
offer_description
*
Object
Mandatory
Offer description details including title, description, tnc etc
ui_configs
*
Object
Mandatory
UI configuration details of an offer
application_mode
*
Enum
Mandatory
Product application mode of an order, can be either PRODUCT | LINE_ITEM | ORDER
offer_rules
*
Object
Mandatory
Order rules breakdown with amount and payment instrument detail
amount
json
Offer benefit amount associated with an offer ID
order_basket
json
Order basket with product level details uploaded along with WHITELIST/BLACKLIST specification for those offers
platform
json
Platforms on which offers are applicable
additional_payment_filters
json
EMI eligibility rules for the offer with tenure and bank details
customer
json
WHITELIST/BLACKLIST of customer IDs that were uploaded during offer configuration
payment_instrument
json
Eligible payment instruments for an offer
gateways
json
WHITELIST/BLACKLIST of gateways that were uploaded during offer configuration
filters
json
WHITELIST/BLACKLIST of filters that were uploaded during offer configuration
txn_type
json
Specifying the transaction type for an offer - can be ORDER (full swipe transactions) or EMI (EMI transactions)
order_breakup
Object
Order level breakdown with details
eligible_saved_payment_methods
*
String
Mandatory
Eligible payment methods (for ELIGIBLE offers) based on the payment_method_reference sent as request
400 : Invalid Input data
Response Body
json
json
401 : Authentication Failed
Response Body
json
JSON
API Latency Guidelines
What is API Latency?
Time taken by the server to respond to the API request.
Average API Percentile Metrics and Recommended Timeout
TP50 (ms): This represents the median latency, meaning 50% of all requests are completed in this time or less. It indicates the typical performance experienced by the majority of users.
TP90 (ms): This value shows that 90% of requests are completed within this time, leaving 10% of requests that take longer. It gives insight into the performance for a broader set of users, beyond the median.
TP99 (ms): This value indicates that 99% of requests finish within this time, with only 1% of requests taking longer. It helps identify outlier cases where latency may become an issue for a small group of users.
TP99.9 (ms): This metric captures extreme latency outliers, where only 0.1% of requests take longer than this value. It’s useful for understanding edge cases where performance degrades for very few users.
TP99.99 (ms): This measures the most rare and severe performance outliers, where just 0.01% of requests exceed this time. Monitoring this helps in addressing the rarest and most critical latency issues that may impact user experience in exceptional scenarios.
Scroll inside to view more
|
Transaction Percentile
|
Latency (ms)
|
|---|---|
TP50 (ms)
| 49.277
|
TP90 (ms)
| 128.11
|
TP99 (ms)
| 404
|
TP99.9 (ms)
| 640.38
|
Recommended Timeout(ms)
| 1000
|
2 columns 6 rows
Warning
The recommended timeouts are based on TP99.9 data, though edge cases (0.01% of requests) may still exceed these limits and are captured in the TP99.99 data as shown below.
Scroll inside to view more
|
Transaction Percentile
|
Latency (ms)
|
|---|---|
TP99.99 (ms)
| 4456.05
|
Recommended Timeout(ms)
| 5000
|
2 columns 3 rows