API Documentation
Integrate Beekeeper coupon validation and redemption into your checkout flow.
Quick Start
The integration involves two API calls in your checkout flow:
- Validate the coupon token when a customer applies it at checkout
- Redeem the coupon token when the order is confirmed
Both endpoints are server-to-server and require your API key.
Base URL: https://api.beekeeper.bz/api/v1
Authentication
All API calls require an API key passed in the X-API-Key header. Generate API keys from your Merchant Dashboard.
X-API-Key: bk_live_your_api_key_hereKeep your API keys secret. Never expose them in client-side code or public repositories.
Validate a Coupon
Call this when a customer enters a coupon code at checkout. Returns the discount amount and final price.
/coupon/validateValidate a coupon token and calculate the discount
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| token | string | Yes | The coupon token the customer entered |
| cart_amount | number | Yes | Cart total before discount (e.g. 99.99) |
| currency | string | No | 3-letter currency code (default: "USD") |
| customer_id | string | No | Your customer ID (for per-customer usage caps) |
Example
curl -X POST https://api.beekeeper.bz/api/v1/coupon/validate \
-H "Content-Type: application/json" \
-H "X-API-Key: bk_live_your_api_key" \
-d '{
"token": "eyJtZXJjaGFudF9pZCI...",
"cart_amount": 100.00,
"currency": "USD"
}'{
"valid": true,
"discount_amount": 10.00,
"final_amount": 90.00,
"offer": {
"type": "percentage",
"value": 10,
"name": "10% Off Summer Sale"
},
"message": "Coupon applied: 10% off"
}Redeem a Coupon
Call this after the order is confirmed/paid. This marks the coupon as used and triggers billing.
/coupon/redeemRedeem a coupon token (marks it as used)
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| token | string | Yes | The same coupon token that was validated |
| order_ref | string | Yes | Your order/transaction reference ID |
| cart_amount | number | Yes | Final cart total after discount |
| discount_amount | number | Yes | The discount amount applied |
| currency | string | No | 3-letter currency code (default: "USD") |
| customer_id | string | No | Your customer ID |
Example
curl -X POST https://api.beekeeper.bz/api/v1/coupon/redeem \
-H "Content-Type: application/json" \
-H "X-API-Key: bk_live_your_api_key" \
-d '{
"token": "eyJtZXJjaGFudF9pZCI...",
"order_ref": "ORDER-12345",
"cart_amount": 90.00,
"discount_amount": 10.00,
"currency": "USD"
}'{
"success": true,
"message": "Coupon redeemed successfully",
"redemption_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"beekeeper_fee": 1.10,
"creator_commission": 5.00
}Integration Flow
Here's how to integrate Beekeeper into a typical e-commerce checkout:
Customer gets a coupon token
Via a creator's link on your Beekeeper landing page. The token is a JWT string.
Customer enters token at checkout
Add a "coupon code" input to your checkout page.
Your backend calls POST /coupon/validate
Send the token + cart amount. Get back the discount. Display it to the customer.
Customer completes payment
Process payment as normal with the discounted amount.
Your backend calls POST /coupon/redeem
Confirm the redemption. The coupon is now used. Beekeeper handles billing and creator payouts.
Node.js Example
const BEEKEEPER_API = 'https://api.beekeeper.bz/api/v1';
const API_KEY = process.env.BEEKEEPER_API_KEY;
// Step 1: Validate the coupon when customer applies it
async function validateCoupon(token, cartAmount) {
const res = await fetch(`${BEEKEEPER_API}/coupon/validate`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': API_KEY,
},
body: JSON.stringify({ token, cart_amount: cartAmount }),
});
if (!res.ok) {
const err = await res.json();
throw new Error(err.message);
}
return res.json();
// { valid: true, discount_amount: 10, final_amount: 90, ... }
}
// Step 2: Redeem after order is confirmed
async function redeemCoupon(token, orderRef, cartAmount, discountAmount) {
const res = await fetch(`${BEEKEEPER_API}/coupon/redeem`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': API_KEY,
},
body: JSON.stringify({
token,
order_ref: orderRef,
cart_amount: cartAmount,
discount_amount: discountAmount,
}),
});
if (!res.ok) {
const err = await res.json();
throw new Error(err.message);
}
return res.json();
// { success: true, redemption_id: "...", beekeeper_fee: 1.10, ... }
}Python Example
import requests
import os
BEEKEEPER_API = "https://api.beekeeper.bz/api/v1"
API_KEY = os.environ["BEEKEEPER_API_KEY"]
headers = {
"Content-Type": "application/json",
"X-API-Key": API_KEY,
}
# Validate
resp = requests.post(f"{BEEKEEPER_API}/coupon/validate", json={
"token": coupon_token,
"cart_amount": 100.00,
}, headers=headers)
data = resp.json()
discount = data["discount_amount"] # 10.00
# Redeem (after payment)
resp = requests.post(f"{BEEKEEPER_API}/coupon/redeem", json={
"token": coupon_token,
"order_ref": "ORDER-12345",
"cart_amount": 90.00,
"discount_amount": 10.00,
}, headers=headers)
result = resp.json()
# {"success": True, "redemption_id": "..."}Error Handling
All errors return a JSON object with error and message fields.
| HTTP Code | Error | Description |
|---|---|---|
| 400 | token_expired | The coupon token has expired |
| 400 | token_already_redeemed | This coupon has already been used |
| 400 | campaign_inactive | The campaign is no longer active |
| 401 | invalid_api_key | API key is missing or invalid |
| 404 | token_not_found | Coupon token not found in the system |
| 429 | rate_limited | Too many requests (see Rate Limits) |
{
"error": "token_expired",
"message": "This coupon token has expired. Please request a new one."
}Rate Limits
| Endpoint | Limit |
|---|---|
| POST /coupon/validate | 60 requests per minute per API key |
| POST /coupon/redeem | 60 requests per minute per API key |
When rate limited, the response includes a retry_after field (in seconds).