Tracking API (REST)
What is this API for?
Tracking API (REST) is an endpoint that accepts sales events from
your online store or backend for Aklamio reward tracking using a
client-to-server mode or server-to-server mode.
If you want to access all functionalities that can be used through
the Partner Interface and the Agent Backoffice instead, please
check our
Partner API documentation.
API Details
Endpoint URL:
https://tracking.aklamio.com/api/v1/events
Method:
POST
Header:
Api-Secret
Authentication
This endpoint needs an additional header with the request:
Api-Secret. This header key is used to validate the
brand and promotion used in payload.
Ask your Aklmaio Customer Success Manager or Integration Manager
for your brand's API Secret Key.
Request Parameters
The Sales Event object is the main object that will be used to track
your end users' purchases. This is where the sales items and general
information will be sent to Aklamio when your request is executed.
partnerID
Identifies your program within Aklamio. If you have several
programs (e.g. countries), a distinction is made via the
partnerId.
string
required
provided by Aklamio
orderRef
A reference to the order that allows you to trace back the
order, has to be unique and is later on used for the validation
of sales.
Note that special characters are not allowed
(e.g. ,<>?;:'"\|[{]}!#$%^&*()=+`~).
string
required
checkoutLocation
Defines the checkout, in case there are several checkouts,
usually one page => one checkout location.
string
required
items
Array of items in the order. You must include at least 1 item in
the request.
Array
required
EventName
This value identifies the event type. Please use
partner-sale.
string
required
predefined
SendTimestamp
This value should be a unixtimestamp of the action to prevent
duplicated. E.g. format:
1601904516011.
string
required
aid
The AID is a direct reference to the Aklamio event (e.g.
referral) that led to this sale. The AID is provided in the URL
when a user is redirected back to your page by clicking on a
referral link. Note that AID takes precedence over any other
Aklamio tracking mechanism (coupon, cookies, etc.).
string
optional
encryptedEmail
This is only relevant for Native Cashback Sales - By setting
this parameter the reward will be assigned to the encryptedEmail
provided by the user. The encryption method must be AES-256-CBC
signed with HMAC-SHA1 and we will use this to sign up users to
Aklamio for "Native Cashback". Note that email and
encryptedEmail should not be set in the same request object.
string
optional
email
The email of the follower. It represents the referred user. Notes:
¹ email and encryptedEmail should not be set in
the same request object;
² email is not required for Keep use case;
string
optional
required if coupon is set and use case is Share or Give
coupon
The Coupon is also a direct reference to the Aklamio referral
that led to this sale. The Coupon is provided in the URL when a user is
redirected back to your page by clicking on a referral link. You can take
it from there dynamically or ask your user to paste the Coupon code manually
(Reward Codes use case) so you can pass it on to the script.
Note that email is required when using a coupon and the use
case is Share or Give.
string
optional
trackingAttribution
This value indicates whether the sale was already attributed to
another channel/competitor (and therefore it is not eligible for
a reward at Aklamio)
boolean
optional
metainfo
Here, you can provide any additional information about the
tracked sale that might be important for you for further
evaluation. We will not evaluate this info, but we can provide
it in reports.
Object
optional
Sales Item
The Item object is the main object used to create items from a sales
event. This is where one stores the item information that is to be
sent to Aklamio using api .
id
Item Identification of the Product bought and registered within
Aklamio backend sent parsed into variable. It is a dynamic field
-> please ensure that Item ID can be used for validation
string
required
name
Product name registered within Aklamio backend sent parsed into
variable. It is a dynamic field. Someone from Aklamio will send
a Matrix containing all Names registered and agreed with
Comercial department
string
optional
price
Price of the product bought. It must be sent in cents e.g: If a
product was bought for $14.00 it needs to be sent as
set.Price(1400)
number
optional
category
Name of the Product Category registered with Aklamio Backend
sent parsed into variable. It is a dynamic field. Someone from
Aklamio will send a Matrix containing all Categories registered
and agreed with Comercial department.
Note that special characters are not allowed
(e.g. /,<>?;:'”\|[{}]!@#$%^&*()=+`~).
string
optional
rewardCategory
Name of the Reward Category registered with Aklamio Backend sent
parsed into variable. It is a dynamic field. Someone from
Aklamio will send a Matrix containing all Categories registered
and agreed with Comercial department.
Note that special characters are not allowed
(e.g. /,<>?;:'”\|[{}]!@#$%^&*()=+`~).
string
optional
rewardFixed
Indicates the Fixed Reward value to be paid out to the user.
Needs to be send in cents so 14.00 will be 1400.
number
optional
rewardPercent
Indicates the % of a Reward will be paid out based on the total
item basket.
number
optional
Check the full Item object sample:
{
"id": "aklamio_test_111",
"name": "item 1",
"price": 20,
"category": "category",
"rewardFixed": null,
"rewardPercent": 1.25,
"rewardCategory": "reward_category"
}
Cashback & Encrypted Email
encryptedEmail field must only be used in Cashback
campaigns - known as Native Cashback. Remember that you can NOT use
email and encryptedEmail properties in the
same request.
In order to implement Native Cashback tracking, you needs to add an
encrypted version of your user's email address - the email address
of the cashback receiver - as a parameter in your sales tracking API
call.
For Cashback examples look up Java/Kotlin or Swift in code samples.
How to get the encrypted email value
-
As an Aklamio customer, you will receive a native cashback key
in a secure way.
-
Use that native cashback key to encrypt your user's email address
using one of the following code snippets:
