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
Field Name Field Type Required maxQty string or integer No products array of object No Field Name Field Type Required key string Yes operator string (IN, NOT IN, =, !=, >, >=, <, <=) Yes value string or number Yes
condition	object	No
Field Name Field Type Required order_total string or number No order_qty string or integer No required_products array of object No Field Name Field Type Required key string Yes operator string (IN, NOT IN, =, !=, >, >=, <, <=) Yes qty string or integer Yes value string or number Yes additionalProperties No
user_condition	object	No
Field Name Field Type Required groups array of string,integer No email string No purchased string or integer 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

curl
  -H "Accept: application/json"
  -H "Cookie: asid=<your admin cookie>"
  https://<your domain>/api/coupons

JavaScript

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
Field Name Field Type Required maxQty string or integer No products array of object No Field Name Field Type Required key string Yes operator string (IN, NOT IN, =, !=, >, >=, <, <=) Yes value string or number Yes
condition	object	No
Field Name Field Type Required order_total string or number No order_qty string or integer No required_products array of object No Field Name Field Type Required key string Yes operator string (IN, NOT IN, =, !=, >, >=, <, <=) Yes qty string or integer Yes value string or number Yes additionalProperties No
user_condition	object	No
Field Name Field Type Required groups array of string,integer No emails string No purchased string or integer 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

curl
  -H "Accept: application/json"
  -H "Cookie: asid=<your admin cookie>"
  https://<your domain>/api/coupons/{id}

JavaScript

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 required

DELETE/api/coupons/{id}

cURL

curl
  -H "Accept: application/json"
  -H "Cookie: asid=<your admin cookie>"
  https://<your domain>/api/coupons/{id}

JavaScript

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

curl
  -H "Accept: application/json"
  -H "Cookie: asid=<your admin cookie>"
  https://<your domain>/api/carts/{cart_id}/coupons

JavaScript

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 required

GET/api/coupons/{id}

cURL

curl
  -H "Accept: application/json"
  -H "Cookie: asid=<your admin cookie>"
  https://<your domain>/api/coupons/{id}

JavaScript

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 required

GET/api/coupons

cURL

curl
  -H "Accept: application/json"
  -H "Cookie: asid=<your admin cookie>"
  https://<your domain>/api/coupons

JavaScript

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 required

DELETE/api/carts/{cart_id}/coupons/{coupon}

cURL

curl
  -H "Accept: application/json"
  -H "Cookie: asid=<your admin cookie>"
  https://<your domain>/api/carts/{cart_id}/coupons/{coupon}

JavaScript

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