Promo-codes API

Auto-generated from the OpenAPI spec. Run node docs-site/scripts/fetch-openapi.js to regenerate.

GET /api/v1/promo-codes

List Promo Codes

List all promo codes. 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 promo codes. true shows only removed promo codes (the "Removed" tab), regardless of active_only.
page	query	No	integer
page_size	query	No	integer

Responses

• 200 — Successful Response
• 422 — Validation Error

---

POST /api/v1/promo-codes

Create Promo Code

Create a new promo code. Manager-only.

Request body

Field	Required	Type	Description
code	Yes	string
discount_type	Yes	string
discount_value	Yes	number
applicable_membership_type_ids	No	array
max_uses	No	integer
one_per_client	No	boolean
valid_from	Yes	string
valid_until	No	string
is_active	No	boolean

Responses

• 201 — Successful Response
• 422 — Validation Error

---

GET /api/v1/promo-codes/{promo_code_id}

Get Promo Code

Get a promo code by ID. Manager-only.

Parameters

Name	In	Required	Type	Description
promo_code_id	path	Yes	integer

Responses

• 200 — Successful Response
• 422 — Validation Error

---

PUT /api/v1/promo-codes/{promo_code_id}

Update Promo Code

Update a promo code. Manager-only.

Parameters

Name	In	Required	Type	Description
promo_code_id	path	Yes	integer

Request body

Field	Required	Type	Description
code	No	string
discount_type	No	string
discount_value	No	number
applicable_membership_type_ids	No	array
max_uses	No	integer
one_per_client	No	boolean
valid_from	No	string
valid_until	No	string
is_active	No	boolean

Responses

• 200 — Successful Response
• 422 — Validation Error

---

DELETE /api/v1/promo-codes/{promo_code_id}

Deactivate Promo Code

Deactivate a promo code (set is_active=False). Manager-only.

Parameters

Name	In	Required	Type	Description
promo_code_id	path	Yes	integer

Responses

• 200 — Successful Response
• 422 — Validation Error

---

DELETE /api/v1/promo-codes/{promo_code_id}/remove

Remove Promo Code

Soft-delete a promo code. Never blocked by historical usage/orders.

Removed codes are hidden from the default/active list but remain in the DB (visible via GET ?removed=true) and can be restored via PATCH /restore. Existing PromoCodeUsage/order rows referencing this code keep resolving correctly forever, since the row is never deleted.

Parameters

Name	In	Required	Type	Description
promo_code_id	path	Yes	integer

Responses

• 204 — Successful Response
• 404 PROMO_CODE_NOT_FOUND — Promo code not found.
• 409 PROMO_CODE_ALREADY_REMOVED — This promo code has already been removed.
• 422 — Validation Error

---

PATCH /api/v1/promo-codes/{promo_code_id}/restore

Restore Promo Code

Clears removed_at, moving the promo code back out of the "Removed" tab and into the normal active/inactive lists.

Parameters

Name	In	Required	Type	Description
promo_code_id	path	Yes	integer

Responses

• 200 — Successful Response
• 404 PROMO_CODE_NOT_FOUND — Promo code not found.
• 409 PROMO_CODE_NOT_REMOVED — This promo code has not been removed.
• 422 — Validation Error

---

POST /api/v1/promo-codes/validate

Validate Promo Code Endpoint

Validate a promo code and return discount info. Does NOT record usage.

Accessible by authenticated clients and managers.

Request body

Field	Required	Type	Description
code	Yes	string
membership_type_id	Yes	integer

Responses

• 200 — Successful Response
• 422 — Validation Error

---