---
title: "Redeem a coupon"
method: POST
path: "/coupons/redeem"
tags: ["Coupons"]
---

# Redeem a coupon

`POST /coupons/redeem`

## Request

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

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

```bash
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**:
```json
{
  "code": "PROMO2024",
  "kind": "free_signature",
  "signatures_count": 2,
  "new_balance_cents": 150000,
  "message": "2 signature(s) offerte(s) ajoutée(s) à votre solde"
}
```

## Request body

- RedeemCouponRequest: Request to redeem a coupon. Only `free_signature` coupons can be redeemed here; `discount` coupons must be applied directly at checkout.
  - `code` string, required: Coupon code to redeem.

## Response `200`

Coupon redeemed; credits added to the balance.

- RedeemCouponResponse: Result of redeeming a `free_signature` coupon. The corresponding credit value is added to the tenant's credit balance.
  - `code` string, required: Coupon code.
  - `kind` 'free_signature', required: Always `free_signature` for a redeemable coupon.
  - `signatures_count` integer, required: Number of free signatures granted by this redemption.
  - `new_balance_cents` integer, required: New credit balance in euro cents after the redemption.
  - `message` string, required: User-friendly confirmation message.

## Other responses

- `400`: Invalid request. Possible causes: invalid code format, the coupon is a `discount` coupon (use it at checkout instead), the coupon is inactive, expired, or saturated (max redemptions reached).
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Coupon code not found.
- `409`: The coupon has already been redeemed by this tenant.
- `422`: Unprocessable Entity
- `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)