If you haven't done so already, we recommend reading the Kotobee API Introduction.


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



Add code


https://www.kotobee.com/api/v1/promocode/add

Add a new promo code into the system, or add 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
active
If value is 1, then code will be activated straight away after creation


Here's an example 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


An example of 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

    

https://www.kotobee.com/api/v1/promocode/edit 

 

 Edit 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
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
active 
If value is 1, then user will be activated straight away after creation
     

Here's an example 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
    

https://www.kotobee.com/api/v1/promocode/delete 

 

Delete an existing promo code entirely, or remove 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
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 value is 1, then the code will be deleted entirely from the system (all access)

   

Here's an example 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 following errors codes may be returned by the API depicting various meaning

  

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