GuidesAPI ReferenceMCPChangelog
Shared

Create a promotion: an automatic sale or a promo code (admin, or manage_org_settings)

post/api/marketing/promotions

One route for both kinds (migration 0163): an automatic "sale" discounts the public appointments booking page with no code, a "code" is typed by the guest at checkout. Appointments only: reservations (hospitality) carry no priced total to discount. A "code" with no explicit code field generates one from name (src/lib/marketing/promotions/codes.ts), retrying up to 3 times on the rare per-company collision; an EXPLICIT code that collides is refused (409) rather than silently regenerated, since that collision is the venue's own typo to fix. Revalidates the public booking page cache (bookingConfigTag) on a 'sale' so the struck-through price appears without waiting the full 5-minute window.

Authorization

sessionCookie
sb-qxrvgfkjyvbngipqvslu-auth-token<token>

The dashboard's Supabase Auth session cookie, set at sign-in. Large sessions are split across numbered chunks (…auth-token.0, .1), so treat this as a cookie family rather than one name.

Every request re-validates it against the Auth server (getUser()), never by decoding the cookie locally: a JWT nothing has checked is not a credential. Tenancy is then read from the verified app_metadata.company_id claim and enforced by row-level security; it is never read from request input, on any route, ever.

role (admin / staff) is deliberately not in RLS. It gates specific actions in route code, the operations marked admin below, so hiding a button in the UI is cosmetic only, and a route's own check is the enforcement.

In: cookie

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/marketing/promotions" \  -H "Content-Type: application/json" \  -d '{    "kind": "sale",    "name": "string",    "discountType": "percent"  }'
{  "promotion": {}}

Resolve a gift card code to its id and balance GET

The lookup half of the redeem flow (2026-08-30, added alongside CloseOutDialog's GiftCardRedeemField): a staff member types a code, this resolves it to the card, and the redeem route above takes the id. Case/whitespace-insensitive. Scoped to the caller's own company: a code is unique per company, not globally (book_gift_cards_company_code, migration 0162), exactly because redemption always happens inside a company's own dashboard.

Enable or disable a promotion (admin, or manage_org_settings) PATCH

The one lifecycle action this v1 dashboard exposes: no delete, no field edits after creation. Revalidates the public booking page cache the same way POST does, so a disabled sale stops showing immediately rather than lagging the 5-minute window.