API Setup Guide

Learn how to connect your custom-built ecommerce site to Lootly to launch your loyalty program for your e-store.

Aleksandra Velkova avatar
Written by Aleksandra Velkova
Updated over a week ago

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

  1. Login into your Lootly account;

  2. Navigate to Integrations -> Overview -> Custom API

  3. Click on Connect to enable API

Lootly integrations

Once you click Connect, you'll land on the API screen where you should enable the API:

API integration Lootly

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.

  1. Go to Points -> Spending;

  2. Click on Add Reward and choose the type of rewards that you’ll offer in your program;

  3. In the reward page, scroll down to the Reward Codes section -> click on Add Codes:

API custom 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:

API custom code lootly

Step 3: Install the widget on your website

  1. 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

  1. 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:

$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

Did this answer your question?