Coupons

Coupon validation and redemption (free-signature / discount codes).

Validate a coupon

POST

https://api.faireplace.com/api

/coupons/validate

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

Code
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
{
  "code": "PROMO2024",
  "kind": "free_signature",
  "description": "2 free signatures",
  "signatures_count": 2,
  "discount_will_apply": false,
  "already_redeemed": false,
  "is_valid": true
}

Validate a coupon › Request Body

Request to preview a coupon without consuming it.

ValidateCouponRequest

code

string · minLength: 1 · maxLength: 64 · required

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

Example: PROMO2024

Validate a coupon › Responses

Coupon preview.

Preview of a coupon. This endpoint does NOT consume the coupon; it only reports whether it can be redeemed by the current tenant.

ValidateCouponResponse

code

string · required

Coupon code.

Example: PROMO2024

kind

CouponKind · enum · 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.

Enum values:

discount

free_signature

Example: free_signature

discount_will_apply

boolean · required

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

Example: false

already_redeemed

boolean · required

Whether the current tenant has already redeemed this coupon.

Example: false

is_valid

boolean · required

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

Example: true

description

string | null

Optional human-readable description of the coupon.

Example: 2 free signatures

signatures_count

integer · int32

Number of free signatures granted by the coupon.

Only present when kind is free_signature (omitted otherwise).

Example: 2

Redeem a coupon

POST

https://api.faireplace.com/api

/coupons/redeem

Redeems a free_signature coupon, converting the granted signatures into credits added to the tenant's balance.

Important

Only free_signature coupons can be redeemed here. discount coupons must be applied directly at signature checkout and are rejected with 400.
Redemption is idempotent: a tenant can redeem a given coupon only once (unique constraint on coupon + tenant). A repeat attempt returns 409.

Usage Example

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

Response:


Code
{
  "code": "PROMO2024",
  "kind": "free_signature",
  "signatures_count": 2,
  "new_balance_cents": 150000,
  "message": "2 signature(s) offerte(s) ajoutée(s) à votre solde"
}

Redeem a coupon › Request Body

Request to redeem a coupon. Only `free_signature` coupons can be redeemed here; `discount` coupons must be applied directly at checkout.

RedeemCouponRequest

code

string · minLength: 1 · maxLength: 64 · required

Coupon code to redeem.

Example: PROMO2024

Redeem a coupon › Responses

Coupon redeemed; credits added to the balance.

Result of redeeming a `free_signature` coupon. The corresponding credit value is added to the tenant's credit balance.

RedeemCouponResponse

code

string · required

Coupon code.

Example: PROMO2024

kind

string · enum · required

Always free_signature for a redeemable coupon.

Enum values:

free_signature

Example: free_signature

signatures_count

integer · int32 · required

Number of free signatures granted by this redemption.

Example: 2

new_balance_cents

integer · int64 · required

New credit balance in euro cents after the redemption.

Example: 150000

message

string · required

User-friendly confirmation message.

Example: 2 signature(s) offerte(s) ajoutée(s) à votre solde

Countries Usage