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 Name | Field Type | Required | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
coupon | string (^[a-zA-Z0-9]+$) | Yes | |||||||||||||||||||||||||||||||||
status | string or integer ('0', '1', 0, 1) | Yes | |||||||||||||||||||||||||||||||||
description | string | No | |||||||||||||||||||||||||||||||||
discount_amount | string or number | Yes | |||||||||||||||||||||||||||||||||
free_shipping | string or integer ('0', '1', 0, 1) | No | |||||||||||||||||||||||||||||||||
discount_type | string | Yes | |||||||||||||||||||||||||||||||||
target_products | object | No | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
condition | object | No | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
user_condition | object | No | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
max_uses_time_per_coupon | string (^[0-9]*$) | No | |||||||||||||||||||||||||||||||||
max_uses_time_per_customer | string (integer) | No | |||||||||||||||||||||||||||||||||
start_date | string | No | |||||||||||||||||||||||||||||||||
end_date | string | No |
POST/api/coupons
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons
fetch('https://<your domain>/api/coupons', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
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 Name | Field Type | Required | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
coupon | string (^[a-zA-Z0-9]+$) | Yes | |||||||||||||||||||||||||||||||||
status | string or integer ('0', '1', 0, 1) | No | |||||||||||||||||||||||||||||||||
description | string | No | |||||||||||||||||||||||||||||||||
discount_amount | string or number | No | |||||||||||||||||||||||||||||||||
free_shipping | string or integer ('0', '1', 0, 1) | No | |||||||||||||||||||||||||||||||||
discount_type | string | No | |||||||||||||||||||||||||||||||||
target_products | object | No | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
condition | object | No | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
user_condition | object | No | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
max_uses_time_per_coupon | string (^[0-9]*$) | No | |||||||||||||||||||||||||||||||||
max_uses_time_per_customer | string (integer) | No | |||||||||||||||||||||||||||||||||
start_date | string | No | |||||||||||||||||||||||||||||||||
end_date | string | No |
PATCH/api/coupons/{id}
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons/{id}
fetch('https://<your domain>/api/coupons/{id}', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
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
Parameter | Type | Required | Description |
---|---|---|---|
id | string | Yes | The UUID of the coupon to update |
Delete a Coupon
Removes a coupon from your EverShop store.
Request Schema (application/json)
No request body requiredDELETE/api/coupons/{id}
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons/{id}
fetch('https://<your domain>/api/coupons/{id}', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
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
Parameter | Type | Required | Description |
---|---|---|---|
id | string | Yes | The UUID of the coupon to delete |
Apply a Coupon
Applies a coupon code to a specific shopping cart.
Request Schema (application/json)
Field Name | Field Type | Required |
---|---|---|
coupon | string | Yes |
POST/api/carts/{cart_id}/coupons
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/carts/{cart_id}/coupons
fetch('https://<your domain>/api/carts/{cart_id}/coupons', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
Sample Of Response
{
"data": {
"coupon": "coupon"
}
}
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
cart_id | string | Yes | The 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 requiredGET/api/coupons/{id}
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons/{id}
fetch('https://<your domain>/api/coupons/{id}', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
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
Parameter | Type | Required | Description |
---|---|---|---|
id | string | Yes | The 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 requiredGET/api/coupons
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/coupons
fetch('https://<your domain>/api/coupons', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
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
Parameter | Type | Required | Description |
---|---|---|---|
page | integer | No | Page number for pagination (default: 1) |
limit | integer | No | Number of coupons per page (default: 20, max: 100) |
sort | string | No | Field to sort by (e.g., "coupon", "created_at") |
order | string | No | Sort order ("asc" or "desc") |
status | integer | No | Filter by status (0 = disabled, 1 = enabled) |
coupon | string | No | Filter by coupon code |
keyword | string | No | Search coupons by keyword |
Remove a Coupon from Cart
Removes a previously applied coupon from a shopping cart.
Request Schema (application/json)
No request body requiredDELETE/api/carts/{cart_id}/coupons/{coupon}
- cURL
- JavaScript
curl
-H "Accept: application/json"
-H "Cookie: asid=<your admin cookie>"
https://<your domain>/api/carts/{cart_id}/coupons/{coupon}
fetch('https://<your domain>/api/carts/{cart_id}/coupons/{coupon}', {
headers: {
'Accept': 'application/json',
'Cookie': 'asid=<your admin cookie>'
}
})
.then(response => response.json())
.then(data => {
if(data.error) {
// Handle the error
} else {
// Handle the data
}
})
.catch(error => {
// Handle the error
});
Sample Of Response
{
"data": {
"success": true
}
}
Path Parameters
Parameter | Type | Required | Description |
---|---|---|---|
cart_id | string | Yes | The UUID of the cart |
coupon | string | Yes | The coupon code to remove from the cart |
Discount Types
EverShop supports various discount types that can be specified in the discount_type
parameter:
Discount Type | Description |
---|---|
fixed_discount_to_entire_order | Applies a fixed amount discount to the entire order |
percentage_discount_to_entire_order | Applies a percentage discount to the entire order |
fixed_discount_to_specific_products | Applies a fixed amount discount to specific products only |
percentage_discount_to_specific_products | Applies a percentage discount to specific products only |
buy_x_get_y | Buy X quantity of products, get Y quantity free |
Troubleshooting
Common Error Codes
Status Code | Description | Solution |
---|---|---|
400 | Bad Request | Check your request payload for invalid data |
401 | Unauthorized | Ensure your API credentials are correct |
404 | Not Found | Verify the coupon ID exists |
409 | Conflict | The coupon code may already be in use |
422 | Validation Error | The coupon conditions are not met by the cart |
500 | Server Error | Contact support if the issue persists |