Redeem bulk coupons

post

https://{host}/v2/coupon/bulk/redeem

Lets you redeem one or more coupons of a customer.

👍
Notes

A maximum of 50 coupons can be redeemed in a single API request.

The coupon redemption and crediting of the coupon to the wallet functionality are available only in the v1.1 API. The v2 API is designed to redeem coupons directly.

VoucherRedemptionevent is triggered only during the single coupon redemption.

🚧
Warning
Bulk coupon redemption will fail if even one of the coupons is invalid. For example, if you submit a request with 50 coupons and just one is either invalid or not issued to the user, the entire redemption will be unsuccessful. There is no option for partial success in bulk redemptions.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/coupon/bulk/redeem' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWFkaHMjU2YQ==' \
--header 'Cookie: _cfuvid=O1NeiUP6e9UsP1Qo1DtGPkZlkdoRXAs5h62Q4uuK9X4-1759131316915-0.0.1.1-604800000' \
--data '{
    "redemptionRequestList": [
        {
            "code": "IG950B8F"
        },
        {
            "code": "NZX4HM3T"
        }
    ],
    "redemptionTime": "2025-09-28T14:00:00+05:30",
    "transactionNumber": "txn-38",
    "user": {
        
        
       
        "externalId": "07072001"
    },
    "billAmount": "3500"
}'

Prerequisites

Authentication: Basic or OAuth authentication
Default access group

Resource information


URI	v2/coupon/bulk/redeem
HTTP method	POST
Pagination	NA
Batch support	NA

Rate limit

Demo, Production and Testing Clusters: 1000 requests per minute per API key

To modify the limit, create a ticket with the Capillary Product support team.

Request query parameter

Parameter	Data type	Description
is_redeemable	Boolean	Specifies whether the coupon is redeemable. When you set `isredeemable=true`, the API checks redeemability and returns the result in the response without performing a redemption. If the coupon is redeemable: The response will include `redemptionStatus.message = "Coupon redemption successful"`. Notes: Coupons are not redeemed when `isredeemable=true` is used. It only checks the status. You can also use this to check the status for multiple coupon codes at once. To add multiple codes, you can add it as an array of objects, where each object contains a code field.

Parameter

Data type

Description

is_redeemable

Boolean

Specifies whether the coupon is redeemable. When you set isredeemable=true, the API checks redeemability and returns the result in the response without performing a redemption. If the coupon is redeemable: The response will include redemptionStatus.message = "Coupon redemption successful".

Notes: Coupons are not redeemed when isredeemable=true is used. It only checks the status. You can also use this to check the status for multiple coupon codes at once. To add multiple codes, you can add it as an array of objects, where each object contains a code field.

Request Body parameter

Parameter	Description
redemptionRequestList	List of coupons to redeem.
code*	Coupon code to redeem. To redeem multiple codes you can add it as an array of objects, where each object contains a code field.
redemptionTime	The date and time when the coupon is going to be redeemed in YYYY-MM-DD HH:MM:SS format. The time defined here is used for certain evaluations, but it is not stored in the system. The system considers the store's current time as the redemption time.
transactionNumber	Transaction number for which the coupon(s) needs to be redeemed.
billAmount*	Transaction amount for which the coupon is redeemed.
user	Details of the customer that redeems the coupon(s).
id	Unique ID of the customer.
mobile*	Unique mobile number of the customer.
email*	Unique email ID of the customer.
externalId*	Unique external ID of the customer.

*Any one of the customer identifiers is mandatory.

Example response

{
    "response": [
        {
            "entityId": 1349127408,
            "result": {
                "redemptionId": "18958125",
                "id": 1349127408,
                "currencyInput": false,
                "localToBaseCurrencyExchangeRate": 0,
                "warnings": [],
                "appendedErrorMessage": "",
                "code": "IG950B8F",
                "discountCode": "NO_VALUE",
                "seriesCode": 865240,
                "isAbsolute": false,
                "couponValue": 10.0,
                "redemptionStatus": {
                    "statusCode": {
                        "status": true,
                        "code": 700,
                        "message": "Coupon processing successful"
                    },
                    "warnings": [],
                    "warningsAsStatusCode": [],
                    "code": 700,
                    "success": true,
                    "message": "Coupon processing successful"
                },
                "discountType": "PERC",
                "discountValue": 10,
                "discountUpto": 100
            },
            "errors": []
        },
        {
            "entityId": 1349127292,
            "result": {
                "redemptionId": "18958124",
                "id": 1349127292,
                "currencyInput": false,
                "localToBaseCurrencyExchangeRate": 0,
                "warnings": [],
                "appendedErrorMessage": "",
                "code": "NZX4HM3T",
                "discountCode": "NO_VALUE",
                "seriesCode": 865240,
                "isAbsolute": false,
                "couponValue": 10.0,
                "redemptionStatus": {
                    "statusCode": {
                        "status": true,
                        "code": 700,
                        "message": "Coupon processing successful"
                    },
                    "warnings": [],
                    "warningsAsStatusCode": [],
                    "code": 700,
                    "success": true,
                    "message": "Coupon processing successful"
                },
                "discountType": "PERC",
                "discountValue": 10,
                "discountUpto": 100
            },
            "errors": []
        }
    ],
    "totalCount": 2,
    "failureCount": 0
}

Response body parameter

Parameter	Description
entityId	Unique identifier for the entity.
result.id	Unique ID of the result.
result.currencyInput	Indicates if currency input is present.
result.localToBaseCurrencyExchangeRate	Exchange rate from local currency to base currency.
result.code	Code associated with the result.
result.discountCode	Code indicating the type of discount.
result.seriesCode	Code associated with the series.
result.isAbsolute	Indicates if the value is absolute.
result.couponValue	Value of the coupon.
result.redemptionStatus.statusCode	Status code object containing status details.
result.redemptionStatus.message	Message indicating the status of coupon processing.
result.redemptionStatus.code	Code indicating the status of coupon processing.
result.redemptionStatus.success	Indicates if the coupon processing was successful.
result.discountType	Type of discount provided.
result.discountValue	Value of the discount provided.
result.discountUpto	Maximum value up to which the discount is applicable.
totalCount	Total count of items in the response.
failureCount	Count of items that failed.

{
    "response": [
        {
            "entityId": 1306648998,
            "result": {
                "redemptionId": "-1",
                "id": 1306648998,
                "currencyInput": false,
                "localToBaseCurrencyExchangeRate": 0,
                "warnings": [],
                "appendedErrorMessage": "",
                "code": "3ELN50QRLCKGW5S6",
                "discountCode": "123123123",
                "seriesCode": 794088,
                "isAbsolute": false,
                "couponValue": 12,
                "redemptionStatus": {
                    "statusCode": {
                        "status": true,
                        "code": 700,
                        "message": "Coupon isRedeem successful"
                    },
                    "warnings": [],
                    "warningsAsStatusCode": [],
                    "code": 700,
                    "success": true,
                    "message": "Coupon isRedeem successful"
                },
                "discountType": "PERC",
                "discountValue": 12,
                "discountUpto": 12
            },
            "errors": []
        },
        {
            "entityId": 1306648999,
            "result": {
                "redemptionId": "-1",
                "id": 1306648999,
                "currencyInput": false,
                "localToBaseCurrencyExchangeRate": 0,
                "warnings": [],
                "appendedErrorMessage": "",
                "code": "WWTX7NIPSDC34DFX",
                "discountCode": "123123123123",
                "seriesCode": 801319,
                "isAbsolute": true,
                "couponValue": 122,
                "redemptionStatus": {
                    "statusCode": {
                        "status": true,
                        "code": 700,
                        "message": "Coupon isRedeem successful"
                    },
                    "warnings": [],
                    "warningsAsStatusCode": [],
                    "code": 700,
                    "success": true,
                    "message": "Coupon isRedeem successful"
                },
                "discountType": "ABS",
                "discountValue": 122,
                "discountUpto": 0
            },
            "errors": []
        }
    ],
    "totalCount": 2,
    "failureCount": 0
}

Language

URL

Click Try It! to start a request and see the response here!