Skip to main content

Promotion API

The Promotion API allows you to programmatically manage promotional offers and discount coupons in your EverShop store. This RESTful interface provides endpoints for creating, updating, deleting, and applying coupons.

Create a Coupon

Creates a new discount coupon in your EverShop store with the specified attributes.

Request Schema (application/json)
Field NameField TypeRequired
couponstring (^[a-zA-Z0-9]+$)Yes
statusstring or integer ('0', '1', 0, 1)Yes
descriptionstringNo
discount_amountstring or numberYes
free_shippingstring or integer ('0', '1', 0, 1)No
discount_typestringYes
target_productsobjectNo
Field NameField TypeRequired
maxQtystring or integerNo
productsarray of objectNo
Field NameField TypeRequired
keystringYes
operatorstring (IN, NOT IN, =, !=, >, >=, <, <=)Yes
valuestring or numberYes
conditionobjectNo
Field NameField TypeRequired
order_totalstring or numberNo
order_qtystring or integerNo
required_productsarray of objectNo
Field NameField TypeRequired
keystringYes
operatorstring (IN, NOT IN, =, !=, >, >=, <, <=)Yes
qtystring or integerYes
valuestring or numberYes
additionalPropertiesNo
user_conditionobjectNo
Field NameField TypeRequired
groupsarray of string,integerNo
emailstringNo
purchasedstring or integerNo
max_uses_time_per_couponstring (^[0-9]*$)No
max_uses_time_per_customerstring (integer)No
start_datestringNo
end_datestringNo
POST/api/coupons
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons
Sample Of Response
{
"data": {
"coupon_id": 30,
"uuid": "d63601a5a67311edb46b60d819134f39",
"status": 1,
"description": "y2RFMOdn9LuiUtob5n1c",
"discount_amount": 10,
"free_shipping": 0,
"discount_type": "fixed_discount_to_entire_order",
"coupon": "y2RFMOdn9LuiUtob5n1c",
"used_time": 0,
"target_products": null,
"condition": null,
"user_condition": null,
"buyx_gety": null,
"max_uses_time_per_coupon": null,
"max_uses_time_per_customer": null,
"start_date": null,
"end_date": null,
"created_at": "2023-02-07 15:07:53",
"updated_at": "2023-02-07 15:07:53",
"links": [
{
"rel": "couponGrid",
"href": "/admin/coupons",
"action": "GET",
"types": [
"text/xml"
]
},
{
"rel": "edit",
"href": "/admin/coupon/edit/d63601a5a67311edb46b60d819134f39",
"action": "GET",
"types": [
"text/xml"
]
}
]
}
}

Update a Coupon

Updates an existing coupon with new attribute values.

Request Schema (application/json)
Field NameField TypeRequired
couponstring (^[a-zA-Z0-9]+$)Yes
statusstring or integer ('0', '1', 0, 1)No
descriptionstringNo
discount_amountstring or numberNo
free_shippingstring or integer ('0', '1', 0, 1)No
discount_typestringNo
target_productsobjectNo
Field NameField TypeRequired
maxQtystring or integerNo
productsarray of objectNo
Field NameField TypeRequired
keystringYes
operatorstring (IN, NOT IN, =, !=, >, >=, <, <=)Yes
valuestring or numberYes
conditionobjectNo
Field NameField TypeRequired
order_totalstring or numberNo
order_qtystring or integerNo
required_productsarray of objectNo
Field NameField TypeRequired
keystringYes
operatorstring (IN, NOT IN, =, !=, >, >=, <, <=)Yes
qtystring or integerYes
valuestring or numberYes
additionalPropertiesNo
user_conditionobjectNo
Field NameField TypeRequired
groupsarray of string,integerNo
emailsstringNo
purchasedstring or integerNo
max_uses_time_per_couponstring (^[0-9]*$)No
max_uses_time_per_customerstring (integer)No
start_datestringNo
end_datestringNo
PATCH/api/coupons/{id}
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons/{id}
Sample Of Response
{
"data": {
"coupon_id": 30,
"uuid": "d63601a5a67311edb46b60d819134f39",
"status": 1,
"description": "y2RFMOdn9LuiUtob5n1c",
"discount_amount": 10,
"free_shipping": 0,
"discount_type": "fixed_discount_to_entire_order",
"coupon": "y2RFMOdn9LuiUtob5n1c",
"used_time": 0,
"target_products": null,
"condition": null,
"user_condition": null,
"buyx_gety": null,
"max_uses_time_per_coupon": null,
"max_uses_time_per_customer": null,
"start_date": null,
"end_date": null,
"created_at": "2023-02-07 15:07:53",
"updated_at": "2023-02-07 15:07:53",
"links": [
{
"rel": "couponGrid",
"href": "/admin/coupons",
"action": "GET",
"types": [
"text/xml"
]
},
{
"rel": "edit",
"href": "/admin/coupon/edit/d63601a5a67311edb46b60d819134f39",
"action": "GET",
"types": [
"text/xml"
]
}
]
}
}

Path Parameters

ParameterTypeRequiredDescription
idstringYesThe UUID of the coupon to update

Delete a Coupon

Removes a coupon from your EverShop store.

Request Schema (application/json)
No request body required
DELETE/api/coupons/{id}
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons/{id}
Sample Of Response
{
"data": {
"coupon_id": 30,
"uuid": "d63601a5a67311edb46b60d819134f39",
"status": 1,
"description": "TRNfYH0X7kQL4Evddsy6",
"discount_amount": 20,
"free_shipping": 0,
"discount_type": "fixed_discount_to_entire_order",
"coupon": "TRNfYH0X7kQL4Evddsy6",
"used_time": 0,
"target_products": null,
"condition": null,
"user_condition": null,
"buyx_gety": null,
"max_uses_time_per_coupon": null,
"max_uses_time_per_customer": null,
"start_date": null,
"end_date": null,
"created_at": "2023-02-07 15:07:53",
"updated_at": "2023-02-07 15:07:53"
}
}

Path Parameters

ParameterTypeRequiredDescription
idstringYesThe UUID of the coupon to delete

Apply a Coupon

Applies a coupon code to a specific shopping cart.

Request Schema (application/json)
Field NameField TypeRequired
couponstringYes
POST/api/carts/{cart_id}/coupons
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/carts/{cart_id}/coupons
Sample Of Response
{
"data": {
"coupon": "coupon"
}
}

Path Parameters

ParameterTypeRequiredDescription
cart_idstringYesThe UUID of the cart to apply the coupon to

Get a Coupon

Retrieves detailed information about a specific coupon.

Request Schema (application/json)
No request body required
GET/api/coupons/{id}
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons/{id}
Sample Of Response
{
"data": {
"coupon_id": 30,
"uuid": "d63601a5a67311edb46b60d819134f39",
"status": 1,
"description": "Summer Sale Discount",
"discount_amount": 10,
"free_shipping": 0,
"discount_type": "fixed_discount_to_entire_order",
"coupon": "SUMMER10",
"used_time": 5,
"target_products": null,
"condition": {
"order_total": 50
},
"user_condition": null,
"buyx_gety": null,
"max_uses_time_per_coupon": "100",
"max_uses_time_per_customer": "1",
"start_date": "2023-06-01",
"end_date": "2023-08-31",
"created_at": "2023-02-07 15:07:53",
"updated_at": "2023-02-07 15:07:53",
"links": [
{
"rel": "couponGrid",
"href": "/admin/coupons",
"action": "GET",
"types": [
"text/xml"
]
},
{
"rel": "edit",
"href": "/admin/coupon/edit/d63601a5a67311edb46b60d819134f39",
"action": "GET",
"types": [
"text/xml"
]
}
]
}
}

Path Parameters

ParameterTypeRequiredDescription
idstringYesThe UUID of the coupon to retrieve

List Coupons

Retrieves a paginated list of coupons from your EverShop store.

Request Schema (application/json)
No request body required
GET/api/coupons
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons
Sample Of Response
{
"data": [
{
"coupon_id": 30,
"uuid": "d63601a5a67311edb46b60d819134f39",
"status": 1,
"description": "Summer Sale Discount",
"discount_amount": 10,
"free_shipping": 0,
"discount_type": "fixed_discount_to_entire_order",
"coupon": "SUMMER10",
"used_time": 5,
"max_uses_time_per_coupon": "100",
"start_date": "2023-06-01",
"end_date": "2023-08-31",
"links": [
{
"rel": "edit",
"href": "/admin/coupon/edit/d63601a5a67311edb46b60d819134f39",
"action": "GET",
"types": [
"text/xml"
]
}
]
},
// More coupons...
],
"total": 8,
"currentPage": 1,
"limit": 20,
"links": [
{
"rel": "first",
"href": "/api/coupons?page=1",
"action": "GET"
},
{
"rel": "last",
"href": "/api/coupons?page=1",
"action": "GET"
}
]
}

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination (default: 1)
limitintegerNoNumber of coupons per page (default: 20, max: 100)
sortstringNoField to sort by (e.g., "coupon", "created_at")
orderstringNoSort order ("asc" or "desc")
statusintegerNoFilter by status (0 = disabled, 1 = enabled)
couponstringNoFilter by coupon code
keywordstringNoSearch coupons by keyword

Remove a Coupon from Cart

Removes a previously applied coupon from a shopping cart.

Request Schema (application/json)
No request body required
DELETE/api/carts/{cart_id}/coupons/{coupon}
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/carts/{cart_id}/coupons/{coupon}
Sample Of Response
{
"data": {
"success": true
}
}

Path Parameters

ParameterTypeRequiredDescription
cart_idstringYesThe UUID of the cart
couponstringYesThe coupon code to remove from the cart

Discount Types

EverShop supports various discount types that can be specified in the discount_type parameter:

Discount TypeDescription
fixed_discount_to_entire_orderApplies a fixed amount discount to the entire order
percentage_discount_to_entire_orderApplies a percentage discount to the entire order
fixed_discount_to_specific_productsApplies a fixed amount discount to specific products only
percentage_discount_to_specific_productsApplies a percentage discount to specific products only
buy_x_get_yBuy X quantity of products, get Y quantity free

Troubleshooting

Common Error Codes

Status CodeDescriptionSolution
400Bad RequestCheck your request payload for invalid data
401UnauthorizedEnsure your API credentials are correct
404Not FoundVerify the coupon ID exists
409ConflictThe coupon code may already be in use
422Validation ErrorThe coupon conditions are not met by the cart
500Server ErrorContact support if the issue persists