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/addadds a new promo code to the system or adds additional access to an existing user. Available variables are as follows,

serial
Contains your serial number.
codename
The 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.
libid
The library ID, in case the code will be a global code (has access over everything).
catid
The category ID, in case the code will have permission over a certain category. This variable is available for libraries only.
bid
The book ID, in case the code will have permission over a certain book. This variable is available for libraries only.
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.
info
Any additional info about this promo code.
active
If 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.

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  
Contains your serial number.
code 
The existing promo code.
uid 
The 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 .
chapters
If 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 .
info 
Any 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    

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  
Contains your serial number 
code 
The 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.
chapters
If 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.
deleteall 
If 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

Error codes  

The API may return the following error codes depicting various meanings
s_authError 

 
The serial number 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.