post https://api.rehook.ai/coupons/apply

FetchAllClientCoupons

Description

Apply coupon for a client.

Endpoint

POST /coupons/apply

Query Parameters

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

Parameters

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

Responses

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

Security

Basic Authentication

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.

Introduction

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

HTTP Method: POST

Prerequisites

API Key and Secret Key for your application
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
API key and secret key are auto generated and cannot be changed.

Authentication

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.

Authorization	Value
Username	API key of your application
Password	Secret key of your application

Parameters

Query Parameters (Mandantory)

key	value	Scope
type	redeem	You have to use this as query parameter to redeem a coupon code
type	revert	You 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": [
        {
            "coupon_id":"coupm_tfKRcTxedjr17FH3m267V",
            "coupon_code":"KS"
        }
    ],
    "source_id":"krish123",
    "order": {
        "order_id": "1223456",
        "status": "pending",
        "original_price_subtotal": 800,
        "selling_price_subtotal": 800,
        "shipping": 100,
        "tax":20,
        "payment_mode": "UPI",
        "metadata": {
            "cart_qty": "4"
        },
        "items": [
            {
                "product_id": "123",
                "sku": "",
                "name":"",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 1,
                "shipping": 0,
                "metadata": {
                    "brand": "brand A",
                    "category": "grocery"
                }
            },
             {
                "product_id": "654",
                "sku": "",
                "name":"",
                "brand": "wrangler",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 2,
                "shipping": 0,
                "metadata": {
                    "brand": "brand B",
                    "category": "vegetables"
                }
            }
        ]
    }
}

Parameters without an object (Optional)

Filed name	Data type	Definition	Example
source_id	string	Required Unique customer Id of your application	Krishna_123

Order details object (Mandatory)

Field name	Data type	Definition	Example
order_id	string	Mandatory Unique transaction Id from your application	rehook12345
original_price_subtotal	Int	Mandatory Sum of original price of all the items (MRP) [selling_price * quantity]	500
selling_price_subtotal	float64	Mandatory Sum of selling price of all the items [original_price * quantity]	300
status	string	Mandatory Status of transaction from your application.	'pending', 'completed', 'reverted'
shipping	float64	Optional shipping charge at an order	30
tax	float64	Optional total tax amount applied at an order	20

Item details - Array of object (Mandatory)

Field name	Data type	Definition	Example
product_id	string	Required Product identification id from your application	abc_124
sku	string	Optional Assigned SKU to a product from your application	124
name	string	Optional name of the product	Coke
original_price	float64	Required original price of the product or MRP	100
selling_price	float64	Required selling price of the product	80
quantity	float64	Optional quantity of the product in the cart	2
shipping	float64	mandantory shipping charge at an item level (value is not mandantory but you have to this field in all the payload)	10

Coupon details object(Mandatory)

Filed name	Data type	Definition	Example
coupon_id	string	Required coupon id generated by Rehook against fixed coupon distributed	coupon_123
coupon_code	string	Required coupon code entered or applied by customer on your application	DIWALI100

Meta data (Optional)

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

meta data key name	meta data value
Key 1	value 1
Key 2	value 2

Example:

meta data key name	meta data value
color	blue
size	L

📘
Meta data -limitation

Meta data details are optional in the request body.

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.

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.

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.

Case	when to call API	Query parameter	Request body	Response
Redeem	When transaction is success or pending	redeem	Source Id + coupon details object + Order object with mandatory fields + Item object with mandatory fields	Given coupon code will be validated and redeemed.
Revert	When pending transaction is failed and successful transaction is cancelled.	revert	Source Id + coupon details object + Order object with mandatory fields + Item object with mandatory fields	Redeemed 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 Code	Message
200	Ok

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

Field	definition	example
couponId	couponId passed in the request body for which redemption or revert to be done	abc_123
coupon_code	redeemed coupon code	DIWALI123
orderId	Transaction id of your application for which redemption or revert to be done	kmn123
request_id	API request Id generated by Rehook	rehook123
status	status of redemption/revert	completed/reverted

Error Responses

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

HTTP Code	Message
400	bad request

error response body

field name	description	example
Code	Error code	400
details	Error details	Given coupon code is wrong
message	error message	coupon_code not found
request_id	API request Id assigned by Rehook	abc_123

Below table shows possible list of cases with error messages

Case	Error message
Wrong source id is passed	message: Invalid payload error details: Invalid source_id
API Key or Secret is wrong	message: 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 failed	message: coupon validation failed error details: selling_price should be greater than 200.00
coupon_code or coupon_id is wrong	message: 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 body	message: coupon_code or coupon_id is missing, error details: coupon id or coupon code is required
query parameter is wrong	message: Invalid query param error details: type should be redeem or revert
for selected items validation, when validation is not satisfied	message: Discount validation is failed, please check terms and condition in the coupon tray'
when selected items none of the product property is not found	message: 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

Redeem or revert a coupon for a customer

FetchAllClientCoupons

Description

Endpoint

Query Parameters

Parameters

Responses

Security

Authentication

Request Body Example

Introduction

API details

Prerequisites

Authentication

Parameters

Query Parameters (Mandantory)

Body Parameters

📘
Meta data -limitation

Sample request body

Complete payload for redeem or revert

📘
API Behaviour:

Success Response:

Error Responses

Introduction

API details

Prerequisites

Authentication

Parameters

Query Parameters (Mandantory)

Body Parameters

📘Meta data -limitation

Sample request body

Complete payload for redeem or revert

📘API Behaviour:

Success Response:

Error Responses

📘
Meta data -limitation

📘
API Behaviour: