Documentation

Integrate in three calls

Browser clients call /quote with a member token. Merchant servers call /redeem after payment success and /rollback after refunds.

1. Quote in the storefront

  • Use the JS SDK with a short-lived member JWT
  • Pass store_id, cart items, and total amount
  • Render best_benefit.final_price and member badges

2. Redeem after payment

  • Send Idempotency-Key on every redeem call
  • Authenticate with x-api-key, x-timestamp, x-signature
  • Persist the returned redemption_id on the merchant order

3. Roll back on refunds

  • Use a new Idempotency-Key for rollback
  • Pass the original order_id and refund reason
  • Couponify restores rule usage automatically
const timestamp = Date.now().toString();
const body = {
  order_id: "ord_9001",
  store_id: "demo-store",
  quote_id: "quote_123",
  final_paid_amount: 80,
  currency: "USD"
};

const signature = hmacSha256(
  merchantSecret,
  `${timestamp}.${JSON.stringify(body)}`
);

fetch("https://api.couponify.ai/api/redeem", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": merchantKey,
    "x-timestamp": timestamp,
    "x-signature": signature,
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify(body)
});