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). Must be greater than 0.
currency	string	Optional	3-letter currency code. Default: "USD".
customer_id	string	Optional	Optional. Stored only as a salted-free SHA-256 hash for fraud analytics. It does NOT enforce any per-customer usage cap — implement per-customer limits in your own checkout.

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 — note this is the opposite of /validate. Platform fee and creator commission are computed from cart_amount + discount_amount, so under-reporting is a billing violation.
discount_amount	number	Required	The discount actually applied. Must match the discount_amount returned by /validate; anything larger is rejected with invalid_discount.
currency	string	Optional	3-letter currency code. Default: "USD".
customer_id	string	Optional	Optional. Stored only as a SHA-256 hash for fraud analytics; enforces no usage cap.

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" \
  -H "Idempotency-Key: 7f4c1e2a-9b3d-4e5f-8a1b-2c3d4e5f6a7b" \
  -d '{
    "token": "eyJtZXJjaGFudF9pZCI...",
    "order_ref": "ORDER-12345",
    "cart_amount": 90.00,
    "discount_amount": 10.00,
    "currency": "USD"
  }'

Idempotency-Key: safe retries

Send an Idempotency-Key header with every redeem — any unique string per redemption attempt (a UUID, or your own order ID). If the request times out or the connection drops, retry with the same key: the original response is replayed verbatim with"idempotent_replay": true, and no second redemption, fee or commission is recorded. Reusing a key with a different request body returns 409 idempotency_key_reused. Keys are scoped to your merchant account.

order_ref is a duplicate guard, not an idempotency key

order_ref must be unique per order. Re-sending an order_refthat already has a redemption returns 400 duplicate_order; it does notreplay the original response — that is what Idempotency-Key above is for. If you are not sending an idempotency key, treat both duplicate_order andcoupon_already_redeemed as “this redemption already succeeded” and complete the order — do not retry in a loop and do not fail the customer’s order. Persist the redemption_id from the first successful call so your own records stay authoritative.

Report accurate cart amounts

Fees are charged on the pre-discount cart total —cart_amount + discount_amount. Where you also called/coupon/validate for the same token, we record the cart total you reported there. If the pre-discount total you report at redeem is materially lower than that validated figure — a shortfall greater than 1% of the validated cart or $1.00, whichever is larger — the platform fee and creator commission are calculated on the validated (higher) amount and the discrepancy is flagged for review. The redemption still succeeds; only the calculation basis changes. Ordinary cart changes between validate and payment (shipping, tax, a removed line item) fall inside the tolerance. See Terms § 7.1.

Redeem only after payment is captured

/coupon/validate does not reserve or lock the coupon — the same token can validate successfully many times, and in two checkouts at once. Only /coupon/redeem consumes it, and only the first concurrent redeem wins. Call redeem after payment is captured, and if it fails withcoupon_already_redeemed, re-price the order without the discount rather than shipping it discounted.

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 an opaque HMAC-signed string — treat it as a secret and never log it in full.

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	invalid_token_expired	The coupon token has expired.
400	invalid_token_invalid_signature	The token signature did not verify — the token was tampered with or is not ours.
400	coupon_expired	The stored coupon record has passed its expiry.
400	coupon_already_used	Returned by /validate when the coupon is already redeemed.
400	coupon_already_redeemed	Returned by /redeem when the coupon is already redeemed.
400	invalid_coupon	The coupon does not belong to your merchant account.
400	offer_suspended	The underlying offer has been suspended.
400	offer_limit_reached	The offer hit its maximum number of redemptions.
400	below_minimum	Cart total is under the offer’s minimum cart value.
400	currency_mismatch	Cart currency does not match the offer currency.
400	invalid_discount	The discount_amount you sent exceeds what the offer allows.
400	duplicate_order	This order_ref has already been used for a redemption.
401	invalid_api_key	API key is missing, malformed, or invalid.
404	coupon_not_found	Coupon token not found in the system.
429	rate_limit_exceeded	Too many requests — see the Rate Limits section.

{
  "error": "coupon_expired",
  "message": "Coupon has expired."
}

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