Beekeeper - Privacy-Focused Coupon Platform

Quick Start

The integration involves two server-to-server 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 require your API key, sent in the X-API-Key header.

Base URL

All requests are sent to https://api.beekeeper.bz/api/v1. Use HTTPS only.

Authentication

All API calls require an API key passed in the X-API-Key header. Generate keys from your Merchant Dashboard.

X-API-Key: bk_live_your_api_key_here

Keep your API keys secret. Never expose them in client-side code or public repositories. Rotate compromised keys immediately from the dashboard.

Validate a Coupon

Call this when a customer enters a coupon code at checkout. Returns whether the coupon is valid and the calculated discount.

POST

/coupon/validate

Validate a coupon token and calculate the discount amount.

Request body

Field	Type	Required	Description
token	string	Required	The coupon token the customer entered.
cart_amount	number	Required	Cart total before discount (e.g. 99.99).
currency	string	Optional	3-letter currency code. Default: "USD".
customer_id	string	Optional	Your customer ID — used for per-customer usage caps.

Example request & response

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"
  }'

Redeem a Coupon

Call this after the order is confirmed and paid. This marks the coupon as used and triggers billing.

POST

/coupon/redeem

Redeem a coupon token. Marks it as used and reports the redemption for billing and creator commission tracking.

Request body

Field	Type	Required	Description
token	string	Required	The same coupon token that was validated.
order_ref	string	Required	Your order or transaction reference ID.
cart_amount	number	Required	Final cart total after discount.
discount_amount	number	Required	The discount amount that was applied.
currency	string	Optional	3-letter currency code. Default: "USD".
customer_id	string	Optional	Your customer ID.

Example request & response

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"
  }'

Idempotency

Use a unique order_ref per order. Re-sending the same order_ref for an already-redeemed coupon returns the original redemption — no double billing.

Integration Flow

Here's the typical lifecycle of a Beekeeper coupon in your checkout flow:

1

Customer gets a coupon token

Via a creator's link on your Beekeeper landing page. The token is a JWT string.

2

Customer enters token at checkout

Add a "coupon code" input to your checkout page.

3

Your backend calls POST /coupon/validate

Send the token + cart amount. Get back the discount. Display it to the customer.

4

Customer completes payment

Process payment as normal with the discounted amount.

5

Your backend calls POST /coupon/redeem

Confirm the redemption. The coupon is now used. Beekeeper handles billing and creator payouts.

Code Examples

Working snippets for the full validate-then-redeem flow:

const BEEKEEPER_API = 'https://api.beekeeper.bz/api/v1';
const API_KEY = process.env.BEEKEEPER_API_KEY;

// 1. Validate at checkout
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) throw new Error((await res.json()).message);
  return res.json();
}

// 2. Redeem after payment 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) throw new Error((await res.json()).message);
  return res.json();
}

Error Handling

All errors return a JSON object with error and message fields. HTTP status codes follow standard conventions.

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 the Rate Limits section.

{
  "error": "token_expired",
  "message": "This coupon token has expired. Please request a new one."
}

Rate Limits

Each API key is rate-limited to protect platform stability. Limits are per-endpoint, per-API key.

Endpoint	Limit
POST `/coupon/validate`	60 requests / minute per API key
POST `/coupon/redeem`	60 requests / minute per API key

When rate limited, the response includes a retry_after field (in seconds). Implement exponential backoff in production.

API Documentation

Quick Start

Authentication

Validate a Coupon

Request body

Example request & response

Redeem a Coupon

Request body

Example request & response

Integration Flow

Code Examples

Error Handling

Rate Limits