Overview
Integrating the Shakesco loyalty program takes three steps:- Launch your token via the Shakesco app (guide)
- Configure your events by setting up what actions earn tokens (dashboard or API)
- Call the API from your backend to award tokens when customers take those actions
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:How Customers Are Identified
Every customer-targeted endpoint takes acustomer_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:
- Send the same value every time for the same customer.
user-7421and7421hash to different things; the contract would see two different people. - It only has to be unique inside your business. The hash is scoped to your business contract.
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:
Step 3: Show Customers Their Balance
Fetch a customer’s token balance whenever they log in or view their rewards page:Step 4: Let Customers Redeem Tokens
When a customer redeems a reward in your app:Common Integration Patterns
Check before claiming (one-time events)
Award cashback after a purchase
Start a happy hour programmatically
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