---
feature: Create course: venue, link, preview, discount, learning points, threshold start
slug: course-create
surface: trainer
consumer: flutter
version: 0.2.0
status: in-progress
brd_version: "v1.0 (11-8-2026) + additional requirements"
brd_ids: [TRR-009, TRR-010, TRR-011, TRR-012]
business_rules: [BR-CRS-01]
decisions: [D1, D3, DEC-17, TD-23, TD-25]
schema_tables: [courses, course_translations]
related_docs: [subscriptions.md, hall-bookings.md]
last_updated: 2026-11-15
---

# Create course: venue, link, preview, discount, learning points, threshold start — Trainer App Integration Guide

> **Base URL:** `{HOST}/api/v1/trainer` · Shared rules: [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Quick reference

| | |
|---|---|
| Version | 0.2.0 (2026-11-15) — drafts, validation, threshold scheduling and submit; **not built yet:** discount (TRR-013), learning points (TRR-014) |
| Status | in-progress · BRD TRR-009..012 · D1 (venue typed, no hall link), D3 (affiliated price is a proposal), DEC-17 |
| Auth | Trainer Bearer token, account `active`. |

| Method | Path | Route name | Purpose |
|--------|------|------------|---------|
| `GET` | `/courses` | `trainer.courses.index` | Own courses (`?status=`, `?per_page=`) |
| `POST` | `/courses` | `trainer.courses.store` | Create a draft |
| `GET` | `/courses/{course}` | `trainer.courses.show` | One course (own only, else 404) |
| `PUT` | `/courses/{course}` | `trainer.courses.update` | Edit a draft or rejected course |
| `POST` | `/courses/{course}/submit` | `trainer.courses.submit` | Send for review (independent trainers) |

**Statuses:** `draft` → `under_review` (submit) → `published` / `rejected` (admin) → `rejected` is edited and resubmitted. Published substantive edits are submitted for review while the live version remains available.
**Error codes:** `BUSINESS_RULE_VIOLATED` (422: validation rules, missing data at submit, no / expired / used-up package, affiliated trainer) · `COURSE_MINIMUM_ABOVE_SEATS` (422: threshold minimum above seats) · `INVALID_STATE_TRANSITION` (422). Published-course edit codes are in [courses.md](courses.md).
**Open decisions:** DEC-10 and DEC-11 assumptions are documented in [courses.md](courses.md).

## 1. Business summary

An active trainer creates a course draft with title, description, category, city, date, start time, duration, free toggle, price, seats and type. An in-person course also carries the venue typed by hand (name, address, map link, notes; no hall link, D1); an external course carries its access link and instructions, which only the owner sees here and which never appear in public details. Submitting needs the required data complete and, for an independent trainer, a usable business model: commission, or an unexpired package with courses left ([subscriptions.md](subscriptions.md)). The trainer never publishes directly. An affiliated trainer's course belongs to the center and the price entered is stored as `proposed_price`; the center submits it (center surface, not built), so `can_submit` is `false` for them.

## 2. Endpoints

### 2.1 Create / edit — `POST /courses`, `PUT /courses/{course}`

| Field | Required on create | Validation |
|-------|--------------------|-----------|
| `type` | yes | `in_person` · `external` |
| `category_id`, `city_id` | yes | uuid of an active category / city |
| `name`, `description` | yes | string (max 255 / 10000); stored once for every language (TD-23) |
| `images` | no | ≤ 5 media hashes |
| `start_mode` | no | `fixed_date` (default) or `threshold` |
| `min_enrollments`, `minimum_deadline_on` | for threshold | integer ≥ 1 and ≤ seats; deadline Y-m-d after today |
| `expected_duration` | no | nullable string, max 50 |
| `starts_on` | for fixed date | `Y-m-d`, not in the past |
| `start_time` | for fixed date | `H:i` |
| `duration_minutes` | for fixed date | 15–1440; the end is derived (can pass midnight) |
| `is_free` | yes | boolean |
| `price` | unless free | > 0, 2 decimals; must be empty / 0 when free |
| `seats` | yes | integer ≥ 1 |
| `sessions_count` | no | 1–365, information only |
| `external_link` | when `external` | URL |
| `access_instructions` | no | text |
| `venue_name`, `venue_address`, `venue_map_url`, `venue_notes` | no (needed to submit an in-person course) | |

Edit accepts any subset; rules that depend on the saved draft are re-checked on the merged state. Changing the type clears the group that no longer applies.

```json
{"status":"success","message":"Created successfully","data":{"id":"a33b5bea-5c2b-4132-8dec-549399ddd2c8","code":"K0VH8OO0MKV3XQ2GR7LM","status":{"value":"draft","label":"مسودة"},"type":{"value":"in_person","label":"حضوري"},"name":"Laravel for beginners","description":"A practical introduction","images":["https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"],"category":{"id":"a33b5bea-4e03-44e4-adf3-3ffa27c1484d","name":"تصنيف 151648"},"city":{"id":"a33b5bea-4fc3-46ca-a3eb-1d3584c41a83","name":"مدينة 969145"},"is_free":false,"price":"350.00","proposed_price":null,"seats":25,"confirmed_count":0,"remaining_seats":25,"start_mode":{"value":"fixed_date","label":"موعد محدد"},"min_enrollments":null,"minimum_reached_at":null,"minimum_progress":null,"threshold":null,"sessions_count":1,"starts_on":"2026-11-25","start_time":"18:30","duration_minutes":150,"ends_at":"2026-11-25T21:00:00+00:00","external_link":null,"session_link":null,"access_instructions":null,"venue":{"name":"Riyadh Hall","address":"King Fahd Road","map_url":null,"notes":null},"rejection_reason":null,"points":null,"submitted_at":null,"can_view":true,"can_view_enrollments":false,"can_edit":true,"can_submit":true,"can_resubmit":false,"can_request_edit":false,"can_update_session_link":false,"can_set_date":false,"can_complete":false,"can_cancel_request":false,"can_view_enrollees":false,"can_view_reason":false,"created_at":"2026-11-15T14:36:44+00:00"}}
```

### 2.2 Submit — `POST /courses/{course}/submit`

```json
{"status":"success","message":"Your course has been submitted for review.","data":{"id":"a33b5bea-724c-4bf5-b9f2-4214f48565ea","code":"VVEUKTJ5KQNXQW7TURA4","status":{"value":"under_review","label":"قيد المراجعة"},"type":{"value":"in_person","label":"حضوري"},"name":"Laravel for beginners","description":"A practical introduction","images":["https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"],"category":{"id":"a33b5bea-6d7e-4fdf-904c-fffbf8d1c9ae","name":"تصنيف 664149"},"city":{"id":"a33b5bea-6eea-4ebc-9e4b-4d6c974f78e8","name":"مدينة 635461"},"is_free":false,"price":"350.00","proposed_price":null,"seats":25,"confirmed_count":0,"remaining_seats":25,"start_mode":{"value":"fixed_date","label":"موعد محدد"},"min_enrollments":null,"minimum_reached_at":null,"minimum_progress":null,"threshold":null,"sessions_count":1,"starts_on":"2026-11-25","start_time":"18:30","duration_minutes":150,"ends_at":"2026-11-25T21:00:00+00:00","external_link":null,"session_link":null,"access_instructions":null,"venue":{"name":"Riyadh Hall","address":"King Fahd Road","map_url":null,"notes":null},"rejection_reason":null,"points":null,"submitted_at":"2026-11-15T14:36:44+00:00","can_view":true,"can_view_enrollments":false,"can_edit":false,"can_submit":false,"can_resubmit":false,"can_request_edit":false,"can_update_session_link":false,"can_set_date":false,"can_complete":false,"can_cancel_request":false,"can_view_enrollees":false,"can_view_reason":false,"created_at":"2026-11-15T14:36:44+00:00"}}
```

Submitting a course that is no longer a draft:

```json
{"status":"error","message":"This course cannot be submitted in its current status.","data":{"error_code":"INVALID_STATE_TRANSITION","correlation_id":"037176c6-9282-4d74-bd95-e3cb0b227930"}}
```

## 3. Business rules enforced

| Rule | Behaviour |
|------|-----------|
| TRR-009 | Only an active trainer; free → no price; seats > 0; date not in the past. |
| TRR-006 | Allowance counted at submit under the subscription row lock, so two submits cannot share the last slot; an expired package blocks submission and keeps existing courses. |
| TRR-012 | Every course is reviewed; required data must be complete (`BUSINESS_RULE_VIOLATED` names the missing items). |
| D3 | Affiliated trainer: `training_center_id` set, price is `proposed_price`, no submit. |

## 4. Known limitations

- Published edit requests are available and the admin reviews them ([admin/courses.md](../admin/courses.md)). See [courses.md](courses.md).
- Discount and learning points are not built. Threshold starts accept `min_enrollments` and `minimum_deadline_on`; the minimum cannot exceed seats.

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 0.2.0 | 2026-11-15 | MINOR | Threshold scheduling and current response fields. | Integrate threshold inputs. |
| 0.1.0 | 2026-11-15 | Initial (partial) | Draft create / edit, validation, submit with plan enforcement. | Build create / edit / submit. |

## Changelog

### 0.2.0 — 2026-11-15
- Added threshold scheduling inputs and updated real responses; integrate threshold fields.

### 0.1.0 — 2026-11-15
- **Added:** `courses` CRUD without delete, `courses/{id}/submit`; `CourseDetailsAreValid`, `CourseIsReadyForReview`, `TrainerHasCourseAllowance`.
- **Breaking:** No
- **App action required:** Build create / edit / submit.
- **BRD / decisions:** TRR-009..012, D1, D3, TD-25
