Coupons

Validate a coupon

Previews a coupon without consuming it. Reports whether the coupon can be redeemed by the current tenant.

Behavior

  • For free_signature coupons, signatures_count indicates how many free signatures would be granted.
  • For discount coupons, discount_will_apply is true: the discount is applied directly at signature checkout (NOT via /coupons/redeem).
  • is_valid is true only if the coupon is active, not expired, not saturated, and not already redeemed by this tenant.

Usage Example

curl -X POST https://api.faireplace.com/api/coupons/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "PROMO2024" }'

Response:

{
  "code": "PROMO2024",
  "kind": "free_signature",
  "description": "2 free signatures",
  "signatures_count": 2,
  "discount_will_apply": false,
  "already_redeemed": false,
  "is_valid": true
}
post/coupons/validate

Request

  • Base URL: https://api.faireplace.com/api
  • URL: https://api.faireplace.com/api/coupons/validate
  • Auth: HTTP bearer

Request body

codestring required

Coupon code to validate (case as provided by the user).

Example request

{
  "code": "PROMO2024"
}

Response

Coupon preview.

codestring required

Coupon code.

kind'discount' | 'free_signature' required

Type of coupon.

  • discount: a Stripe discount applied directly at signature checkout (NOT redeemable via POST /coupons/redeem).
  • free_signature: grants a number of free signatures, converted into credits when redeemed.
descriptionstring nullable

Optional human-readable description of the coupon.

signatures_countinteger

Number of free signatures granted by the coupon.

Only present when kind is free_signature (omitted otherwise).

discount_will_applyboolean required

true when kind is discount, meaning a Stripe discount will be applied automatically at signature checkout.

already_redeemedboolean required

Whether the current tenant has already redeemed this coupon.

is_validboolean required

true if the coupon is active, not expired, not saturated (max redemptions not reached) and not already redeemed by this tenant.

Example response

{
  "code": "PROMO2024",
  "kind": "free_signature",
  "description": "2 free signatures",
  "signatures_count": 2,
  "is_valid": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.