---
title: "Validate a coupon"
method: POST
path: "/coupons/validate"
tags: ["Coupons"]
---

# Validate a coupon

`POST /coupons/validate`

## Request

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

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

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

## Request body

- ValidateCouponRequest: Request to preview a coupon without consuming it.
  - `code` string, required: Coupon code to validate (case as provided by the user).

## Response `200`

Coupon preview.

- ValidateCouponResponse: Preview of a coupon. This endpoint does NOT consume the coupon; it only reports whether it can be redeemed by the current tenant.
  - `code` string, 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.
  - `description` string, nullable: Optional human-readable description of the coupon.
  - `signatures_count` integer: Number of free signatures granted by the coupon. Only present when `kind` is `free_signature` (omitted otherwise).
  - `discount_will_apply` boolean, required: `true` when `kind` is `discount`, meaning a Stripe discount will be applied automatically at signature checkout.
  - `already_redeemed` boolean, required: Whether the current tenant has already redeemed this coupon.
  - `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.

## Other responses

- `400`: Invalid coupon code (length 1-64 required).
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Coupon code not found.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/faireplace/apis/faireplace-property-management-api.md) · [All operations](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faireplace/apis/faireplace-property-management-api/revisions/69de39762919?raw)