Skip to main content
For the complete documentation index, see llms.txt.

​
Overview

Integrating the Shakesco loyalty program takes three steps:
  1. Launch your token via the Shakesco app (guide)
  2. Configure your events by setting up what actions earn tokens (dashboard or API)
  3. Call the API from your backend to award tokens when customers take those actions
All API calls go to https://tokens.shakesco.com with your API key.

​
Step 1: Get Your API Key

Generate a key from users.shakesco.com/user/api-tokens and store it as an environment variable: 
SHAKESCO_API_KEY=uHdONhRNd98285c4...
Never embed your API key in browser or mobile-client code. The Tokens API is designed for server-to-server calls only.

​
How Customers Are Identified

Every customer-targeted endpoint takes a customer_ref field: any string that uniquely identifies that customer inside your business. It can be a UUID, your database primary key, an account number, a phone number, or an email. Two rules:
  1. Send the same value every time for the same customer. user-7421 and 7421 hash to different things; the contract would see two different people.
  2. It only has to be unique inside your business. The hash is scoped to your business contract.
The examples below use short strings like customer-123. In real code, pass whatever stable internal ID you already have, usually your DB primary key. Email works too, but if a customer ever changes their email you would lose access to their balance, which is why we recommend a stable opaque ID.

​
Step 2: Award Tokens on Customer Actions

Call /claim-tokens whenever a customer completes an event you’ve configured: 
// After a customer signs up
async function onCustomerSignup(customerRef) {
  const response = await fetch("https://tokens.shakesco.com/claim-tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SHAKESCO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      event_name: "signup",
      customer_ref: customerRef,
    }),
  });

  const { tx_hash } = await response.json();
  console.log("Tokens credited:", tx_hash);
}

import os, requests

def on_customer_signup(customer_ref: str):
    response = requests.post(
        "https://tokens.shakesco.com/claim-tokens",
        headers={
            "Authorization": f"Bearer {os.environ['SHAKESCO_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={"event_name": "signup", "customer_ref": customer_ref}
    )
    data = response.json()
    print("Tokens credited:", data.get("tx_hash"))

​
Step 3: Show Customers Their Balance

Fetch a customer’s token balance whenever they log in or view their rewards page: 
async function getCustomerBalance(customerRef) {
  const res = await fetch(
    `https://tokens.shakesco.com/balance?customer_ref=${encodeURIComponent(customerRef)}`,
    { headers: { Authorization: `Bearer ${process.env.SHAKESCO_API_KEY}` } }
  );
  const { balance } = await res.json();
  // balance is a plain decimal string, e.g. "50.0"
  return Number(balance);
}
For a full snapshot (balance, tier, staked, vested, voting power): 
const res = await fetch(
  `https://tokens.shakesco.com/user-info?customer_ref=${encodeURIComponent(customerRef)}`,
  { headers: { Authorization: `Bearer ${process.env.SHAKESCO_API_KEY}` } }
);
const info = await res.json();

​
Step 4: Let Customers Redeem Tokens

When a customer redeems a reward in your app: 
async function redeemTokens(customerRef, tokenAmount) {
  const response = await fetch("https://tokens.shakesco.com/redeem-tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SHAKESCO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ customer_ref: customerRef, amount: tokenAmount }),
  });
  return response.json();
}

​
Common Integration Patterns

​
Check before claiming (one-time events)

const check = await fetch(
  `https://tokens.shakesco.com/has-claimed-event?customer_ref=${customerRef}&event_name=signup`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { has_claimed } = await check.json();

if (!has_claimed) {
  await claimTokens("signup", customerRef);
}

​
Award cashback after a purchase

// Record the spending - Shakesco awards cashback automatically if threshold is met
await fetch("https://tokens.shakesco.com/process-cashback", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    customer_ref: customerRef,
    spent_amount: 600,
    currency: "KES",
  }),
});

​
Start a happy hour programmatically

// 2× tokens for the next 2 hours
await fetch("https://tokens.shakesco.com/set-happy-hour", {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ duration: "7200", multiplier: 2 }),
});

​
What’s Available in the API

Rewards

Claim, redeem, expire tokens

Transfer & Migration

Transfer tokens and migrate from legacy systems

Staking

Lock tokens and earn staking rewards

Vesting

Gradual token distribution schedules

Promotions

Happy hours and daily caps

Governance & Cashback

Tiers, voting, and cashback programs

Read & Query

Balances, user info, activity

Events

Manage token claim events