Online Coupon Creation API

Vivoldi’s Coupon Creation API enables you to create discount coupons programmatically.

Choose either percentage-based (%) or fixed-amount discounts, and configure details such as expiration date, usage limits, group, and template directly in your request.

For bulk coupon creation, use the dashboard.
If images are required, first create a coupon group and upload images in the dashboard, then generate coupons by referencing that group.

This API is available on the Personal plan or higher.

POST

/api/coupon/v1/create 

{
    "cpnNo": "",
    "cpnNoDigits": 12,
    "domain": "https://vvd.bz",
    "webhookEnableYn": N",
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5,
    "discCurrency": "USD",
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "useLimit": 1,
    "grpIdx": 271,
    "tmplIdx": 0,
    "onsiteYn": "Y",
    "onsitePwd": "123456",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "url": "https://bestshop.com",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cpnNostring
Coupon number. 8–16 characters, letters and numbers only. Auto-generated if not provided. Special characters not allowed.
Example: V5H8GR5T
cpnNoDigits integer
Default:16
Enum:
16128
Length of the coupon code.
If not provided, the default length (16) will be used.
Only applies when a coupon code is not specified. The system will generate one automatically using the selected length.
domain string
Default:https://vvd.bz
Coupon domain.
If left empty, the default domain will be used.
Available on Premium plans and above: you can specify a custom domain registered in Link Domain Management.
webhookEnableYn string
Enum:
YN
Whether to enable Webhook.
Global Webhook must be enabled.
This feature is available only in the Enterprise plan.
nmstringrequired
Coupon name.
discTypeIdxintegerrequired
Discount type. (457: Percentage %, 458: Fixed amount)
discdoublerequired
For percentage discounts (457): range 1–100%. For fixed amount discounts (458): enter an amount.
discCurrencystring
Currency unit. Required when using fixed amount (discTypeIdx:458).
strtYmddaterequired
Coupon valid start date. Example: 2024-10-01
endYmddaterequired
Coupon expiration date. Example: 2024-12-31
The expiration date can only be set until December 31 of the following year.
useLimitintegerrequired
Coupon usage limit. (0: Unlimited, 1–5: Restricted uses)
If set to 2 or more, userId must be provided.
grpIdxinteger
Coupon group. Used to manage coupons in groups. Group IDX can be checked in the dashboard.
If both group and coupon settings are applied, group settings take priority.
tmplIdxinteger
Coupon template. Template IDX can be checked in the dashboard when creating coupons.
onsiteYnstring
On-site coupon indicator. Shows a “Use Coupon” button on the coupon page.
Required for offline store staff to process coupon usage.
onsitePwdstring
On-site coupon password. Required when redeeming the coupon.
memostring
Internal notes for reference.
urlstring
If a URL is entered, a “Go to Use Coupon” button will appear on the coupon page.
Clicking the button or image redirects to the specified URL.
colorstring
Coupon text color. Enter HEX value. Example: #4F4F4F
backgroundstring
Coupon background color. Enter HEX value. Example: #FFFFFF
userIdstring
Used to manage coupon recipients.
Required if usage limit is set to 2–5. Typically the website login ID or user name.
userNmstring
Coupon user name. For internal management.
userPhnnostring
Coupon user contact number. For internal management.
userEmlstring
Coupon user email. For internal management.
userEtc1string
Additional internal management field.
userEtc2string
Additional internal management field. 
{
    "code": 0,
    "message": "",
    "result": "ZJLF0399WQBEQZJM"
}

Response Parameters

code integer
Response code: 0 = Success, other values = Error
message string
Response message. If the response code is not 0, an error message is returned.
result string
Response value. The generated coupon number is returned.
Example: ZJLF0399WQBEQZJM

When to Use This API

Use this API when you need to automatically issue coupons for promotions, events, or user acquisition campaigns.

It fits a wide range of marketing scenarios, including signup incentives, targeted discounts, and driving conversions from ad traffic.

Coupon Code Format Configuration

Control the coupon code using the cpNo and cpNoDigits parameters.
If cpNo is provided, that value is used as the coupon code. If not, the system generates one automatically.

For auto-generated codes, set the length with cpNoDigits (default: 16).
Choose the length based on your use case: longer codes reduce collision risk, while shorter codes improve ease of entry.

User Data Association

To assign a coupon to a specific user, set the userId parameter.

To associate coupons with multiple users, use userEml·userPhone·userEtc1·userEtc2 together.
These values are used in the dashboard to identify and filter coupon owners, making them useful for B2C services that require user-level identification.

Use cases

  • Automated signup rewards: Trigger the API on user registration to generate and deliver a personalized coupon instantly
  • Time-limited promotions: Define start and end dates to issue coupons valid only within a specific period
  • Ad conversion tracking: Attach coupons to ad links to track the full funnel from click → redemption → purchase
  • Targeted user campaigns: Deliver personalized discounts based on email or user ID
  • In-store coupons: Set onsiteYn to Y so staff can validate coupons using a password at the point of sale

Things to consider

  • To create coupons with images, first create a coupon group and upload images in the dashboard, then specify the group ID in grpIdx before calling the API.
  • To receive webhooks, set webhookEnablYn to Y and register the Webhook URL in the dashboard in advance.
  • If useLimit is set to unlimited, coupons will not be marked as fully used even after redemption.
  • For in-store coupons, ensure secure password management for coupon validation.