get https://{host}/v2/customers/coupons
This API retrieves the coupon history details of a customer with basic details. For each customer, information includes coupon codes, validity, discount type and amount, redemption history, and issuing details, as well as pagination to manage large data sets efficiently. This API is ideal for accessing an overview of all coupons across customers. If you want to retrieve more information about coupons, use this API.
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 .
Prerequisites
- Authentication: Basic or OAuth authentication
- Default access group
Resource information
| URL | /customers/coupons |
| HTTP Method | GET |
| Pagination | Yes |
| Batch support | No |
| Rate limit information | None |
API endpoint example
https://eu.api.capillarytech.com/v2/customers/coupons?mobile=917003222195&coupon_code_case=LOWER&limit=20&offset=5
Request Query Parameters
| Parameters | Data Type | Description |
|---|---|---|
| mobile | Integer | Mobile of the customer. |
| Integer | Email of the customer. | |
| externalId | Integer | External ID of the customer. |
| id | Long | Unique ID of the customer. |
| status | Enum | Get coupons of selected status(es). Supported values: REDEEMED, UNREDEEMED, ACTIVE, EXPIRED, ACTIVE_REDEEMED, ACTIVE_UNREDEEMED, EXPIRED_REDEEMED, EXPIRED_UNREDEEMED, REDEEMABLEIn the enum values, Active_Redeemed is for coupon is active but redeemed), Active_Unredeemed for coupons that are active and not redeemed, Expired_Redeemed for coupons that are expired but redeemed,and Expired_Unredeemed for coupons that are expired and not redeemed. |
| 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, UPPER, AS_IT_IS LOWER Converts the coupon code to lowercase. Example: "ABCD1234" → "abcd1234" UPPER Converts the coupon code to uppercase. Example: "abcd1234" → "ABCD1234" AS_IT_IS Returns the coupon code exactly as it was created or provided. Example: "abAB123" → "abAB123" |
| sort_order | Enum | Sort the results in Ascending (ASC) or Descending (DESC) order. By default it is Descending. |
| limit | Integer | Limit the number of results to be retrieved. For example: limit=10 to retrieve the history of ten recent coupons of the customer. |
| offset | Integer | Defines the number of rows that needs to be skipped from the beginning of the results. For example, number 10 skips the first 10 search results. |
Response parameters
| Parameter | Description |
|---|---|
| code | The unique coupon code generated. This code is used for redeeming the coupon. |
| seriesId | The unique identifier for the coupon series. |
| description | Description of the coupon. |
| validTill | Expiry date and time of the coupon in ISO 8601 format. |
| discountType | Specifies the type of discount provided by the coupon (e.g., ABS for absolute, PERC for percentage). |
| discountValue | The value of the discount. |
| discountUpto | The maximum value up to which the discount can be applied. |
| customer | An object containing details about the customer. |
| customer.id | The unique identifier of the customer. |
| customer.profiles | An object containing profile details of the customer. |
| customer.profiles.firstName | The first name of the customer. |
| customer.profiles.lastName | The last name of the customer. |
| customer.profiles.identifiers | Identifier for the customer. |
| customer.profiles.identifiers.type | The type of identifier (e.g., "mobile", "email"). |
| customer.profiles.identifiers.value | The value of the identifier (e.g., the actual mobile number or email address). |
| customer.profiles.commChannels | Communication channels preferred by the customer. |
| customer.profiles.userId | A unique identifier for the user's profile. |
| customer.profiles.accountId | The account ID associated with the customer's profile. |
| customer.profiles.autoUpdateTime | The timestamp indicating the last automatic update time for the profile. |
| customer.profiles.identifiersAll | Contains all identifiers associated with the customer. |
| identifiersAll.type` | The type of the first identifier in the all identifiers. |
| identifiersAll.value | The value of the first identifier in the all identifiers. |
| identifiersAll.type | The type of the second identifier in the all identifiers. |
| identifiersAll.value | The value of the second identifier in the all identifiers. |
| redemptionStatus | Represents the overall status of the redemption. |
| redemptionStatus.status | Indicates the overall success status of the coupon processing. |
| redemptionStatus.message | A message describing the overall status of the coupon processing. |
| redemptionStatus.code | The status code representing the overall result of the coupon processing. |
| issuedAt | An object containing details about where the coupon was issued. |
| issuedAt.code | The code of the store where the coupon was issued. |
| issuedAt.name | The name of the store where the coupon was issued. |
| customProperty | An array of custom properties associated with the coupon. |
| redemptions | An array containing details of redemptions associated with the coupon. |
| reversedRedemptions | An array containing details of reversed redemptions associated with the coupon. |
{
"entity":{
"pagination":{
"limit":"100",
"offset":"0",
"total":4
},
"customers":[
{
"firstname":"Tom",
"lastname":"Sawyer",
"mobile":"918860000001",
"id":401031250,
"coupons":[
{
"code":"KNRYHMRW",
"seriesId":363653,
"description":"NewCouponForAll",
"validTill":"2029-09-01T00:00:00+05:30",
"discountType":"ABS",
"discountValue":1000.0,
"discountUpto":0.0,
"redemptionCount":0,
"redemptionsLeft":1,
"id":399000028,
"createdDate":"2021-09-25T16:28:11+05:30",
"transactionNumber":"2147877652",
"issuedAt":{
"code":"storecode",
"name":"webstore1"
},
"redemptions":[
{
"date": "2022-03-10T14:48:09+05:30",
"transactionNumber": "1646903888000",
"redeemedAt": {
"code": "luciauto_store2",
"name": "Auto Store2"
}
]
},
{
"code":"7TF6TBQB",
"seriesId":363653,
"description":"NewCouponForAll",
"validTill":"2029-09-01T00:00:00+05:30",
"discountType":"ABS",
"discountValue":1000.0,
"discountUpto":0.0,
"redemptionCount":0,
"redemptionsLeft":1,
"id":399000029,
"createdDate":"2021-09-25T16:28:11+05:30",
"transactionNumber":"2147877652",
"issuedAt":{
"code":"storecode",
"name":"webstore1"
},
"redemptions":[
]
},
{
"code":"6JAFX7ZF",
"seriesId":363653,
"description":"NewCouponForAll",
"validTill":"2029-09-01T00:00:00+05:30",
"discountType":"ABS",
"discountValue":1000.0,
"discountUpto":0.0,
"redemptionCount":0,
"redemptionsLeft":1,
"id":399000026,
"createdDate":"2021-09-25T16:25:25+05:30",
"transactionNumber":"2147877651",
"issuedAt":{
"code":"storecode",
"name":"webstore1"
},
"redemptions":[
]
},
{
"code":"KZWMCYTR",
"seriesId":14162,
"description":"Mobile Push offer 1",
"validTill":"2022-03-20T00:00:00+05:30",
"discountType":"PERC",
"discountValue":10.0,
"discountUpto":0.0,
"redemptionCount":0,
"redemptionsLeft":1,
"id":397755229,
"createdDate":"2021-09-01T17:53:43+05:30",
"transactionNumber":"2147861881",
"issuedAt":{
"code":"storecode",
"name":"webstore1"
},
"redemptions":[
]
}
]
}
]
},
"warnings":[
],
"errors":[
],
"success":true
}
{
"entity": {
"pagination": {
"limit": "100",
"offset": "0",
"total": 7
},
"customers": [
{
"firstname": "autofn_917003222195",
"lastname": "autoln_917003222195",
"email": "[email protected]",
"mobile": "917003222195",
"id": 345635529,
"externalId": "ext_id917003222195",
"coupons": [
{
"code": "tt6wzp7xnw",
"seriesId": 68579,
"description": "test-lekhana-2",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"redemptionCount": 0,
"redemptionsLeft": 1,
"id": 39004111,
"createdDate": "2024-10-11T13:18:03Z",
"transactionNumber": "0",
"issuedAt": {
"code": "store123",
"name": "MarvelAuto_Store"
},
"redemptions": [],
"reversedRedemptions": []
},
{
"code": "ziwy7lzgw8",
"seriesId": 68579,
"description": "test-lekhana-2",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"redemptionCount": 0,
"redemptionsLeft": 1,
"id": 39004112,
"createdDate": "2024-10-11T13:18:03Z",
"transactionNumber": "0",
"issuedAt": {
"code": "store123",
"name": "MarvelAuto_Store"
},
"redemptions": [],
"reversedRedemptions": []
},
{
"code": "hu1dh75hny",
"seriesId": 68579,
"description": "test-lekhana-2",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"redemptionCount": 0,
"redemptionsLeft": 1,
"id": 39004113,
"createdDate": "2024-10-11T13:18:03Z",
"transactionNumber": "0",
"issuedAt": {
"code": "store123",
"name": "MarvelAuto_Store"
},
"redemptions": [],
"reversedRedemptions": []
},
{
"code": "vmqvzcvymt",
"seriesId": 68579,
"description": "test-lekhana-2",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"redemptionCount": 0,
"redemptionsLeft": 1,
"id": 36502461,
"createdDate": "2024-10-10T10:37:03Z",
"transactionNumber": "0",
"issuedAt": {
"code": "store123",
"name": "MarvelAuto_Store"
},
"redemptions": [],
"reversedRedemptions": []
},
{
"code": "x6wqg8kb01",
"seriesId": 68579,
"description": "test-lekhana-2",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"redemptionCount": 0,
"redemptionsLeft": 1,
"id": 36502462,
"createdDate": "2024-10-10T10:37:03Z",
"transactionNumber": "0",
"issuedAt": {
"code": "store123",
"name": "MarvelAuto_Store"
},
"redemptions": [],
"reversedRedemptions": []
},
{
"code": "oo8hf7divr",
"seriesId": 68579,
"description": "test-lekhana-2",
"validTill": "2024-10-31T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"redemptionCount": 0,
"redemptionsLeft": 1,
"id": 36502463,
"createdDate": "2024-10-10T10:37:03Z",
"transactionNumber": "0",
"issuedAt": {
"code": "store123",
"name": "MarvelAuto_Store"
},
"redemptions": [],
"reversedRedemptions": []
},
{
"code": "w2jjud9yrguaprdur52o",
"seriesId": 68377,
"description": "test-lekhana",
"validTill": "2024-10-09T00:00:00Z",
"discountType": "ABS",
"discountValue": 10.0,
"discountUpto": 0.0,
"redemptionCount": 0,
"redemptionsLeft": 1,
"id": 36501088,
"createdDate": "2024-10-08T18:29:14Z",
"transactionNumber": "0",
"issuedAt": {
"code": "store123",
"name": "MarvelAuto_Store"
},
"customProperty": [
{
"name": "standard_image_1",
"value": ""
},
{
"name": "standard_image_2",
"value": ""
},
{
"name": "standard_description",
"value": "DescriptionCustom"
},
{
"name": "standard_image_3",
"value": ""
},
{
"name": "standard_terms_and_conditions",
"value": "Terms and conditionscustom"
},
{
"name": "test-xyz",
"value": "test-xyz custom"
}
],
"redemptions": [],
"reversedRedemptions": []
}
]
}
]
},
"warnings": [],
"errors": [],
"success": true
}