Overview
- Hublify integrates an option to add coupons
- Every Coupon belongs to a campaign
- Coupons can have relative or absolute values
- They can be combined or be set as exclusive
- Various optional constraints can be configured for each coupon or the campaign in general, e.g.
- how long is each coupon valid
- who can redeem the coupon (everyone or only a specific person)
- requirements for a specific minimum cart value or a specific product in the cart
The coupon-campaign
Dataset coupon_campaign
The coupon-campaign is the main grouping criteria for coupons. Every coupon needs to be assigned to a campaign.
The constraints set within a campaign are valid for all coupons that belong to this campaign.
If the coupon itself has it's own constraints they will be combined with the ones set for the campaign.
Get existing campaigns
Request URL
https://{your hublify url}/api/eos_10/data_getList
Request parameter
{
"dataset": "coupon_campaign",
"fields": [
"couponcamp_id",
"couponcamp_label",
"couponcamp_desc",
"couponcamp_type",
"couponcamp_valid_start",
"couponcamp_valid_end",
"couponcamp_xsettings"
]
}Response
{
"status": true,
"data": [
{
"couponcamp_id": "1", // internal ID for the campaign
"couponcamp_label": "HFYDemo", // Label to identify the campaign
"couponcamp_desc": "Hublify Demo", // Description
"couponcamp_type": "promotion", // Type of the campaign
"couponcamp_valid_start": null, // time the campaign starts (null = no time restriction)
"couponcamp_valid_end": null, // time the campaign ends (null = no time restriction)
"couponcamp_xsettings": { // campaign-wide settings
"default": { // these are default-settings used for creating new coupons
"cnt_label": "shop_coupon_code", // counter used to create coupon-codes
"block": 2, // block within the shopping cart that
"coupon_valid_end_period": "", // period after creation that each coupon would be valid
"coupon_value": "5", // value of the coupon
"coupon_value_type": "relative", // value-type, reletave here means "5%"
},
"constraints": { // these constraints will be checked automatically in your cart
"order_min_value": "", // minimum order value required, here no minimum required
"order_min_value_prc_mode": "brutto", // which total does the order-min-value refer to
"null_orders_allow": "", // 1, if the order could have a total value of 0.00 after redeeming the coupon
"redeem_combined_blocked": "", // 1, if coupons from this campaign can not be combined with other coupons
"redeem_combined_max": "" // max number of coupons that can be combined
}
}
},
... // shortened result
]
}Creating a new campaign
Request URL
https://{your hublify url}/api/eos_10/data_create
Request parameter
{
"dataset": "coupon_campaign",
"fields": {
"couponcamp_label": "HFYDemoCampaign", // provide a label to identify the campaign
"couponcamp_desc": "Hublify Demo Campaign", // additional description text
"couponcamp_type": "promotion", // Enum: "promotion" or "prepaid"
"couponcamp_xsettings": {
"default": { // these will be used if no overriding values are set when creating the coupon
"cnt_label": "shop_coupon_randomized", // Label for a "counter" that should be used to create new coupons
"block": 2, // Relevant for grouping in the cart. Typically leave it with 2
"coupon_valid_end_period": "3months", // you can set a period for how long each created coupon should be valid
"coupon_value": "5", // value of each coupon (here: 5 EUR)
"coupon_value_type": "absolute" // Enum: "absolute" (= fixed value in shop-currency)
// or "relative" (= % of the cart-value)
},
"constraints": { // optional constraints - which requirements have to be met to redeem the coupon
"order_min_value": "10", // min value of the cart/order
"order_min_value_prc_mode": "brutto" // Enum: is the specified order_min_value "brutto" or "netto"
}
}
}
}Response
If your request was successful, you receive a success-message
{
"status": true,
"meta": {
"primary_key": "couponcamp_id",
"primary_value": 2 // the internal ID for the newly created campaign
}
}The coupon itself
Dataset coupon
Each coupon has unique code. It can be specific to a person or available to everyone.
Unpersonalized coupons can by used multiple times, but every person can only use each coupon once.
The constraints set within a campaign are valid for all coupons that belong to this campaign.
If the coupon itself has it's own constraints they will be combined with the ones set for the campaign.
Get currently available coupons
Tipp: You can also use all fields from coupon and coupon_campaign as filter.
Request URL
https://{your hublify url}/api/eos_10/data_getList
Request parameter
{
"dataset": "coupon",
"fields": [
"coupon_id",
"coupon_code",
"coupon_value",
"coupon_value_type",
"coupon_valid_cnt_unused",
"drvd_coupon_valid_start",
"drvd_coupon_valid_end",
"drvd_valid_now",
"coupon_personalized",
"couponcamp_label",
"coupon_xdata",
"couponcamp_xsettings"
]
}Response
{
"status": true,
"data": [
{
"coupon_id": "1",
"coupon_code": "HFYDEMO5EUR",
"coupon_value": "5.0000",
"coupon_value_type": "absolute",
"coupon_valid_cnt_unused": "1000",
"drvd_coupon_valid_start": null,
"drvd_coupon_valid_end": null,
"drvd_valid_now": "1",
"coupon_personalized": "0",
"couponcamp_label": "HFYDEMO",
"coupon_xdata": {
"coupon_constraints": {
"order_min_value": "20"
}
},
"couponcamp_xsettings": {
"default": {
"cnt_label": "shop_coupon_code",
"block": "2",
"coupon_valid_end_period": "",
"coupon_value": "",
"coupon_value_type": "absolute",
"product": ""
},
"constraints": {
"order_min_value": null,
"order_min_value_prc_mode": "brutto",
"pcode_list": "",
"category_list": "",
"pcode_list_ignore": "",
"category_list_ignore": "",
"persongroup_list": "",
"null_orders_allow": 0,
"redeem_combined_blocked": 0,
"redeem_combined_max": null
}
}
},
... // shortened result
]
}Creating a new coupon
Request URL
https://{your hublify url}/api/eos_10/data_create
Request parameter
{
"dataset": "coupon",
"fields": {
"coupon_code": "MyOwnCoupon", // your own individual code, leave empty to use campaign default
"coupon_valid_cnt_unused": "50", // how often can this coupon be used, here 50x
"coupon_valid_end": "2021-12-31 23:55:00", // how long until this coupin expires
"fk_coupon_couponcamp_id": "1", // the campaign this belongs to
"coupon_value": "15", // overrides campaign default with own value, here 15 EUR
"coupon_value_type": "absolute",
"coupon_xdata": {
"coupon_constraints": { // optional constraints - which requirements have to be met to redeem the coupon
"order_min_value": "50", // min value of the cart/order, this overrides the campaign setting
"order_min_value_prc_mode": "brutto" // Enum: is the specified order_min_value "brutto" or "netto"
}
}
}
}Response
If your request was successful, you receive a success-message
{
"status": true,
"meta": {
"primary_key": "coupon_id",
"primary_value": 2 // the internal ID for the newly created coupon
}
}Creating a new personalized coupon
Request URL
https://{your hublify url}/api/eos_10/data_create
Request parameter
{
"dataset": "coupon",
"fields": {
"coupon_code": "MyOwnPersonalCoupon", // your own individual code, leave empty to use campaign default
"coupon_valid_end": "2021-12-31 23:55:00", // how long until this coupin expires
"fk_coupon_couponcamp_id": "1", // the ID of the coupon-campaign this belongs to
"fk_coupon2person_persid": "1", // the ID of the person this belongs to
"coupon_value": "15", // overrides campaign default with own value, here 15 EUR
"coupon_value_type": "absolute",
"coupon_xdata": {
"coupon_constraints": { // optional constraints - which requirements have to be met to redeem the coupon
"order_min_value": "50", // min value of the cart/order, this overrides the campaign setting
"order_min_value_prc_mode": "brutto" // Enum: is the specified order_min_value "brutto" or "netto"
}
}
}
}Response
If your request was successful, you receive a success-message
{
"status": true,
"meta": {
"primary_key": "coupon_id",
"primary_value": 3 // the internal ID for the newly created coupon
}
}Person specific details
Details about all coupons that are available for a specific person or that he has redeemed in the past
Dataset coupon2person
Adding coupons to a cart
Request
You only need to provide the cart-id and coupon-code to add a coupon to the cart.
Hublify will automatically check if the coupon is valid and usable for your current cart
Request URL
https://{your hublify url}/api/eos_10/cart_addCoupon
Request parameter
{
"filter": {
"cart_id": 123
},
"fields": {
"coupon_code": "GUTSCHEIN123" // the coupon code
}
}Response
If your request was successful, you receive a success-message
{
"status": true,
"msg": [
{
"type": "OK",
"i18n": {
"string": "ecs_plugin_coupon.COUPON.coupon_added_to_cart",
"params": {
"coupon_code": "GUTSCHEIN123"
}
}
}
]
}If a coupon you added to the cart is not meeting the requirements yet (e.g. min value not reached) , it could still be accepted, but shows with price 0 in your cart-items.
If it's still not valid by the time your finish your purchase, it will be automatically removed from the cart.