API - List Coupons

List Coupons

This API is used to get list of coupons for a group by specifying the path to the group or id.

Path syntax is as follows:

Path = segment/segment/......

segment = * | {code: "group code"} | {name: "group name"}

Each segment can contain * (matches any group at that level), name of the group or code of the group. Path must result in single group otherwise the API will fail.

Example of Path

Path = {name:"Training"}/{name: "Corporate"}/{name: "Sales"}

Path = {name:"Training"}/{name: "Corporate"}/*


API Details

Signature of API call

connection.invokeApi(String uri, String realUserName, Map<String, String> requestParameters);

See details about invoking API in general


Parameter 1 - URI



Parameter 2 - UserName

Username of the site admin


Parameter 3 - Request Parameters

Name Value
dispatch listCoupons
xml true
authCode Coupon name (optional)

Coupon type (optional). Must be from one of the below values






entityType should be set to one of the following values

- SITE (to create coupon that is valid for all items in the site)

- PROGRAM_SESSION (to create coupon that is valid for a program session)

- COURSE_SESSION (to create coupon that is valid for a course session)

- EVENT (to create coupon that is valid for an event)

- GROUP (to create coupon that is valid for everything available in a group)


Id of the above entity.

In case entityType is SITE, this value is optional. If not passed, current site id is assumed. In case of multi site enabled accounts, pass the value of any site id from your own account. You can also pass url of the site instead of Id in this parameter (if id is not known)

In case entityType is GROUP, ID or the path should be passed


Search for coupon that has expiration date equal or after this date represented as epoch time in milliseconds - number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds

expToDate Search for coupon that has expiration date equal or before this date
ownerGroupId ID or path of the authorized group which can use this coupon

Boolean (true | false)

Find coupons that are expired


Boolean (true | false)

Find coupons that are fully used

currPage page number to fetch, must be specified for 2nd page onwards. Value of currPage starts with 0. So for page 2 specify currPage = 1
numItems total records in the list, must be specified for 2nd page onwards. You can get the count of records from response of first page. then pass it as-is in subsequent pages.
pageSize Number of items in a page



Response on successfully getting the coupon list

HTTP Response Code = HttpServletResponse.SC_OK

Response XML

<response code="0">
      <coupons numItems=".." currPage=".." pageSize="10">
         <coupon id="e48b628e-c31b-11e1-a74c-e96024937694" couponType="USAGE" setMembershipExpiration="false" addUserToCouponsGroup="false" requireApproval="false" previewAccessOnly="false" status="ACTIVE">
            <comments><![CDATA[free coupon for customer1]]></comments>


Code Snippet

/* Check API Call for detail */

Map<String, String> parameters = new HashMap<String, String>();
String result = connection.invokeApi("couponService.do", "adminusername", parameters);
private void populateMapForCouponList(Map<String, String> parameters) {
    parameters.put("dispatch", "listCoupons");
    parameters.put("xml", String.valueOf(true));
", "{name:\"Training\"}/{name: \"Corporate\"}/{name: \"Sales\"}");