Upload a Coupon File to the Coupon List

Once a coupon list is created, coupons should be added to the list to be distributed through campaigns. If a coupon list has been running for some time, it may be running low after serving several campaigns.

Using this API, you can replenish an older list or populate a new list by providing the URL of a file containing the coupons, thereby enabling their distribution through various campaigns. These coupons can be provided through a file, and the API requires the URL where your coupon file is hosted.

info

Information

Upon API request, file processing begins, and the file status will be PENDING by default.

For convenience, a callback URL can be set up to trigger when the file's processing is completed.
The processing status can be checked using the Fetch a Coupon File API to get the status separately.

API Endpoint

POST https://api-0X.moengage.com/v1/coupon-list/{{coupon_list_id}}/files

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	Optional	string	This field consists of the file name of the coupon list.
file_url	Required	string	This field consists of the file path of the coupon list.
file_url_auth_username	Optional	string	This field consists of the coupon file username.
file_url_auth_password	Optional	string	This field consists of the coupon file password.
created_by	Optional	string	This field consists of the name of the subscriber who uploaded the coupon file.
callback_url	Optional	string	This field consists of the coupon file callback URL.

Response

Status	Key		Data Type	Description
Success	name		string	This field contains the coupon file name.
	file_url		string	This field consists of the file path of the coupon list.
	created_by		string	This field consists of the name of the subscriber who uploaded the coupon file.
	status		string	Once the coupon URL upload request is accepted, the response displays the following status: PENDING - The URL is waiting for approval. Note: To know the status of the coupon upload, you need to trigger the Fetch a Coupon File API.
	coupons_list_id		string	This field contains the coupon list ID that you have requested to upload the coupon file to.
	_id		string	This field contains the coupon file ID.
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	The request was successful, and the coupon URL upload request was accepted. Note: The status of the URL upload is always PENDING.
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	invalid-request	The requested JSON is incorrect. Verify and try again.
	EmptyFileUrl	The 'file_url' can not be empty. Provide the coupon file URL and try again.
	MultipleFileUrl	Multiple file URLs are not permitted. Select one file URL and try again.
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://coupon-management.moengage.com/v1/coupon-list/{{coupon_list_id}}/files' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data '{
  "file_url": "{{File_URL}}"
}'

Sample Response

{
    "name": "File_Name",
    "file_url": "URL_OF_Coupon_File",
    "created_by": "User_Name",
    "status": "PENDING",
    "coupon_list_id": "673eddd448fbdf5b8f97b6c3",
    "_id": "673edef3dd21d37bf1a91a19"
}

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

{
  "error": {
    "code": "invalid-request",
    "message": "The 'file_url' can not be empty. Please provide the coupon file url and try again."
  }
}

{
  "error": {
    "code": "invalid-request",
    "message": "Multiple file urls are not permitted. Please select one file url and try again."
  }
}

{
  "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.