Apply coupon for a client.


POST /coupons/apply

Query Parameters

  • type (query parameter): Type of action: redeem or revert (mandatory)


  • coupon_details (array of object): coupon details (mandatory)
    • coupon_id (string): coupon id or "bulk" (when using bulk user coupons) (mandatory)
    • coupon_code (string): coupon id (mandatory)
  • source_id (string): source id (optional)
  • order : Order details (optional)
    • original_amount (float64): original amount (mandatory)
    • selling_amount (float64): selling amount (mandatory)
    • status (string): status [pending, completed, reverted] (optional)
    • shipping (float64): shipping (optional)
    • tax (float64): tax (optional)
    • payment_mode (string): payment mode (optional)
    • metadata(object): metadata (optional)
      • key1 (string): meta key 1
      • key2 (float64): meta key 2
    • items (array of object): product items (optional)
      • original_price (float64): original price (mandatory)
      • selling_price (float64): original price (mandatory)
      • product_id (string): product id (mandatory)
      • sku (string): sku (optional)
      • name (string): name (optional)
      • quantity (float64): quantity (optional)
      • metadata(object): metadata (optional)
        • itemkey1 (string): meta key 1
        • itemkey2 (float64): meta key 2


  • 200 OK

  • 400 Bad Request

    • Response:
      • code (error code): NOT_FOUND_CODE
      • message (error message): Campaign not found details
      • details (error details): Error details
      • request_id (string): Request ID


  • Basic Authentication


This endpoint requires Basic Authentication.

  • Username: apiKey
  • Password: apiSecret

Request Body Example

  "coupon_details": [{
    "coupon_id": "coupm_rq4XiTPbrhq0d0i92EkSx",
    "coupon_code": "CUP-21"
  "source_id": "customerA_123",
  "order": {
    "order_id": "order_123",
    "status": "pending",	
    "original_amount": 190,
    "selling_amount": 135.97,
    "shipping": 5.0,
    "tax": 3.47,
    "payment_mode": "UPI",
    "metadata": {
      "created_by": "JohnDoe",
      "created_date": "2023-06-13T10:00:00",
      "source": "Website"
    "items": [
        "product_id": "ABC123",
        "sku": "SKU123",
        "name": "Example Product 1",
        "original_price": 190.99,
        "selling_price": 149.99,
        "quantity": 2,
        "metadata": {
          "color": "blue",
          "size": "L"


Rehook Platform API provides resource oriented URLs to work with your business data. Our API uses JSON for request and response. API errors are returned using standard HTTP response codes.


Redeem API will enable you to redeem an applied code after transaction is successful on your application.
Revert API will enable you to revert a redeemed coupon code if pending transaction failed or successful transaction is cancelled.

API details

API Endpoint: https://api.rehook.ai/coupons/apply



  1. API Key and Secret Key for your application
  2. If you don't know the API key and secret key, please go to setting module on admin panel to view API details for your application. To know more about application setting, please visit Application setting
  3. API key and secret key are auto generated and cannot be changed.


You need to provide the API key and Secret of your application in every new request as Authorisation. Rehook use Basic authentication method to authenticate the API calls.

UsernameAPI key of your application
PasswordSecret key of your application


Query Parameters (Mandantory)

typeredeemYou have to use this as query parameter to redeem a coupon code
typerevertYou to have use this as query parameter to revert a redeemed coupon code

Body Parameters

Please refer to the complete request body as given below.

    "coupon_details": [
    "order": {
        "order_id": "1223456",
        "status": "pending",
        "original_price_subtotal": 800,
        "selling_price_subtotal": 800,
        "shipping": 100,
        "payment_mode": "UPI",
        "metadata": {
            "cart_qty": "4"
        "items": [
                "product_id": "123",
                "sku": "",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 1,
                "shipping": 0,
                "metadata": {
                    "brand": "brand A",
                    "category": "grocery"
                "product_id": "654",
                "sku": "",
                "brand": "wrangler",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 2,
                "shipping": 0,
                "metadata": {
                    "brand": "brand B",
                    "category": "vegetables"

Parameters without an object (Optional)

Filed nameData typeDefinitionExample
Unique customer Id of your application

Order details object (Mandatory)

Field nameData typeDefinitionExample
Unique transaction Id from your application
Sum of original price of all the items (MRP)
[selling_price * quantity]
Sum of selling price of all the items
[original_price * quantity]
Status of transaction from your application.
'pending', 'completed', 'reverted'
shipping charge at an order
total tax amount applied at an order

Item details - Array of object (Mandatory)

Field nameData typeDefinitionExample
Product identification id from your application
Assigned SKU to a product from your application
name of the product
original price of the product or MRP
selling price of the product
quantity of the product in the cart
shipping charge at an item level (value is not mandantory but you have to this field in all the payload)

Coupon details object(Mandatory)

Filed nameData typeDefinitionExample
coupon id generated by Rehook against fixed coupon distributed
coupon code entered or applied by customer on your application

Meta data (Optional)

You can provide the meta data in order object or item object using key value pair

meta data key namemeta data value
Key 1value 1
Key 2value 2


meta data key namemeta data value


Meta data -limitation

  1. Meta data details are optional in the request body.
  2. If you want to pass any other custom fields in the API payload, then such fields can be passed as key value pairs inside metadata object.
  3. Our system will validate the meta data only if same meta data with key value pair with same data type is created in any campaign on rebook dashboard, otherwise, Rehook API will nullify the meta data provided in the request body.
  4. Meta data object can be passed at order or item level.

Sample request body

Below table shows what details to be shared in the request body in following cases.

Casewhen to call APIQuery parameterRequest bodyResponse
RedeemWhen transaction is success or pendingredeemSource Id + coupon details object + Order object with mandatory fields + Item object with mandatory fieldsGiven coupon code will be validated and redeemed.
RevertWhen pending transaction is failed and successful transaction is cancelled.revertSource Id + coupon details object + Order object with mandatory fields + Item object with mandatory fieldsRedeemed coupon code will be reverted and will be available for redeemption.

Sample request body and API behaviour details are given below for the above mentioned cases:

Complete payload for redeem or revert

complete payload details are given above


API Behaviour:

  • Above payload contains the complete details of API payload for coupon redemption.
  • Coupon details are mandatory and primary fields in redemption API call
  • You have to pass the query parameter as redeem or revert to let Rehook know that whether coupon is to be redeemed or reverted.
  • Coupon cannot be redeemed for non logged in users. you have to pass the source id mandatory in all redeem or revert API call, otherwise API will return error message.
  • You have to share the mandatory fields of order and item object in redeem or revert API call to validate the coupon conditions if you have not validated it using validate coupon API. this works as a fall mechanism to avoid redeeming inapplicable coupon codes.

Success Response:

If API call is successful, then Rehook will return the following HTTP success code with response body as given below:

HTTP CodeMessage

Sample response JSON body

case 1: when coupon is redeemed

    "status": "completed",
    "couponId": "coupm_9ZbJ2ryi4ia2eyz6I7sRc",
    "orderId": "122346",
    "request_id": "d45e39f3-7506-9f63-9cdc-c364c93ff706",
    "coupon_code": "WHOLECART"

case 2: when coupon is reverted

    "status": "reverted",
    "couponId": "coupm_9ZbJ2ryi4ia2eyz6I7sRc",
    "orderId": "122346",
    "request_id": "501c3450-ef12-99a5-8e84-5aa1801c2411",
    "coupon_code": "WHOLECART"

sample response fields and definition

couponIdcouponId passed in the request body for which redemption or revert to be doneabc_123
coupon_coderedeemed coupon codeDIWALI123
orderIdTransaction id of your application for which redemption or revert to be donekmn123
request_idAPI request Id generated by Rehookrehook123
statusstatus of redemption/revertcompleted/reverted

Error Responses

If API call is failed, then Rehook will return the following HTTP success code with response body as given below:

HTTP CodeMessage
400bad request

error response body

field namedescriptionexample
CodeError code400
detailsError detailsGiven coupon code is wrong
messageerror messagecoupon_code not found
request_idAPI request Id assigned by Rehookabc_123

Below table shows possible list of cases with error messages

CaseError message
Wrong source id is passedmessage: Invalid payload

error details: Invalid source_id
API Key or Secret is wrongmessage: Unathourized

error details: app id or app secret invalid
Mandatory fields are not passed in the order or item object.message: Invalid payload

error details: selling_price is required
coupon validation failedmessage: coupon validation failed

error details: selling_price should be greater than 200.00
coupon_code or coupon_id is wrongmessage: Invalid coupon code or coupon id

error details: coupon not found, invalid coupon code or coupon id
coupon_id or coupon_code missing in the request bodymessage: coupon_code or coupon_id is missing,
error details: coupon id or coupon code is required
query parameter is wrongmessage: Invalid query param

error details: type should be redeem or revert
for selected items validation, when validation is not satisfiedmessage: Discount validation is failed, please check terms and condition in the coupon tray'
when selected items none of the product property is not foundmessage: Discount validation is failed, please check terms and condition in the coupon tray'
when Discount validation is failed (in case of product validation )sample message 1: selling_price should be greater than 200
sample message 2: cart_qty should be greater than 10
Click Try It! to start a request and see the response here!