Time	Status	User Agent
Retrieving recent requests…

This API retrieves coupon details for a specific customer, including issued, redeemed, and expired coupons. You can filter results by coupon status, date range, coupon series, or store, and sort by validity or creation date.

Pass at least one customer identifier (mobile, email, external_id, or id) to identify the customer.

Example request

curl --location 'https://eu.api.capillarytech.com/v1.1/customer/coupons?mobile=1234512345&limit=200' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86NjVhMDgzYjk1MNTY5NDk1YmNkNzUxYmJiY2U=' \
--header 'Cookie: _cfuvid=CMee7qv34XA7aUyzJ_SpIlU06R3Fngfu6LI-1771396256754-0.0.1.1-604800000'

Prerequisites

Authentication: Basic or OAuth authentication
Access group: Default access group

Resource information


Pagination support	Yes
Batch support	No

Query parameters

Field	Type	Required	Description
mobile	String	Conditional	Specify the mobile number of the customer.
email	String	Conditional	Specify the email ID of the customer.
external_id	String	Conditional	Specify the external ID of the customer.
id	Number	Optional	Specify the unique ID of the customer.
start_date	Date	Optional	Specify the starting date (YYYY-MM-DD) to get coupons issued or redeemed on or after. To get the coupon history for a specific duration, pass both start_date and end_date.
end_date	Date	Optional	Specify the ending date (YYYY-MM-DD) to get coupons issued or redeemed before. To get the coupon history for a specific duration, pass both start_date and end_date.
status	Enum	Optional	Specify the status to filter coupons by. Values: unredeemed, redeemed, expired, active. Note: active returns coupons whose valid_till is a future date and does not validate redemptions.
series_id	Number	Optional	Specify the series ID to retrieve coupons from a specific coupon series.
store_id	String	Optional	Specify the store ID to retrieve active coupons that can be redeemed at a specific store.
order_by	Enum	Optional	Specify the field to sort results by. Values: created_date, created_by, valid_till.
sort_order	Enum	Optional	Specify the sort order. Values: asc (ascending), desc (descending).
limit	Number	Optional	Specify the maximum number of results to return. Default limit: 100

Example response

{
  "response": {
    "pagination": {
      "limit": "100",
      "offset": "0",
      "total": 1
    },
    "status": {
      "success": "true",
      "code": 200,
      "message": "Success"
    },
    "customers": {
      "customer": [
        {
          "firstname": "Tom",
          "lastname": "Sawyer",
          "email": "[email protected]",
          "external_id": null,
          "mobile": "9988776655",
          "id": "98662653",
          "coupons": {
            "coupon": [
              {
                "id": "163267982",
                "series_id": "12360",
                "series_name": "Spin_The_Wheel",
                "redemption_count": 0,
                "created_date": "2019-07-29T16:13:14.000Z",
                "valid_till": "2019-12-31 23:59:59",
                "code": "6WRNA5UM",
                "transaction_number": null,
                "issued_at": {
                  "code": "store_001",
                  "name": "Main Store"
                },
                "purpose": "",
                "custom_properties": {
                  "custom_property": [
                    {
                      "name": "standard_description",
                      "value": "10% off on next purchase"
                    }
                  ]
                },
                "redemptions": {
                  "redemption": [
                    {
                      "id": "4359526",
                      "date": "2021-05-17T19:07:54.000Z",
                      "transaction_number": "TXN12345",
                      "redeemed_at": {
                        "code": "store_002",
                        "name": "Downtown Store"
                      }
                    }
                  ]
                }
              }
            ]
          },
          "item_status": {
            "success": "true",
            "code": 1000,
            "message": "Coupons retrieved successfully"
          }
        }
      ]
    }
  }
}

Response parameters

Field	Type	Description
pagination	Object	Define the pagination details for the response.
.limit	String	Specify the maximum number of results per page.
.offset	String	Specify the number of results to skip from the beginning.
.total	Number	Specify the total number of coupons matching the query.
status	Object	Define the overall API response status.
.success	String	Indicate if the request was successful (true or false).
.code	Number	Specify the HTTP status code.
.message	String	Provide the status message.
customers	Object	Contain the container for customer data.
.customer	Array	Define an array of customer objects.
..firstname	String	Specify the customer's first name.
..lastname	String	Specify the customer's last name.
..email	String	Specify the customer's email address.
..external_id	String	Specify the customer's external ID.
..mobile	String	Specify the customer's mobile number.
..id	String	Specify the customer's unique ID.
..coupons	Object	Contain the container for the customer's coupons.
...coupon	Array	Define an array of coupon objects.
....id	String	Specify the unique coupon ID.
....series_id	String	Specify the ID of the coupon series this coupon belongs to.
....series_name	String	Specify the name of the coupon series.
....redemption_count	Number	Specify the number of times this coupon has been redeemed.
....created_date	String	Specify the date and time when the coupon was issued (ISO 8601 format).
....valid_till	String	Specify the coupon expiry date and time.
....code	String	Specify the coupon code.
....transaction_number	String	Specify the transaction number associated with coupon issuance, if any.
....issued_at	Object	Define the store where the coupon was issued.
.....code	String	Specify the store code.
.....name	String	Specify the store name.
....purpose	String	Specify the purpose or description of the coupon issuance.
....custom_properties	Object	Contain the container for custom properties.
.....custom_property	Array	Define an array of custom property objects with name and value fields.
....redemptions	Object	Contain the container for redemption history.
.....redemption	Array	Define an array of redemption objects.
......id	String	Specify the redemption ID.
......date	String	Specify the date and time of redemption (ISO 8601 format).
......transaction_number	String	Specify the transaction number associated with the redemption.
......redeemed_at	Object	Define the store where the coupon was redeemed.
.......code	String	Specify the store code.
.......name	String	Specify the store name.
..item_status	Object	Define the status for this specific customer's coupon retrieval.
...success	String	Indicate if the retrieval was successful (true or false).
...code	Number	Specify the item-level status code (1000 for success).
...message	String	Provide the item-level status message.

Error and warning codes

Code	Type	Description
701	Error	Customer could not be found. Check the mobile, email, or external ID passed.
702	Error	Coupon code is invalid.
707	Error	Coupon series ID is invalid.
1000	Info	Coupons retrieved successfully.