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.

Endpoints

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]+$)	No
status	string or integer ('0', '1', 0, 1)	No
description	string	No
discount_amount	string or number	No
free_shipping	string or integer or boolean ('0', '1', 0, 1, true, false)	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 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 Yes additionalProperties No
user_condition	object	No
Field Name Field Type Required groups array of string,integer No emails array of string No purchased number No
max_uses_time_per_coupon	string (^[0-9]*$)	No
max_uses_time_per_customer	string (^[0-9]*$)	No
start_date		No
end_date		No

POST/api/coupons

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/coupons

JavaScript

fetch('https://<your domain>/api/coupons', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .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]+$)	No
status	string or integer ('0', '1', 0, 1)	No
description	string	No
discount_amount	string or number	No
free_shipping	string or integer or boolean ('0', '1', 0, 1, true, false)	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 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 Yes additionalProperties No
user_condition	object	No
Field Name Field Type Required groups array of string,integer No emails array of string No purchased number No
max_uses_time_per_coupon	string (^[0-9]*$)	No
max_uses_time_per_customer	string (^[0-9]*$)	No
start_date		No
end_date		No

PATCH/api/coupons/{id}

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/coupons/{id}

JavaScript

fetch('https://<your domain>/api/coupons/{id}', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .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 "Authorization: Bearer <admin JWT token>"
  https://<your domain>/api/coupons/{id}

JavaScript

fetch('https://<your domain>/api/coupons/{id}', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  }
})
  .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 "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/carts/{cart_id}/coupons

JavaScript

fetch('https://<your domain>/api/carts/{cart_id}/coupons', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .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

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 "Authorization: Bearer <admin JWT token>"
  https://<your domain>/api/carts/{cart_id}/coupons/{coupon}

JavaScript

fetch('https://<your domain>/api/carts/{cart_id}/coupons/{coupon}', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  }
})
  .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