Create a Coupon List

This API enables you to organize unique, single-use coupon codes within the system. It allows you to create and organize distinct lists for different coupon code categories.

info	Information This API creates the coupon list with basic specifications only. The coupons should be added using Upload the Coupons API to this coupon list before utilizing it in campaigns.

API Endpoint

POST https://api-0X.moengage.com/v1/coupon-list

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

You can obtain the username and password details from the MoEngage Dashboard.

Navigate to Settings > Account > APIs.
Copy the following details:
- Username: Under Workspace ID (earlier App ID), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Campaign report/Business events/Custom templates/Catalog API tile to copy the API key.
Use these details to authenticate the API requests.

Request Headers

Key

Required

Sample Values

Description

Content-Type

Required

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Required

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

This authentication parameter, used for access control, must be passed in the request. To generate the authentication header, refer to Authentication.

MOE-APPKEY

Required

{“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY has to be passed in the request. You can find your MoEngage Workspace ID in the MoEngage Dashboard:

Settings -> Account -> APIs -> Workspace ID (earlier app id)

For more information, refer to Authentication.

Request Body

Key	Required	Values	Description
name	Required	string	This field consists of the coupon list's unique name.
label	Required	string	This field consists of the label name for the coupon list.
expires_at	Required	string	This field consists of the date the coupon list expires in yyyy-mm-dd format.
email_alert_subscribers	Optional	string	This field consists of the email address of the coupon list subscriber. The subscriber will receive all the alerts on the coupon list in the email provided in this field.
created_by	Required	string	This field consists of the user name who requests to create the coupon list.
alert_conditions	Optional	JSON object	This object contains the details and types of alert conditions listed below: success_alert (boolean) failure_alert (boolean) coupon_shortage_alert alert (boolean) threshold_count (integer) expiry_alert alert (boolean) days_before (integer)

Response

Status	Key		Data Type	Description
Success	name		string	This field consists of the unique name of the coupon list corresponding to a successful coupon list creation request.
	label		string	This field consists of the label name for the coupon list corresponding to a successful coupon list creation request.
	expires_at		string	This field consists of the expiry date of the coupon list in yyyy-mm-dd format corresponding to a successful coupon list creation request.
	created_by		string	This field consists of the user name who created the coupon list corresponding to a successful coupon list creation request.
	email_alert_subscribers		string	This field consists of the email address of the coupon list subscriber corresponding to a successful coupon list creation request.
	alert_conditions		JSON object	This field consists of the alert conditions and the statuses specified while creating the coupon list.
	status		string	Once the coupon list creation request is accepted, the list status will show ACTIVE.
	_id		string	This field contains the unique ID corresponding to a successful coupon list creation request. This ID is used as a parameter for fetching, updating, or archiving coupon lists.
Failure	error	code	string	Each error codes are unique and serve as a shorthand representation for the type of error, providing a quick reference that can be used to diagnose, troubleshoot, and address the problem based on a predefined set of error conditions.
Failure	error	message	string	Along with the error code, a detailed message is also provided in the response, describing the specifics of the request failure and the nature of the error.

Refer to the Sample Response section for examples.

Response Codes

Status Code	Request State	Description
201	Success	Indicates that the request is successful and the coupon list creation request is accepted.
400	Bad request	Possible issues include duplicates, such as coupon list names, invalid data types, or missing mandatory attributes. For more information, refer to Error Messages.
401	Unauthenticated	Your request is unauthorized.
403	Forbidden	Your account does not have access to the Coupon Management features.
500	Internal server error	This response is returned when the system runs into an unexpected error.

Error Messages

Status Code	Error code	Description
400	duplicate-coupon-list-name	The coupon list name already exists. Enter a unique name and try again.
	duplicate-coupon-list-label	The coupon list label already exists. Enter a unique label and try again.
	missing-mandatory-attributes	You must include the mandatory attributes: name, label, expiry date, and email ID of the creator with string data type and try again.
	invalid-request	Invalid field in the request: ['<key name>']. Verify and try again. The value provided for the '<key name>' is invalid. Verify and try again. The requested JSON is incorrect. Verify and try again. The expiry date should not be a past date. Verify and try again. The 'alert' value is set to False, but the 'days_before' value is provided. The 'alert' value is set to True, but the 'days_before' value is missing. The expiry alert days should not exceed the expiry date. The 'alert' value is set to True, but the 'threshold_count' value is missing. The 'alert' value is set to False, but the 'threshold_count' value is provided. The data type provided for some of the attributes is invalid.
401	request-unauthenticated	Your request is unauthorized. Verify your credentials and try again.
403	request-forbidden	Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance.
500	unexpected-error	Something went wrong with your request. Contact the MoEngage team for further assistance.

Sample cURL Request

curl --location 'https://api-0X.moengage.com/v1/coupon-list' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data-raw '{
  "name": "signup_coupons",
  "label": "signup_coupons",
  "created_by": "John",
  "email_alert_subscribers": ["john.doe@example.com"],
  "expires_at": "2024-10-25",
  "alert_conditions": {
    "success_alert": true,
    "failure_alert": true,
    "expiry_alert": {
      "alert": true,
      "days_before": 1
    },
    "coupon_shortage_alert": {
      "alert": true,
      "threshold_count": 4
    }
  }
}'

Sample Response

{
    "name": "Example Name",
    "label": "Sample Label",
    "expires_at": "2024-10-31T18:29:00",
    "created_by": "John",
    "email_alert_subscribers": [
        "john.doe@example.com"
    ],
    "alert_conditions": {
        "success_alert": true,
        "failure_alert": true,
        "expiry_alert": {
            "alert": true,
            "days_before": 1
        },
        "coupon_shortage_alert": {
            "alert": true,
            "threshold_count": 10
        }
    },
    "status": "ACTIVE",
    "_id": "6721d00eefc476c0f67e0d05"
}

{
  "error": {
    "code": "duplicate-coupon-list-name",
    "message": "The coupon list name already exists. Please enter a unique name and try again."
  }
}

{
  "error": {
    "code": "duplicate-coupon-list-label",
    "message": "The coupon list label already exists. Please enter a unique label and try again."
  }
}

{
  "error": {
    "code": "missing-mandatory-attributes",
    "message": "Missing mandatory key ''. Please verify and try again."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "Invalid field in the request: ['']. Please verify and try again"
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The value provided for the '' key is invalid. Please verify and try again."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The requested JSON is incorrect. Please verify and try again."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The expiry date should not be a past date. Please verify and try again."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The 'alert' value is set to False but the 'days_before' value is provided."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The 'alert' value is set to True but the 'days_before' value is missing."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The expiry alert days should not exceed the expiry date."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The 'alert' value is set to True but the 'threshold_count' value is missing."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The 'alert' value is set to False but the 'threshold_count' value is provided."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "The data type provided for some of the attributes is invalid."
  }
}

{
  "error": {
    "code": "request-unauthenticated",
    "message": "Your request is unauthorized. Please verify your credentials and try again."
  }
}

{
  "error": {
    "code": "request-forbidden",
    "message": "Your account does not have access to the Coupon Management features. Please contact the MoEngage team for further assistance."
  }
}

{
  "error": {
    "code": "unexpected-error",
    "message": "Something went wrong with your request. Please contact the MoEngage team for further assistance."
  }
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.