Overview
This guide helps you to connect your custom-built e-commerce website with Lootly, step by step.
Please note that API access is offered in the Advanced plan of Lootly.
Follow the steps below to finish the integration.
Step 1: Enable API under Integrations
Login into your Lootly account;
Navigate to Integrations -> Overview -> Custom API
Click on Connect to enable API
Once you click Connect, you'll land on the API screen where you should enable the API:
Save your changes.
Step 2: Setup spending rewards and upload coupon codes
Once you have enabled the API integration in Lootly, navigate to Points ->Spending to set up the spending rewards for your customers.
Go to Points -> Spending;
Click on Add Reward and choose the type of rewards that you’ll offer in your program;
In the reward page, scroll down to the Reward Codes section -> click on Add Codes:
4. An import tool will open prompting you to upload a document with your coupon codes. This should be a simple CSV file with 1 column containing your coupon codes:
Step 3: Install the widget on your website
Paste our core script into your page header above the </head> tag
<script type="text/javascript" src="https://lootly.io/js/integrations/common/script.js"></script>
2. Paste the following div at the bottom of your page just inside of the </body> tag.
Replace the XXX variables with the appropriate values.
<div id="lootly-widget" class="lootly-init" style="display: none"
data-provider="https://lootly.io"
data-api-key="xxx"
data-shop-domain="https://yoursite.com"
data-shop-id="xxx"
data-customer-id="xxx"
data-customer-signature="xxx">
</div>
Note that customer ID and customer signature will be empty when a user is not logged in.
If no customer is provided, the widget will behave in "non logged in mode".
If a customer is logged in and passed to the widget, it will behave in "logged in" mode and show that customer's specific data.
Data-shop-id is an MD5 hash of your domain concatenated with API secret.
Customer signature is an MD5 hash of customer ID concatenated with API secret.
PHP Example:
<?php
$lootly_customer_id = ''; // will be empty if not logged in
$lootly_customer_signature = ''; // will be empty if not logged in
$api_key = 'xxx';
$api_secret = 'xxx';
$lootly_shop_domain = 'https://yoursite.com';
$lootly_shop_signature = md5($lootly_shop_domain.$api_secret);
if(get_current_user_id()){ // check if user is logged in to your store
$lootly_customer_id = get_current_user_id();
$lootly_customer_signature = md5($lootly_customer_id.$api_secret);
}
?>
<div id="lootly-widget" class="lootly-init" style="display: none"
data-provider="https://lootly.io"
data-api-key="<?php echo esc_html($api_key); ?>"
data-shop-domain="<?php echo esc_url($lootly_shop_domain); ?>"
data-shop-id="<?php echo $lootly_shop_signature; ?>"
data-customer-id="<?php echo $lootly_customer_id; ?>"
data-customer-signature="<?php echo $lootly_customer_signature; ?>">
</div>
Step 4: Order Processing API
Call the Orders API when new orders come in so points can be rewarded
Whenever an order is completed and ready to be awarded points, call the following API:
Reference Docs:
////////////
PHP Example:
////////////
$api_key = "xxx";
$api_secret = "xxx";
$customer = [
'id' => "001", // your internal, unique ID for the customer
'email' => "support@lootly.io",
'first_name' => "James",
'last_name' => "Bond",
'birthday' => "1970-01-01",
'default_address' => (object)[
'zip' => "11111",
'country' => "USA"
]
];
$coupons = [
(object)["code" => "COUPON_CODE"] // coupon codes used on the order
];
$requestParams = [
"id" => "100001", // Order ID
"total_price" => "39.99",
"total_tax" => "0.00",
"total_discounts" => "10.00",
"subtotal_price" => "29.99",
"taxes_included" => "0",
"discount_codes" => $coupons,
"customer" => $customer,
"key" => $api_key
];
ksort($requestParams); // sort the parameters
$hmac = base64_encode(hash_hmac('sha256', json_encode($requestParams), $api_secret, true));
$requestParams['hmac'] = $hmac;
$payload = json_encode($requestParams);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://lootly.io/integrations/webhooks/common/orders-completed",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json"
),
));
$response = curl_exec($curl);
curl_close($curl);
2. Call the Refund API when orders are refunded or cancelled so points can be subtracted.
Whenever an order is refunded or cancelled ( you can set the status in Integrations ), call the following API to remove the previously given points:
Reference Docs: https://lootly.stoplight.io/docs/lootly-api/API/Orders/Orders.json/paths/~1integrations~1webhooks~1%7Bintegration-name%7D~1orders-cancelled/post
$api_key = "xxx";
$api_secret = "xxx";
$transactions = [
(object)["amount" => "15.99"] // the amount that was refunded (if not a partial refund, this should match the order total for a full refund)
];
$requestParams = [
"id" => "100001", // Order ID
"transactions" => $transactions,
"key" => $api_key
];
ksort($requestParams); // sort the parameters
$hmac = base64_encode(hash_hmac('sha256', json_encode($requestParams), $api_secret, true));
$requestParams['hmac'] = $hmac;
$payload = json_encode($requestParams);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://lootly.io/integrations/webhooks/common/refunds-create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json"
),
));
$response = curl_exec($curl);
curl_close($curl);
Click here to access the full API documentation.
General API Notes
HTTP Status Codes:
200: Successful request
201: API endpoint not found
401: Failed authentication (incorrect hmac)
500: Integration not found