Learn how to add, edit and delete codes using Kotobee API.

The Promo Code API lets you control all aspects of promo codes for your cloud ebook or library, such as adding, editing, and deleting codes.

Please make sure you read the Kotobee API Introduction before starting out here.

Add code

This URL base API (https://www.kotobee.com/api/v1/promocode/add) adds a new promo code to the system or adds additional access to an existing user. Available variables are as follows,

serial or accesskey 
Contains your authentication method.
codenameThe promo code that the user will use for login (optional). If no code is specified, a random one will be generated.
uid
Promo code ID. You may use the ID if you would like to add additional access to an already existing promo code.
libidThe library ID, in case the code will be a global code (has access over everything).
catidThe category ID, in case the code will have permission over a certain category. This variable is available for libraries only.
bidThe book ID, in case the code will have permission over a certain book. This variable is available for libraries only.
cidThe cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the past three variables (libid, bid, catid) will take effect.
infoAny additional info about this promo code.
activeIf the value is 1, then the code will be activated straight away after creation.

Here's an example of a URL that adds a code (SPECIALPROMO) and assigns permissions to the library with ID 42:

https://www.kotobee.com/api/v1/promocode/add?serial=123456789&codename=SPECIALPROMO&libid=42&active=1

This is an example on how to do it using POST variables with PHP:

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => "https://www.kotobee.com/api/v1/promocode/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_SSL_VERIFYPEER => false,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POST => true
));

$data = array();
$data["serial"] = "1234-5678-9999-9999";
$data["codename"] = "SPECIALPROMO";
$data["libid"] = "42";
$data["active"] = "1";
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);

$resp = curl_exec($curl);
//echo $resp;     //in case you want to view the result
curl_close($curl);
If you, later on, would like to add further permissions to the same promo code, make a separate API call for the add operation, using the ID (uid) of that promo code.
Postman example

Edit code 

This URL base API (https://www.kotobee.com/api/v1/promocode/edit )edits an existing promo code. Available variables are as follows, 
serial or accesskey  Contains your authentication method.
codeThe existing promo code.
uidThe ID of the promo code, to use as an identifier instead of the code (above).
codename
A new code name to use instead of the existing.
libid The library ID, in case the user will be a global user (has access over everything).
catid The category ID, in case the user will have permission over a certain category. This variable is available for libraries only.
bid The book ID, in case the user will have permission over a certain book. This variable is available for libraries only .
chaptersIf the user will receive permissions over a certain book (either library ebook or cloud ebook), you may specify the chapter indices that the user can only access. Leaving this blank will give access to the entire book (optional).
chaptersappend

If the chapters variable is passed, you can control whether to append those list of chapters to the user's current accessed chapters, or to overwrite them. The default behavior is to overwrite them (optional).

cid The cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the past three variables (libid, bid, catid) will take effect .
infoAny additional info about this promo code.
active If the value is 1, the user will be activated straight away after creation.

Here's an example of a URL that deactivates a promo code from the system:

https://www.kotobee.com/api/v1/promocode/edit?serial=1234-5678-9999-9999&code=SPECIALPROMO&active=0    

Postman example

Delete code   

This is a URL base API (https://www.kotobee.com/api/v1/promocode/delete ) that deletes an existing promo code entirely or removes access to an entity (library, category, or book). Available variables are as follows,

serial or accesskey Contains your authentication method
codeThe existing promo code.
uid
The ID of the promo code, to use as an identifier instead of the code (above).
libid The library ID, in case you want to remove access from the library (globally).
catid The category ID, in case you want to remove access from a certain category.
bid The book ID, in case you want to remove access from a certain book.
cid  The cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the past three variables (libid, bid, catid) will take effect.
deleteallIf the value is 1, then the code will be deleted entirely from the system (all access).

Here's an example of a URL that deletes the promo code entirely:

http://www.kotobee.com/api/v1/user/promocode?serial=1234-5678-9999-9999&code=SPECIALPROMO&deleteall=1

Postman example

Error codes  

The API may return the following error codes depicting various meanings
s_authError
The serial number or access key used is not registered with Kotobee Cloud.
s_wrongUser
The library or cloud ebook you are trying to reach cannot be accessed by your serial number.
s_codenameExists
Specified code is already being used.
s_codeIdMissing
No code identifier (code or ID) provided.
s_userNotRegistered
When requesting an edit or delete operation, the promo code is not registered.
s_userDontExist
When requesting to delete a user's access to a particular entity, this user access may not exist.