Developer API

Create Coupon

This API allows you to create discount coupons.
To create multiple coupons at once, you must use the dashboard.

Uploading coupon images is not supported via API.
If you need images, first create a coupon group in the dashboard and upload the image there, then specify the group when creating the coupon.

When a coupon group is specified, some coupon settings will be overridden by the group’s settings.

This API is available starting from the Personal plan.

Http Header

POST /api/coupon/v1/create
Host: https://vivoldi.com
Authorization: APIKey {Your API Key}
Content-type: application/json
User-agent: {Your User-agent}
Accept-Language: en

Request

{
	"cpnNo": "",  // You can specify a coupon code manually. If left empty, a 16-character code will be generated automatically by the system.
	"grpIdx": 271,
	"tmplIdx": 0,
	"nm": "$5 discount coupon",
	"discTypeIdx": 458,
	"disc": 5,
	"strtYmd": "2025-01-01",
	"endYmd": "2025-12-31",
	"onsiteYn": "Y",
	"onsitePwd": "123456",
	"memo": "New Member Registration, IP: 211.111.222.33",
	"url": "https://bestshop.com",
	"useLimit": 1,
	"userId": "att78z",
	"userNm": "Brown Smith",
	"userPhnno": "+1 123-4567-8900",
	"userEml": "",
	"userEtc1": "Gold rating",
	"userEtc2": ""
}

Fields	Field Descriptions	Description	Type
cpnNo	Coupon number	A 8~16 digit coupon number that is a combination of uppercase letters and numbers. Special characters can’t be used in the coupon number. If the value is empty, then the coupon number is automatically generated by the system.	string
grpIdx	Coupon group	Coupon groups are used to manage the categorization of coupons, and if a group setting and a coupon setting overlap, then the coupon setting is ignored. You can find the group IDX on the Coupon groups page of your dashboard. Default value: 0	int
tmplIdx	Coupon template	Coupon templates are used to describe a coupon and tell users what it’s for, how to use it, and any caveats. The template IDX can be found on the Coupon templates page in your dashboard. Default value: 0	int
nm	Coupon name	The name of the coupon appears on the coupon page.	string
discTypeIdx	Discount type	Set the discount type (rate or amount) for the coupon. 457: Rate discount (%), 458: Amount discount Rate discount: Used when you offer a percentage discount for a coupon. Discount by amount: Used to offer a discount by the amount entered.	int
disc	Discount value	Enter a value between 1% and 100% when the discount type is Rate (457). Enter the amount to discount when the discount type is Amount (458).	double
discCurrency	Amount Currency	You can set a monetary unit when the discount type is Amount (458). KRW, CAD, CNY, EUR, GBP, IDR, JPY, MUR, RUB, SGD, USD Default value: KRW	string
strtYmd	Validity start date	Set the start date of the validity period to indicate when the coupon is available for use. 10-digit value in yyyy-mm-dd date format. Example: 2024-10-01	date
endYmd	Validity expiration date	Set the expiration date of the coupon to indicate how long the coupon is available for use. 10-digit value in yyyy-mm-dd date format. Example: 2024-12-31	date
onsiteYn	On-site coupons or not	If this value is Y, then the coupon page displays a button to redeem the coupon. The user shows the coupon to a store associate, and the associate redeems the coupon. This is a useful feature if you have a brick-and-mortar store. Default value: N	Y or N
onsitePwd	On-site coupon usage password	When you set a password, store staff must enter the set password when processing coupons. Users cannot process coupons arbitrarily.	string
memo	Notes	It can be used for internal purposes to manage coupons. Notes are not visible to users.	string
url	URL	After you enter the URL, the coupon page displays a “Go to redeem coupon” button that, when clicked, takes you to the URL that you entered. If an image of the coupon has been uploaded, then clicking on the image will also take you to the URL.	string
useLimit	Maximum number of coupon redemptions per person	Set the maximum number of times a coupon can be redeemed. The number of coupon redemptions per person “2 ~ 5” is required when processing coupon redemptions using the REST API provided by Vivoldi. In this case, the user ID value must be entered. When managing coupon redemptions manually on the dashboard, you can select only one of the following options: “Unlimited” or “1 time”. If you select “Unlimited”, then anyone can redeem the coupon an unlimited number of times. 0:Unlimited, 1:1 time limit, 2:2 time limit, 3:3 time limit, 4:4 time limit, 5:5 time limit	int
color	Text color	Set the color of the coupon text on the coupon page. It must be entered as a HEX value and can be up to 9 digits long, including the transparency. Default value: #4F4F4FFF	string
background	Background color	On the Coupons page, set the background color for the coupon. It must be entered as a HEX value and can be up to 9 digits long, including the transparency. Default value: #FFFFFFFF	string
userId	User ID	Used to manage who has issued coupons and who has redeemed them. If the value of Maximum coupon redemptions per person is between 2 and 5, then the user ID must be entered. Typically, you enter the login ID of the member who signed up for your website.	string
userNm	Username	If you already know who you want to issue the coupon to, then enter the name of the user who will use the coupon. You need this to manage the issuance and redemption of coupons.	string
userPhnno	User contacts	Set the contacts of the users who will redeem the coupon.	string
userEml	User email	Set the email of the user who will redeem the coupon.	string
userEtc1	User Other Information1	Set additional information about the user for internal administrative purposes.	string
userEtc2	User Other Information2	Set additional information about the user for internal administrative purposes.	string

Response

{
	"code": 0,
	"message": "",
	"result": "ZJLF0399WQBEQZJM"
}

Fields	Description	Type
code	Response code (0:Success)	int
message	The response message, or a related message if the response code is non-zero.	string
result	Response value (Coupon number)	string