Coupon

[samkiell]

new feature alert

[samkiell]

so the frontend will be needing these endpoints from the backend yall

POST /events/{event_id}/coupons/ - Create coupon for event
GET /events/{event_id}/coupons/ - List coupons for event (organizer)
DELETE /coupons/{coupon_code}/ - Delete/deactivate coupon
POST /coupons/validate/ - Validate a coupon code
Body: { coupon_code, event_id, ticket_items }
Response: { valid, discount_type, discount_value, discounted_total }

@Danieee27

[samkiell]

Tasks for Frontend guys

Coupon Feature — Task Distribution

Samkiel: Architecture, organizer-side coupon setup (event create/edit), API contract definition
Tobi: Checkout integration — coupon input, validation UI, discount application logic
Abraham: Coupon display states, small UI components (badge, success/error states)

---

API Contract the frontend needs from the Backend

POST /events/{event_id}/coupons/         - Create coupon for event
GET  /events/{event_id}/coupons/         - List coupons for event (organizer)
DELETE /coupons/{coupon_code}/           - Delete/deactivate coupon
POST /coupons/validate/                  - Validate a coupon code
  Body: { coupon_code, event_id, ticket_items }
  Response: { valid, discount_type, discount_value, discounted_total, original_total, savings, message }

---

SAMKIEL

Organizer Coupon Setup in Event Create/Edit

You are implementing the Coupon Setup feature for the Axile Event Platform 
organizer frontend.

CONTEXT:
- Framework: Next.js App Router (v16), JavaScript 
- Styling: Tailwind CSS, shadcn/ui
- Forms: react-hook-form
- API calls: Axios via existing lib/api/client.js
- Event creation uses multipart/form-data (FormData)
- State: Zustand + TanStack Query
- Notifications: react-hot-toast
- Brand primary color: #e11d48

TASK:
Add a Coupon section to the event creation form and the event edit form.
This section appears below the existing form fields.

COUPON FIELDS:
- enable_coupon: boolean toggle (default: false)
- When enabled, show:
  - discount_type: "percentage" | "flat" — radio or select
  - discount_value: number input
    - If percentage: 1–100, show % symbol
    - If flat: positive number, show ₦ symbol
  - coupon_code: text input + "Generate Code" ghost button that produces
    a random 6–8 char uppercase alphanumeric string
  - usage_limit: number input, optional (null = unlimited)
  - expiry_date: date picker, optional

FILES TO CREATE:
- src/components/events/coupon-setup.jsx
- src/lib/utils/coupon.js          ← generateCouponCode() utility
- src/lib/api/coupons.js           ← all coupon API stubs

COUPON API STUBS (src/lib/api/coupons.js):
All functions are stubbed — backend is not ready yet.

import apiClient from "./client";

export const createEventCoupon = async (eventId, data) => {
  // POST /events/{event_id}/coupons/
  // data: { discount_type, discount_value, coupon_code, usage_limit, expiry_date }
  // TODO: implement when backend is ready
  throw new Error("Not implemented");
};

export const getEventCoupons = async (eventId) => {
  // GET /events/{event_id}/coupons/
  // Returns: array of coupon objects
  throw new Error("Not implemented");
};

export const deleteCoupon = async (couponCode) => {
  // DELETE /coupons/{coupon_code}/
  throw new Error("Not implemented");
};

GENERATE UTILITY (src/lib/utils/coupon.js):
export function generateCouponCode(length = 7) {
  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
  let result = "";
  for (let i = 0; i < length; i++) {
    result += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return result;
}

COUPONSETUP COMPONENT (src/components/events/coupon-setup.jsx):
Props:
- control — react-hook-form control object
- watch — react-hook-form watch function
- setValue — react-hook-form setValue function
- existingCoupons — array of coupon objects (for edit page), default []
- onDeleteCoupon — function(couponCode) called when organizer deletes 
  an existing coupon

Behavior:
- Use shadcn Switch for the enable_coupon toggle
- When enable_coupon is false, hide all other coupon fields
- "Generate Code" button calls generateCouponCode() and sets the 
  coupon_code field via setValue
- Show a live preview line when all required fields are filled:
  e.g. "Buyers get 20% off with code SAVE20"
  or   "Buyers get ₦500 off with code FLAT50"
- On edit page, if existingCoupons has items, render them in a small 
  list above the new coupon form. Each item shows:
  - The coupon code (monospace)
  - Discount summary (e.g. "20% off")
  - A delete icon button that calls onDeleteCoupon(coupon.coupon_code)
- Validation (register with required rules):
  - discount_value: required if enable_coupon is true, must be > 0
  - coupon_code: required if enable_coupon is true

UI:
- Section title: "Coupon / Discount" with Tag icon from lucide-react
- Use shadcn Card or a bordered div to wrap the section
- Keep the UI consistent with the rest of the event form styling

INTEGRATION IN EVENT CREATE/EDIT PAGE:
- Import CouponSetup and place it below existing form sections
- After the event is created/updated successfully, if enable_coupon is true:
  - Call createEventCoupon(eventId, couponData) in a try/catch
  - On success: toast.success("Coupon created successfully")
  - On failure: toast.error("Event saved, but coupon setup failed. 
    Please try again from the edit page.")
  - Do NOT fail the entire form submit if coupon creation fails
- Coupon fields should NOT be appended to FormData — they are sent in 
  a separate JSON POST after the event save

Do not implement the checkout side — that is Tobi's task.
Write clean JavaScript (JSX). Named exports only.

---

TOBI

Checkout Coupon Input & Discount Application

You are implementing the coupon/discount feature on the ticket checkout 
flow for the Axile Event Platform frontend.

CONTEXT:
- Framework: Next.js App Router (v16), JavaScript
- Styling: Tailwind CSS, shadcn/ui
- Booking API: POST /tickets/book/
- Current payload: { event_id, items: [{ category_name, quantity }] }
- Updated payload adds: coupon_code (optional string)
- State: Zustand + TanStack Query
- Notifications: react-hot-toast
- Brand primary: #e11d48

VALIDATE COUPON API (src/lib/api/coupons.js):
This file is created by the lead — do not recreate it.
Add only this export to it (coordinate with lead):

export const validateCoupon = async (couponCode, eventId, items) => {
  // POST /coupons/validate/
  // Body: { coupon_code: couponCode, event_id: eventId, ticket_items: items }
  // Response: { valid, discount_type, discount_value, original_total,
  //             discounted_total, savings, message }
  const response = await apiClient.post("/coupons/validate/", {
    coupon_code: couponCode,
    event_id: eventId,
    ticket_items: items,
  });
  return response.data;
};

FILES TO CREATE:
- src/components/checkout/coupon-input.jsx

COUPONINPUT COMPONENT SPEC:
Props:
- eventId (string)
- items (array of { category_name, quantity })
- onCouponApplied(result, code) — called when coupon is valid and applied
- onCouponRemoved() — called when user removes applied coupon
- disabled (boolean, optional) — disables input during booking submission

Internal state:
- inputValue — the typed coupon code string
- isLoading — true while validateCoupon is in flight
- error — string or null
- appliedResult — the validation response object or null

Behavior:
- Text input + "Apply" button side by side
- On "Apply" click:
  - Trim and uppercase the inputValue
  - If empty, set error "Please enter a coupon code" and return
  - Set isLoading true, clear previous error
  - Call validateCoupon(code, eventId, items)
  - On success where valid is true:
    - Set appliedResult to the response
    - Call onCouponApplied(result, code)
    - Clear error
  - On success where valid is false:
    - Set error to result.message or "Invalid or expired coupon code"
  - On API error (catch block):
    - Set error "Something went wrong. Please try again."
  - Always set isLoading false after
- When appliedResult is set (coupon applied state):
  - Input becomes readonly (disabled)
  - "Apply" button is hidden
  - Show a "Remove" text button that:
    - Clears appliedResult, inputValue, error
    - Calls onCouponRemoved()
- Loading state: disable input and button, show Loader2 spinning icon 
  inside button (lucide-react)

UI when coupon is applied (success state):
- Green CheckCircle icon + "Coupon applied!" text in green
- This is a simple inline message — the full savings breakdown is 
  rendered in the parent checkout page, not inside this component

UI when error:
- Inline red text below the input, XCircle icon (lucide-react)

CHECKOUT PAGE INTEGRATION:
In the existing booking/checkout page:

1. Import CouponInput and SavingsCallout (from Abraham's components)

2. Only show CouponInput if event pricing_type is "paid"

3. Manage coupon state in the checkout page:
   const [appliedCoupon, setAppliedCoupon] = useState(null);
   // appliedCoupon shape: { code: string, result: validationResponse }

4. Pass handlers:
   onCouponApplied={(result, code) => setAppliedCoupon({ code, result })}
   onCouponRemoved={() => setAppliedCoupon(null)}

5. Order summary display — below ticket selections, above the CTA button:

   Without coupon:
     Total: ₦10,000

   With coupon applied:
     Subtotal:           ₦10,000
     Discount (20% off): -₦2,000    ← text-green-600
     ─────────────────────────────
     Total:              ₦8,000
   
   Use the SavingsCallout component from Abraham for the green 
   savings highlight box.

6. On booking submit:
   - If appliedCoupon is set, add coupon_code: appliedCoupon.code 
     to the booking payload
   - If booking API returns an error mentioning the coupon, show:
     toast.error("Coupon could not be applied. Booking placed 
     without discount.")
   - After successful booking, clear appliedCoupon

EDGE CASES:
- If discounted_total === 0 (100% off), display "Free" instead of ₦0
- Do not auto-validate on keystroke — only on explicit "Apply" click
- disabled prop should disable both the input and button (during 
  booking submission in progress)

Write clean JavaScript JSX. Named export for CouponInput.
Use cn() from src/lib/utils/cn.js for conditional classes.
No inline styles.

---

ABRAHAM

Coupon UI Components — Badges & Display States

You are building small display components for the Coupon feature on 
the Axile Event Platform frontend.

CONTEXT:
- Framework: Next.js App Router (v16), JavaScript
- Styling: Tailwind CSS, shadcn/ui
- Icons: lucide-react
- Use cn() from src/lib/utils/cn.js for conditional classes
- Brand primary: #e11d48
- No API calls. No Zustand. No router. Pure UI components only.

FILES TO CREATE:
1. src/components/coupon/coupon-badge.jsx
2. src/components/coupon/coupon-status-badge.jsx
3. src/components/coupon/savings-callout.jsx
4. src/components/coupon/coupon-code-display.jsx

────────────────────────────────────────────
1. CouponBadge
────────────────────────────────────────────
Purpose: Small pill shown on event cards/detail pages to indicate 
a coupon discount is available for that event.

Props:
- discountType: "percentage" | "flat"
- discountValue: number
- className: string (optional)

Display logic:
- discountType "percentage" + discountValue 20 → "20% OFF"
- discountType "flat" + discountValue 500      → "₦500 OFF"

UI:
- Tag icon (lucide-react) on the left, small size (14px)
- Background: #e11d48, text white
- text-xs, font-semibold, px-2 py-0.5, rounded-full
- Named export: export function CouponBadge({ discountType, 
  discountValue, className })

────────────────────────────────────────────
2. CouponStatusBadge
────────────────────────────────────────────
Purpose: Shows the status of a coupon in the organizer's coupon list.

Props:
- isActive: boolean
- timesUsed: number
- usageLimit: number or null (optional)
- expiryDate: string or null (optional, ISO date string)

Status logic (check in this order):
1. isActive is false → "Inactive" — gray
2. expiryDate is set and is in the past → "Expired" — red
3. usageLimit is set and timesUsed >= usageLimit → "Limit Reached" — orange
4. Otherwise → "Active" — green

UI:
- Small colored circle dot + status text
- Use only Tailwind color utilities:
  Active:        text-green-600, bg-green-50, border-green-200
  Expired:       text-red-600,   bg-red-50,   border-red-200
  Inactive:      text-gray-500,  bg-gray-50,  border-gray-200
  Limit Reached: text-orange-600, bg-orange-50, border-orange-200
- border rounded-full px-2 py-0.5 text-xs font-medium
- Named export: export function CouponStatusBadge({ isActive, 
  timesUsed, usageLimit, expiryDate })

────────────────────────────────────────────
3. SavingsCallout
────────────────────────────────────────────
Purpose: A highlighted box in checkout showing savings after a 
coupon is applied. Rendered by the checkout page, used alongside 
the order summary.

Props:
- originalTotal: number
- discountedTotal: number
- savings: number
- couponCode: string

UI:
- Wrapper: bg-green-50 border border-green-200 rounded-lg p-3
- First line: CheckCircle icon (green, 16px) + 
  "Coupon '{couponCode}' applied!"  in text-green-700 font-medium
- Second line (text-sm text-green-600):
  "You're saving ₦{savings.toLocaleString()} on this order"
- All naira amounts formatted with .toLocaleString()
- Named export: export function SavingsCallout({ originalTotal, 
  discountedTotal, savings, couponCode })

────────────────────────────────────────────
4. CouponCodeDisplay
────────────────────────────────────────────
Purpose: Displays a coupon code in a styled box with copy-to-clipboard.
Used in the organizer's event management/edit page coupon list.

Props:
- code: string
- onCopy: function (optional, called after copy)

Local state:
- copied: boolean (useState, default false)

Behavior:
- On copy button click:
  - navigator.clipboard.writeText(code)
  - Set copied to true
  - After 2000ms, set copied back to false (useEffect cleanup)
  - Call onCopy() if provided
- While copied is true: show Check icon instead of Copy icon

UI:
- Wrapper: flex items-center gap-2 bg-gray-50 border border-dashed 
  border-gray-300 rounded px-3 py-1.5 w-fit
- Code text: font-mono text-sm font-semibold text-gray-800 
  tracking-widest
- Copy button: ghost, icon only, p-1
  - Default: Copy icon from lucide-react (14px), text-gray-400
  - After copy: Check icon (14px), text-green-500
- Named export: export function CouponCodeDisplay({ code, onCopy })

────────────────────────────────────────────
RULES FOR ALL COMPONENTS:
- JavaScript JSX only — no TypeScript
- Named exports only, no default exports
- No API calls, no Zustand, no Next.js router
- No inline styles — Tailwind classes only
- Use cn() for any conditional class logic
- Each file gets a short comment at the top describing what it renders

ARIGATO

---

[Temiloluwagboyega]

Frontend guide: ticket coupons

This document describes how the ticket coupon feature behaves on the API so web/mobile clients can integrate organizers creating codes and attendees applying them at checkout.

Base URL prefix (same as the rest of the app):

/tickets/

Authentication uses Authorization: Bearer <access_token> unless noted otherwise.

---

Concepts

Concept	Meaning
Coupon	Belongs to one event. Optionally scoped to one ticket category; if omitted, it applies to all categories on that event.
Discount type	"fixed" = flat currency amount off the eligible subtotal; "percent" = percentage (0–100) off the eligible subtotal.
Eligible subtotal	Sum of line items that match the coupon (whole cart, or only the configured category).
One use per user	Each authenticated student can redeem a given coupon code at most once, counted when the booking is confirmed (paid or free completion path).
Pending checkout	While the student has pending tickets that reference this coupon, they cannot start another booking with the same coupon until those pending tickets are gone or confirmed (e.g. cleanup/expiry clears pending rows).

Important: Coupon checkout is implemented on student self-booking (POST /tickets/book/). Organizer “book for attendee” / bulk flows do not accept coupon_code yet.

---

Organizer: create a coupon

Endpoint: POST /tickets/organizer/coupons/
Auth: Organizer JWT (IsOrganizer).

Request body (JSON)

Field	Type	Required	Description
event_id	string	yes	Event id (same format as elsewhere, e.g. event:…).
discount_type	string	yes	"fixed" or "percent".
discount_value	number	yes	Decimal ≥ 0.01. For percent, must be ≤ 100.
category_id	string | null	no	Ticket category id for this event (e.g. category:…). Omit or empty for all categories.
starts_at	ISO 8601 datetime | null	no	Coupon valid from this instant (server timezone aware).
ends_at	ISO 8601 datetime | null	no	Coupon valid until this instant; must be after starts_at if both set.
max_redemptions	integer | null	no	Global cap across all users; omit for unlimited. Minimum 1 when sent.

Response — 201 Created

Returns a single coupon object (shape below). The code is generated server-side (event-name-style initials + - + 4 digits). Show this to the organizer so they can share it.

Example

POST /tickets/organizer/coupons/
{
  "event_id": "event:TE-12345",
  "discount_type": "percent",
  "discount_value": "15.00",
  "category_id": "category:ABC12-XYZ34"
}

---

Organizer: list coupons for an event

Endpoint: GET /tickets/organizer/coupons/?event_id=<event_id>
Auth: Organizer JWT.

Query parameters

Param	Required	Description
event_id	yes	Same event id string used elsewhere.

Response — 200 OK

{
  "coupons": [
    {
      "code": "TC-4821",
      "event_id": "event:TE-12345",
      "category_id": "category:ABC12-XYZ34",
      "discount_type": "percent",
      "discount_value": "15.00",
      "is_active": true,
      "starts_at": null,
      "ends_at": null,
      "max_redemptions": 100,
      "redemptions_count": 12,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "count": 1
}

Use redemptions_count / max_redemptions for organizer dashboards. There is no deactivate/update endpoint in this feature slice; only listing + create are exposed.

---

Student: apply coupon at checkout

Endpoint: POST /tickets/book/
Auth: Student JWT (same as normal booking).

Extra body field

Field	Type	Required	Description
coupon_code	string	no	Public code (case-insensitive on server). Omit or blank for normal booking.

Whitespace-only values are treated as “no coupon.”

Existing booking fields (unchanged)

• event_id (required)
• items: [{ "category_name": string, "quantity": number }]
• referral (optional)
• payment_method: "paystack" | "manual_bank_transfer" when the event allows multiple methods (same rules as before)

Success responses

Behavior matches existing booking, plus optional coupon metadata when a coupon was applied.

Coupon object (when present):

Field	Type	Meaning
code	string	Applied coupon code.
discount_amount	number	Discount applied to the eligible portion of the cart (base currency, before platform/Paystack fees).
subtotal_after_discount	number	Total ticket base subtotal for this booking after discount (sum of stored ticket line amounts).

Paid — Paystack (200 OK):

• Same as today: payment_url, payment_reference, tickets, booking_id, etc.
• Each ticket in tickets includes total_price already discounted per unit logic used server-side.
• Optional top-level coupon object as above.

Paid — manual bank transfer (201 Created):

• total_amount: amount the user must transfer (includes platform piece per existing rules; no Paystack fee).
• Optional coupon.

Free / zero total base (201 Created):

• Tickets created confirmed immediately when pricing_type is free or discounted base is 0.
• Server records coupon redemption in this path without Paystack.

Payment not configured (201 Created):

• Fallback payload includes base_ticket_price, total_amount, etc.; discounted base is reflected there when coupon applied.

Errors — 400 Bad Request

Typical shapes:

{ "error": "Invalid coupon code for this event." }

{ "error": "You have already used this coupon." }

Other messages cover expiry, inactive coupon, wrong event/category mix in cart, global max redemptions reached, pending booking conflict, validation failures on items, payment method rules, etc.

Serializer validation errors use DRF’s usual { "field": ["…"] } shape where applicable.

---

How pricing works for the UI

1. Authoritative totals after apply only exist after a successful POST /tickets/book/ (or you duplicate server rules client-side for estimates only).
2. tickets[].total_price in the booking response is the discounted per-ticket line used for payment aggregation (each row is quantity 1 in this API).
3. category_price on ticket serializers (if exposed in your client types) may still reflect the catalog category price from the related category; use total_price for “what this line costs in this booking.”
4. Fees: Final Paystack charge is computed server-side from the discounted ticket base plus platform/Paystack rules—do not assume fees are calculated on pre-discount list prices.

There is no dedicated “preview coupon” endpoint yet. Options:

• Call POST /tickets/book/ only when the user confirms (simplest).
• Or add a future POST /tickets/coupons/validate/ (not implemented) if product needs live preview without reserving inventory.

---

UX checklist

• Organizer: After create, show code, discount summary, optional category scope, and validity window.
• Checkout: Input for optional promo code; on submit include coupon_code; surface { error } from API clearly.
• Paid flow: Redirect/open payment_url as today; amount matches discounted totals.
• Already used: Expect clear error; disable re-entry for that code for that logged-in user.
• Mixed cart + category-scoped coupon: Discount applies only to matching categories; discount_amount describes savings on the eligible portion—avoid implying “X off entire cart” unless coupon is event-wide.

---

Quick reference

Action	Method & path
Create coupon	POST /tickets/organizer/coupons/
List coupons	GET /tickets/organizer/coupons/?event_id=…
Book with coupon	POST /tickets/book/ + coupon_code

---

Related backend modules

• Models: radar.ticket.models (TicketCoupon, CouponRedemption, Ticket.applied_coupon)
• Logic: radar.ticket.coupon_service
• Views: TicketBookingView, OrganizerTicketCouponListCreateView

@samkiell @LupoNetn @Abraham123-dev