Gift-cards API
Auto-generated from the OpenAPI spec. Run
node docs-site/scripts/fetch-openapi.jsto regenerate.
POST /api/v1/gift-cards
Issue Gift Card
Manually issue a gift card (e.g. for phone/in-person sales). Manager-only.
Request body
| Field | Required | Type | Description |
|---|---|---|---|
initial_value | Yes | number | |
recipient_name | No | string | |
recipient_email | No | string | |
message | No | string | |
expires_at | No | string |
Responses
- 201 — Successful Response
- 422 — Validation Error
GET /api/v1/gift-cards
List Gift Cards
List all gift cards. Manager-only.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
active_only | query | No | boolean | |
status | query | No | "active" | "inactive" | "all". Takes precedence over active_only when provided — "inactive" is evaluated fully server-side, so the response's total/pagination reflect the filtered count rather than the broad set. Omit to keep today's active_only-only behavior. | |
removed | query | No | boolean | Default false excludes removed gift cards. true shows only removed gift cards (the "Removed" tab), regardless of active_only. |
page | query | No | integer | |
page_size | query | No | integer |
Responses
- 200 — Successful Response
- 422 — Validation Error
GET /api/v1/gift-cards/{gift_card_id}
Get Gift Card
Get a gift card by ID. Manager-only.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
gift_card_id | path | Yes | integer |
Responses
- 200 — Successful Response
- 422 — Validation Error
PUT /api/v1/gift-cards/{gift_card_id}
Update Gift Card
Update a gift card. Manager-only.
Deliberately minimal — today the only editable field is is_active, so
this is primarily the reactivate path (mirrors the generic-PUT-accepts-
is_active convention used by locations/class_templates/membership_types/
products/promo_codes/waivers/staff-pay-components in this codebase,
rather than a dedicated reactivate route). initial_value and
remaining_balance are intentionally NOT editable here — those go
through the dedicated redemption/purchase logic in
app/services/gift_card_service.py.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
gift_card_id | path | Yes | integer |
Request body
| Field | Required | Type | Description |
|---|---|---|---|
is_active | No | boolean |
Responses
- 200 — Successful Response
- 422 — Validation Error
DELETE /api/v1/gift-cards/{gift_card_id}
Deactivate Gift Card
Deactivate a gift card (set is_active=False). Manager-only.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
gift_card_id | path | Yes | integer |
Responses
- 200 — Successful Response
- 422 — Validation Error
DELETE /api/v1/gift-cards/{gift_card_id}/remove
Remove Gift Card
Soft-delete a gift card. Manager-only.
Never blocked on historical references — past GiftCardRedemption rows
(and any Payment that recorded this card's code) keep resolving fine
since the row is never actually deleted, only hidden from the
default/active list. Removed cards are hidden from the default/active
list but remain in the DB (visible via GET /gift-cards?removed=true)
and can be restored via PATCH /restore.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
gift_card_id | path | Yes | integer |
Responses
- 204 — Successful Response
- 404
GIFT_CARD_NOT_FOUND— Gift card not found. - 409
GIFT_CARD_ALREADY_REMOVED— This gift card has already been removed. - 422 — Validation Error
PATCH /api/v1/gift-cards/{gift_card_id}/restore
Restore Gift Card
Restore a previously-removed gift card. Manager-only.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
gift_card_id | path | Yes | integer |
Responses
- 200 — Successful Response
- 404
GIFT_CARD_NOT_FOUND— Gift card not found. - 409
GIFT_CARD_NOT_REMOVED— This gift card has not been removed. - 422 — Validation Error
POST /api/v1/gift-cards/validate
Validate Gift Card Endpoint
Validate a gift card code and return its remaining balance.
Does NOT redeem/deduct anything — read-only check. Accessible by authenticated clients and managers (codes are not client-scoped, so no ownership check is required beyond authentication).
Request body
| Field | Required | Type | Description |
|---|---|---|---|
code | Yes | string |
Responses
- 200 — Successful Response
- 422 — Validation Error
POST /api/v1/gift-cards/checkout-session
Create Gift Card Checkout Session
Create a Stripe Checkout Session for a client to purchase a gift card as a present for someone else.
A client purchases using their own account (their JWT sub becomes
purchaser_client_id). A manager purchasing does not have a membership
of their own to attribute the purchase to, so purchaser_client_id is
left null in that case.
This is a separate, one-off (mode="payment") Checkout Session flow — it does not reuse or overload the membership checkout-session endpoint.
Request body
| Field | Required | Type | Description |
|---|---|---|---|
amount | Yes | number | |
recipient_name | No | string | |
recipient_email | No | string | |
message | No | string | |
success_url | Yes | string | |
cancel_url | Yes | string |
Responses
- 200 — Successful Response
- 422 — Validation Error