> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shakesco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate the Loyalty Program

> Connect your backend to the Tokens API and start rewarding customers automatically

<span style={{display:"none"}}>For the complete documentation index, see [llms.txt](/llms.txt).</span>

## Overview

Integrating the Shakesco loyalty program takes three steps:

1. **Launch your token** via the Shakesco app ([guide](/loyalty-program/launch-token))
2. **Configure your events** by setting up what actions earn tokens ([dashboard](https://users.shakesco.com/loyalty-program) or [API](/api-reference/tokens/events/set-event-details))
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](https://users.shakesco.com/user/api-tokens) and store it as an environment variable:

```bash theme={null}
SHAKESCO_API_KEY=uHdONhRNd98285c4...
```

<Warning>
  Never embed your API key in browser or mobile-client code. The Tokens API is designed for server-to-server calls only.
</Warning>

## 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:

```javascript theme={null}
// 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);
}
```

```python theme={null}
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:

```javascript theme={null}
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):

```javascript theme={null}
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:

```javascript theme={null}
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)

```javascript theme={null}
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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Rewards" icon="gift" href="/api-reference/tokens/rewards/claim-tokens">
    Claim, redeem, expire tokens
  </Card>

  <Card title="Transfer & Migration" icon="arrow-right-arrow-left" href="/api-reference/tokens/transfer/transfer-tokens">
    Transfer tokens and migrate from legacy systems
  </Card>

  <Card title="Staking" icon="coins" href="/api-reference/tokens/staking/set-staking-rate">
    Lock tokens and earn staking rewards
  </Card>

  <Card title="Vesting" icon="clock" href="/api-reference/tokens/vesting/create-vesting-grant">
    Gradual token distribution schedules
  </Card>

  <Card title="Promotions" icon="champagne-glasses" href="/api-reference/tokens/promotions/set-happy-hour">
    Happy hours and daily caps
  </Card>

  <Card title="Governance & Cashback" icon="layer-group" href="/api-reference/tokens/governance/set-tiers">
    Tiers, voting, and cashback programs
  </Card>

  <Card title="Read & Query" icon="magnifying-glass" href="/api-reference/tokens/read/balance">
    Balances, user info, activity
  </Card>

  <Card title="Events" icon="calendar" href="/api-reference/tokens/events/set-event-details">
    Manage token claim events
  </Card>
</CardGroup>