| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
This API retrieves the details of one or more coupons by coupon codes or IDs, or get coupons issued to specific customers.
Note
- For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .
Example request
curl --location 'https://eu.api.capillarytech.com/v2/coupon?couponCodes=YTOWAEN5N0&showCouponSeries=true' \
--header 'Authorization: Basic YyZTZm' \
--header 'Cookie: _cfuvid=N8eBMQkzAuS0B.TF12bNd.D2Foo6GiTEeU_Hb2aUc1U-1768823280663-0.0.1.1-604800000'Prerequisites
- Authentication: Basic or OAuth authentication
- Default access group
Resource information
| URL | /coupon |
| HTTP Method | GET |
| Pagination | No |
| Batch support | No |
| Rate limit information | None |
API endpoint example
https://eu.api.capillarytech.com/v2/coupon?issuedToIds=345635529&coupon_code_case=LOWER
Request Query parameter
| Parameter | Datatype | Description |
|---|---|---|
issuedToIds | Integer | Fetch coupons issued to specific customers. Pass customer IDs to fetch. |
couponIds* | Integer | Fetch coupon details by coupon IDs. To fetch multiple coupons, use the id or code parameters repeatedly in your API request, For example: ?couponIds=123&couponIds=456 or ?couponCodes=ABC&couponCodes=DEF. Mandatory if couponCodes is not provided. |
couponCodes* | String | Fetch coupon details by coupon code. Mandatory if couponIds is not provided. |
coupon_code_case | Enum | This parameter helps to retrieve the coupon code in the desired letter cases. By default, the system automatically converts the coupon code to upper case. The query itself is not case sensitive. Supported Values: LOWER: Converts the coupon code to lower case.UPPER: Converts the coupon codes to upper case.AS_IT_IS: It ensures that the coupon code is retrieved exactly as it was created or provided, without altering the letter case. For instance, if the code is "abAB123," it should be retrieved and displayed as "abAB123," maintaining its original formatting. |
| showCouponSeries | Boolean | Fetches the coupon series details when set totrue.Default value: false |
includeIssualDetails | Boolean | Specifies whether to include the couponIssualDetails object in the response. When set to true, returns the metadata captured at the time of issuance.Default value: false |
Response parameter
With showCouponSeries = false
| Parameter | Description |
|---|---|
| code | The unique code associated with the coupon. |
| seriesId | The ID of the series the coupon belongs to. |
| description | A brief description of the coupon. |
| discountCode | Code indicating the type of discount. |
| validTill | The expiry time displayed here can be different if time is defined along with the expiry date of the coupon. For more details, refer to the documentation about the difference in the displayed and actual coupon expiry time. |
| validTillDateTime | Specifies the exact expiry date and time of a coupon in ISO 8601 format (e.g., "2026-06-11T23:59:59Z"), indicating the precise moment until which the coupon can be redeemed. |
| discountType | The type of discount. |
| discountValue | The value of the discount provided by the coupon. |
| discountUpto | The maximum value up to which discount can be applied. |
| discountOn | What the discount is applied on. |
| detailedInfo | Detailed information about the coupon. |
| couponIssualDetails | Defines the object containing the metadata captured at the time of coupon issuance. Returned when includeIssualDetails=true. |
| ..sourceType | Indicates the category of the source that initiated the issuance (e.g., Promotions, Journeys, API). |
| ..sourceId | Indicates the unique reference ID of the entity that triggered the issuance (e.g., journey block ID, rule ID). |
| ..sourceActivity | Indicates the specific event or activity that caused the coupon to be issued (e.g., Milestone completion, Post-purchase bounce-back). |
| ..notes | Specifies additional comments about the issuance. |
| ..reason | Specifies the business justification for issuing the coupon (e.g., campaign reward, service recovery). |
With showCouponSeries = true
| Parameter | Data type | Description |
|---|---|---|
| .data | Array | Array containing the list of coupon series details. |
| ..code | String | Indicates the coupon code used for redemption. |
| ..seriesId | Long | Indicates the ID of the coupon series the coupon belongs to. |
| ..description | String | Indicates the description of the coupon series. |
| ..discountCode | String | Indicates the discount code of the coupon series. |
| ..validTill | String | Indicates the coupon validity end date and time in ISO 8601 format, returned in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ..validTillDateTime | String | Indicates the coupon validity end date and time in ISO 8601 format, returned in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ..discountType | Enum | Indicates the type of discount. Example values: ABS, PERC. |
| ..discountValue | Integer | Indicates the discount value—percentage when discountType=PERC, and currency amount when discountType=ABS |
| ..discountUpto | Integer | Indicates the maximum discount allowed. |
| ..discountOn | Enum | Indicates the discount applies to the total bill or specific items. Example values: BILL, ITEM |
| ..detailedInfo | String | Additional descriptive text about the coupon. |
| ..couponIssualDetails | Object | Indicates an object containing the metadata captured at the time of coupon issuance. Returned when includeIssualDetails=true. |
| ...sourceType | String | Indicates the category of the source that initiated the issuance (e.g., Promotions, Journeys, API). |
| ...sourceId | String | Indicates the unique reference ID of the entity that triggered the issuance (e.g., journey block ID, rule ID). |
| ...sourceActivity | String | Indicates the specific event or activity that caused the coupon to be issued (e.g., Milestone completion, Post-purchase bounce-back). |
| ...notes | String | Specifies additional comments about the issuance. |
| ...reason | String | Specifies the business justification for issuing the coupon (e.g., campaign reward, service recovery). |
| ..couponSeries | Object | Object containing the details of the coupon series. |
| ...id | Integer | Unique ID of the coupon series. |
| ...orgId | Long | Indicates the organization ID associated with the coupon series. |
| ...description | String | Indicates the description of the coupon series. |
| ...discountCode | String | Indicates the discount code associated with the coupon series. |
| ...validTillDate | String | Indicates the expiration date of the coupon series in ISO 8601 format, returned in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ...validTillDateTime | String | Indicates the expiration date and time of the coupon series in ISO 8601 format, returned in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ...validTillISODate | String | Indicates the coupon expiration date in yyyy-MM-dd ISO date format.Note: This parameter is not related to ISO timezone standardization. |
| ...validDaysFromCreation | Long | Indicates the number of days from creation after which the coupon expires. |
| ...expiryStrategyValue | Long | Indicates the configured expiry strategy value for the coupon series. |
| ...maxCreate | Long | Indicates the maximum number of coupons that can be created in the series. |
| ...maxRedeem | Long | Indicates the maximum number of redemptions allowed for the series. |
| ...isTransferrable | Boolean | Indicates whether the coupon can be transferred to another customer. Value: true: The coupon can be transferred to another customer.false: The coupon is locked to the originally issued user. |
| ...anyUser | Boolean | Indicates whether any customer can redeem the coupon. Value: true: Any user can redeem the coupon.false: Redemption is restricted only to the issued user. |
| ...sameUserMultipleRedeem | Boolean | Indicates whether the same customer can redeem the coupon multiple times. Value: true: The same user is allowed to redeem multiple times from this series.false: The same user is not allowed multiple redemptions. |
| ...isReferralExistingUsersAllowed | Boolean | Indicates whether existing users are allowed to use the coupon for referrals. Value: true: Existing users can participate in the referral program for this series.false: Only new users can be used in the referral flow. |
| ...isMultipleUseAllowed | Boolean | Indicates whether the coupon can be used multiple times. Value: true: Each coupon code may be used multiple times.false: Each coupon code is single‑use. |
| ...isValidationRequired | Boolean | Indicates whether validation is required before redemption. Value: true: Validation is required before actual redemption.false: Coupon can be directly redeemed without validation. |
| ...isValidWithDiscountedItem | Boolean | Indicates whether the coupon can be used with discounted items. Value: true: Coupon can be applied to items on discount.false: Coupon cannot be combined with existing item discounts. |
| ...createdBy | Long | Indicates the user ID of the person who created the coupon series. |
| ...numIssued | Long | Indicates the number of coupons issued in the series. |
| ...numRedeemed | Long | Indicates the number of coupons redeemed in the series. |
| ...createdOn | String | Indicates the date and time when the coupon series was created in ISO 8601 format, returned in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ...lastUsed | String | Indicates the date and time when the coupon series was last used in ISO 8601 format, returned in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ...seriesCode | String | Indicates the unique series code for the coupon series. |
| ...smsTemplate | String | Indicates the SMS template associated with the coupon series. |
| ...isSMSDisabled | Boolean | Indicates whether SMS communication is disabled for the coupon series. Value: true: SMS sending for this series is disabled.false: SMS sending is allowed/enabled. |
| ...info | String | Indicates additional coupon information. |
| ...isMultipleVouchersPerUserAllowed | Boolean | Indicates whether multiple vouchers can be issued to the same user. Value: true: A single user can receive multiple vouchers from this series.false: A user is restricted to one voucher from this series. |
| ...doNotResendExistingVoucher | Boolean | Indicates whether an existing voucher should not be resent to the user. Value: true: The system does not resend an issued voucher to the same user.false: Resending an existing voucher is allowed. |
| ...mutualExclusiveSeriesIds | String | Indicates the list of series IDs that are mutually exclusive with this series. |
| ...storeIdsJson | String | JSON string containing store IDs where the series is applicable. |
| ...isDvsEnabled | Boolean | Indicates whether DVS (Dynamic Voucher System) is enabled for the coupon series. Value: true: Dynamic Voucher System is enabledfalse: Dynamic Voucher System is disabled. |
| ...dvsExpiryDate | String | Indicates the expiry date for DVS vouchers in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ...priority | Long | Indicates the priority of the coupon series when multiple offers apply. |
| ...shortSMSTemplate | String | Indicates the short SMS template used for the coupon series. |
| ...maxVouchersPerUser | Long | Indicates the maximum number of coupons from this series that a single user can receive. |
| ...minDaysBetweenVouchers | Long | Indicates the minimum days gap between issuing multiple vouchers in this series to the same user. |
| ...maxReferralsPerReferee | Long | Indicates the maximum number of referrals allowed per referee. |
| ...discountUpto | Long | Indicates the maximum discount allowed. |
| ...discountValue | Long | Indicates the value of the discount configured for the series. |
| ...dvsItems | String | Indicates the DVS items configuration for the coupon series. |
| ...redemptionRange | String | Indicates the redemption range configuration. Example: Allowed days and hours. |
| ...minBillAmount | Long | Indicates the minimum bill amount required for redemption. |
| ...maxBillAmount | Long | Indicates the maximum bill amount above which the coupon is not applicable. |
| ...redeemAtStore | String | Indicates the list of stores where the coupon can be redeemed. |
| ...campaignId | Long | Indicates the campaign ID associated with the coupon series. |
| ...tag | String | Indicates the tag associated with the coupon series. It helps categorize or search the series. |
| ...maxRedemptionsInSeriesPerUser | Long | Indicates the maximum redemptions allowed per user in the coupon series. |
| ...minDaysBetweenRedemption | Long | Indicates the minimum number of days required between redemptions for a user. |
| ...redemptionValidFrom | String | Indicates the date and time from which redemption is allowed in ISO 8601 format, returned in the server time zone. EU server example India server example Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
| ...sourceOrgId | Long | Indicates the source organization ID, if the series is shared across organizations. |
| ...issueToLoyalty | Boolean | Indicates whether the coupon is issued to a loyalty customer. |
| ...redeemStoreType | String | Indicates the type of stores where redemption is allowed. |
| ...offlineRedeemType | Boolean | Indicates whether the coupon supports offline redemption. Value: true: Dynamic Voucher System is enabledfalse: Dynamic Voucher System is disabled. |
| ...isOldFlowEnabled | Boolean | Indicates whether the old redemption flow is enabled. Value: true: Uses the legacy coupon flow for this seriesfalse: Use the current/standard flow. |
| ...isPreRedeemEventRequired | Boolean | Indicates whether a pre-redemption event is required. Value: true: A pre-redeem event must succeed before redemption proceeds;false: No pre-redeem event is required. |
| ...termsAndConditions | String | Indicates the terms and conditions configured for the coupon series. |
| ...signalRedemptionEvent | Boolean | Indicates whether the system triggers a redemption event. Value: true: The system sends a redemption event when a coupon is redeemed.false: The system does not send a redemption event signal when a coupon is redeemed. |
| ...syncToClient | Boolean | Indicates whether the coupon series is synced to the client system. Value: true: Keeps the series in sync with client systems.false: Does not keep the series in sync with client systems. |
| ...showPinCode | Boolean | Indicates whether the PIN code is displayed for the coupon. Value: true: Shows a PIN code to the user for this series.false: Does not show a PIN code to the user for this series. |
| ...targetUserDetails | Object | Object containing target user details. |
| ....validMaxUserTransactionLimit | Integer | Indicates the maximum transaction limit allowed for the user. |
| ....validUserRegistrationStartTime | Long | Indicates the user registration start time for eligibility validation. |
| ....validUserRegistrationEndTime | Long | Indicates the user registration end time for eligibility validation. |
| ...numUploadedNonIssued | Integer | Indicates the number of uploaded coupons that were not issued. |
| ...numUploadedTotal | Integer | Indicates the total number of uploaded coupons. This includes both issued and not issued coupons. |
| ...redemptionValidAfterDays | Integer | Indicates the number of days after issuance from which redemption is allowed. |
| ...ownedBy | String | Indicates the ownership of the coupon series. |
| ...ownerId | Integer | Indicates the owner ID associated with the coupon series. |
| ...ownerValidity | Long | Indicates the validity period for the owner configuration. |
| ...alphaNumeric | Boolean | Indicates whether the coupon code supports alphanumeric values. Value: true: Generated codes are alphanumeric.false: Generated codes are not alphanumeric. |
| ...shortCodeLength | integer | Indicates the length of the short coupon code. |
| ...randomCodeLength | integer | Indicates the length of the randomly generated coupon code. |
| ...fixedExpiryDate | integer | Indicates the fixed expiry date in epoch time (milliseconds). |
| ...numTotal | Integer | Indicates the total number of coupons in the series. |
| ...latestIssualTime | Long | Indicates the latest issuance time in epoch time (milliseconds). |
| ...latestRedemptionTime | Long | Indicates the latest redemption time in epoch time (milliseconds). |
| ...resendMessageEnabled | Boolean | Indicates whether resend message is enabled for the coupon series. Value: true: Allow resending coupon communications.false: Do not allow resending coupon communications. |
| ...redemptionPerCouponMaxLimit | Long | Indicates the maximum number of redemptions allowed per coupon. |
| ...isPrefixEnabled | Boolean | Indicates whether a prefix is enabled for coupon code generation. Value: true: Enable applying a prefix to generated coupon codes.false: Disable applying a prefix to generated coupon codes. |
| ...isSuffixEnabled | Boolean | Indicates whether a suffix is enabled for coupon code generation. Value: true: Enable applying a suffix to generated coupon codes.false: Disable applying a suffix to generated coupon codes. |
| ...orgPrefixOverride | Boolean | Indicates whether the organization prefix overrides the series prefix. Value: true: Overrides the organization-level prefix with the series-specific prefix.false: Uses the organization-level prefix as is. |
| ...orgSuffixOverride | Boolean | Indicates whether the organization suffix overrides the default suffix. Value: true: Overrides the organization-level suffix with the series-specific one.false: Uses the organization-level suffix as is. |
| ...seriesType | String | Indicates the series type of the coupon series. |
| ...clientHandlingType | String | Indicates how the client handles the coupon series. Example: DISC_CODE |
| ...expiryStrategyType | String | Indicates the expiry strategy type for the coupon series. |
| ...discountOn | String | Indicates what the discount applies to. Example: BILL, ITEM |
| ...discountType | String | Indicates the type of discount. Example: ABS, PERC. |
| ...updateProductData | Boolean | Indicates the update requirement for product data. Value: true: Product data associated with the series needs updating/sync.false: No product data update needed. |
| ...externalIssual | Boolean | Indicates whether the coupon series supports external issuance. Value: true: Coupon issuance is handled by an external gateway or provider.false: Coupon issuance is handled internally. |
| .warnings[] | Array | Array with the list of warnings returned in the response, if any. |
| .errors[] | Array | Array with the list of errors returned in the response, if any. |
{
"data": [
{
"code": "5875447216353555",
"seriesId": 868760,
"description": "Gold star coupons",
"discountCode": "gold1234",
"validTill": "2026-06-11T00:00:00Z",
"validTillDateTime": "2026-06-11T23:59:59Z",
"discountType": "ABS",
"discountValue": 1000,
"discountUpto": 0,
"discountOn": "BILL",
"detailedInfo": "Gold star coupons"
}
],
"warnings": [],
"errors": []
}{
"data": [
{
"code": "vmqvzcvymt",
"seriesId": 68579,
"description": "test-lekhana-2",
"discountCode": "NO_VALUE",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"discountOn": "BILL",
"detailedInfo": "test-lekhana-2"
},
{
"code": "x6wqg8kb01",
"seriesId": 68579,
"description": "test-lekhana-2",
"discountCode": "NO_VALUE",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"discountOn": "BILL",
"detailedInfo": "test-lekhana-2"
},
{
"code": "oo8hf7divr",
"seriesId": 68579,
"description": "test-lekhana-2",
"discountCode": "NO_VALUE",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"discountOn": "BILL",
"detailedInfo": "test-lekhana-2"
},
{
"code": "tt6wzp7xnw",
"seriesId": 68579,
"description": "test-lekhana-2",
"discountCode": "NO_VALUE",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"discountOn": "BILL",
"detailedInfo": "test-lekhana-2"
},
{
"code": "ziwy7lzgw8",
"seriesId": 68579,
"description": "test-lekhana-2",
"discountCode": "NO_VALUE",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"discountOn": "BILL",
"detailedInfo": "test-lekhana-2"
},
{
"code": "hu1dh75hny",
"seriesId": 68579,
"description": "test-lekhana-2",
"discountCode": "NO_VALUE",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"discountOn": "BILL",
"detailedInfo": "test-lekhana-2"
}
],
"warnings": [],
"errors": []
}{
"data": [
{
"code": "YTOWAEN5N0",
"seriesId": 757291,
"description": "Vishu 10% OFF",
"discountCode": "XMM123",
"validTill": "2026-05-09T00:00:00Z",
"validTillDateTime": "2026-05-09T23:59:59Z",
"discountType": "ABS",
"discountValue": 500,
"discountUpto": 0,
"discountOn": "BILL",
"detailedInfo": "Evil coupon",
"couponSeries": {
"id": 757291,
"orgId": 100737,
"description": "Vishu 10% OFF",
"discountCode": "XMM123",
"validTillDate": "2026-05-09T00:00:00Z",
"validTillDateTime": "2026-05-09T23:59:59Z",
"validTillISODate": "2026-05-09",
"validDaysFromCreation": 30,
"expiryStrategyValue": 1,
"maxCreate": 5,
"maxRedeem": 5,
"isTransferrable": false,
"anyUser": true,
"sameUserMultipleRedeem": true,
"isReferralExistingUsersAllowed": false,
"isMultipleUseAllowed": true,
"isValidationRequired": false,
"isValidWithDiscountedItem": true,
"createdBy": 75161973,
"numIssued": 5,
"numRedeemed": 0,
"createdOn": "2025-04-25T12:29:05Z",
"lastUsed": "2025-04-25T12:29:05Z",
"seriesCode": "1458A78E8A2846FBBB01",
"smsTemplate": "Hi {{first_name}} {{last_name}} your voucher code {{voucher}}is valid {{valid_days_from_create}}. {{fullname}} {{offer_name}}",
"isSMSDisabled": false,
"info": "Evil coupon",
"isMultipleVouchersPerUserAllowed": true,
"doNotResendExistingVoucher": true,
"mutualExclusiveSeriesIds": "[-1]",
"storeIdsJson": "[-1]",
"isDvsEnabled": false,
"dvsExpiryDate": "2025-04-25T00:00:00Z",
"priority": 0,
"shortSMSTemplate": "Hello {{cust_name}}, your voucher code is {{voucher_code}}",
"maxVouchersPerUser": 11,
"minDaysBetweenVouchers": 2,
"maxReferralsPerReferee": -1,
"discountUpto": 0,
"discountValue": 500,
"dvsItems": "items",
"redemptionRange": {
"dom": [
1
],
"dow": [
1
],
"hours": [
1
]
},
"minBillAmount": 100,
"maxBillAmount": 20000,
"redeemAtStore": "[-1]",
"campaignId": -1,
"tag": "Vishu 10% OFF",
"maxRedemptionsInSeriesPerUser": 122,
"minDaysBetweenRedemption": 0,
"redemptionValidFrom": "2024-05-01T00:00:00Z",
"sourceOrgId": -1,
"issueToLoyalty": false,
"redeemStoreType": "redeemable_stores",
"offlineRedeemType": false,
"isOldFlowEnabled": false,
"isPreRedeemEventRequired": false,
"termsAndConditions": "T&C",
"signalRedemptionEvent": false,
"syncToClient": false,
"showPinCode": false,
"targetUserDetails": {
"validMaxUserTransactionLimit": 5,
"validUserRegistrationStartTime": 0,
"validUserRegistrationEndTime": 10000
},
"numUploadedNonIssued": 0,
"numUploadedTotal": 0,
"redemptionValidAfterDays": 0,
"ownedBy": "NONE",
"ownerId": -1,
"ownerValidity": 0,
"alphaNumeric": true,
"shortCodeLength": 0,
"randomCodeLength": 10,
"fixedExpiryDate": 1778284800000,
"numTotal": 5,
"latestIssualTime": 1750933819000,
"latestRedemptionTime": 0,
"resendMessageEnabled": true,
"redemptionPerCouponMaxLimit": -1,
"isPrefixEnabled": false,
"isSuffixEnabled": false,
"orgPrefixOverride": false,
"orgSuffixOverride": false,
"seriesType": "UNDEFINED",
"clientHandlingType": "DISC_CODE",
"expiryStrategyType": "SERIES_EXPIRY",
"discountOn": "BILL",
"discountType": "ABS",
"externalIssual": false,
"updateProductData": false
}
}
],
"warnings": [],
"errors": []
}