Charter Contracts

Backoffice paths: Backoffice > Charter > Overview (/backoffice/charter/missions), Backoffice > Charter > Pilots (/backoffice/charter/pilots), and Backoffice > Charter > Customers (/backoffice/charter/customers)

Available to roles: System Administrator, Administrator; Operations Staff has full access

Overview

Charter contracts are multi-leg missions created by staff on behalf of charter customers. Each mission assigns a specific aircraft and route sequence, and pilots take the contract in one of two ways depending on its claiming mode: they apply and staff pick one (reviewed), or the first eligible pilot claims it instantly. The assigned pilot earns points upon successful completion, with a customer-specific multiplier applied to the base award. Failure to complete a contract results in penalty points and a temporary cooldown period.

The system also supports automatic mission generation from weighted route pools, aircraft repositioning through bounties, and customer branding with logos and banners.

---

Charter Customers

Charter customers represent the clients requesting charter operations. Manage customers at Backoffice > Charter > Customers.

The customer list is a card grid showing each customer's banner and logo, multiplier badge, monthly quota bar, aircraft and route counts, and an auto-generation indicator. The edit page is organised into cards: Profile, Entitlements, Fleet access (the aircraft pool), Routes (with weight steppers), Auto-generation, Flight numbers (with a live preview), and Branding.

Customer Fields

Field	Description
Name	The customer's name or company.
Logo	Customer logo image for display on missions.
Banner	Customer banner image for branding.
Description	A brief description of the customer.
Points Multiplier	Multiplier applied to base mission points (default: 1.00). A value of 2.00 doubles all point awards for this customer's missions.

Entitlements

Each customer can be given publishing caps. Leave any cap blank for unlimited.

Field	Description
Flights / Day	Maximum missions that can be published for this customer per day.
Flights / Month	Maximum missions that can be published per calendar month. Resets on the 1st.
Live at Once	Maximum missions simultaneously live on the board (Open, Assigned, or In Progress).

Both mission generation and publishing stop at the caps:

• Publishing a mission is refused with a message naming the exhausted cap. The mission builder shows the customer's quota, and its Review step only allows Save as draft when the quota is exhausted.
• Auto-generation pauses for the rest of the month once the monthly cap is reached.

The customer edit page shows a Used this month bar so staff can see the remaining quota at a glance, and pilots see the remaining quota on contract cards.

Flight Number Settings

Each customer can optionally have a flight number prefix configured. When set, all charter legs for that customer receive a branded flight number instead of the default CHR{id}-{sequence} format.

Field	Description
Flight Number Prefix	A short prefix (e.g. "65") prepended to each flight number. Leave blank to use the default format.
Total Digits	Total number of digits in the flight number including the prefix (default: 4). For example, prefix "65" with 4 total digits produces numbers like "6537".

Flight numbers are generated randomly and checked for uniqueness across all active (non-completed, non-cancelled, non-failed) missions. They are assigned when legs are created — both for manually created missions and auto-generated ones.

Routes

Each customer has one or more routes that define the leg patterns used when creating missions (manually or via auto-generation). A route consists of:

Field	Description
Weight	A relative selection weight. Higher values make this route more likely to be picked during auto-generation.
Route Type	Pair (simple point-to-point) or Sequence (multi-stop route with ordered legs).
Legs	Ordered list of flight segments, each with a departure and arrival airport.

For example, a customer with two routes — one with weight 3 and another with weight 1 — will have the first route selected roughly 75% of the time during auto-generation.

Aircraft Pool

Each customer is linked to a pool of aircraft. Auto-generation picks a random aircraft from this pool; when creating a mission manually, staff may pick any aircraft in the fleet (pool aircraft are suggested first).

Auto-Generation Settings

Field	Description
Auto-Generate Enabled	Toggle to enable or disable automatic mission creation.
Interval Min (days)	Minimum number of days between auto-generated missions.
Interval Max (days)	Maximum number of days between auto-generated missions. The actual interval is randomised between min and max.

When enabled, the system runs a daily job that checks each customer's last_generated_at timestamp and creates a new DRAFT mission if the interval has elapsed. Staff must then set the points award and publish the mission manually.

---

Charter Missions

Missions represent individual contracts. Manage them from the Charter Operations overview at Backoffice > Charter > Overview.

The Overview Page

The overview is the day-to-day home for charter operations:

• Stat cards — five headline numbers: Open contracts, Awaiting review (applications to triage), In progress, At risk, and Completed MTD (this month).
• Needs attention panel — contracts under deadline pressure, each with suggested actions:

Situation	Actions
A leg window closes within 24 hours and the leg is not booked	Message pilot / View
An open contract is unclaimed and its first window opens within 48 hours	Assign pilot / Ping eligible pilots
The mission aircraft is not at the first departure airport	Create repositioning bounty (or a Bounty posted badge when one is already active)

• Contract board — every contract with its Mode (Instant or Review badge), Pilot, Legs (segment bars), Next deadline (countdown), and Status. Expanding a row reveals the legs timeline, pending applications with Accept/Reject, and the full action set: publish, unpublish, assign, message, unassign, edit, fail, and cancel.

The Contract Builder

Creating a contract opens a five-step builder:

1. Contract — the customer, title, and a briefing for pilots.
2. Legs — the flight segments, with an Add return leg shortcut and ground-gap labels (same-day turnaround or days on the ground) between legs. Each leg has a departure and arrival airport and a time window; flight numbers are auto-assigned from the customer's prefix settings. A window may already be open when the contract is created, but every new leg must stay open for at least 48 hours from the moment of creation.
3. Aircraft — any aircraft in the fleet may be picked, searchable by registration. Aircraft in the customer's pool are listed first with a Customer pool badge, and each aircraft carries a position note (at the departure airport and ready to go, or elsewhere and needing repositioning).
4. Rules — the claiming mode, the points award with a live customer-multiplier preview, an optional exam requirement, and the customer's quota note.
5. Review — final checks on the aircraft position, leg windows, and quota, then Save as draft or Publish contract.

Editing a contract reuses the same builder. Completed legs are locked, airports can only change on legs that have not opened yet, the aircraft cannot change once legs are booked, and any window change notifies the assigned pilot with a schedule-change notification.

Legs that are not flown within their time window will cause the entire mission to fail automatically.

Claiming Modes

Every contract has a claiming mode, chosen in the builder's Rules step:

Mode	How pilots get the contract
Instant	The first eligible pilot to press Claim this Contract gets it immediately — no staff review. Best for urgent flying.
Reviewed applications	Pilots apply and staff pick one from the applications list. Best for showcase missions. This is the default.

Eligibility for an instant claim requires the pilot to be off cooldown, under the active-contract limit, and to have passed the contract's required exam (if any).

Assigning a Pilot Directly

Staff can assign any pilot to an open contract from the Assign pilot modal, skipping the application queue. The modal shows a searchable roster with each pilot's status — available, partially loaded, slots full, or blocked. Assigning a blocked or slot-full pilot is refused unless staff explicitly choose Override & assign; every override is recorded in the contract's activity log with the staff member's name. If the pilot had a pending application it is accepted, other applicants are rejected and notified, and the assigned pilot is notified.

Messaging Pilots

The Message pilot modal sends a free-text message to a pilot about a contract, on the channels staff choose (in-app and/or email). Ready-made templates cover the common cases — window reminder, aircraft ready early, and schedule change — alongside a custom message. Every message is logged on the contract's activity trail.

Pinging Eligible Pilots

For an open contract that nobody has taken, Ping eligible pilots sends an in-app notification to every pilot who could take it right now (off cooldown, free contract slot, required exam passed). Re-pings on the same contract are throttled to once every 6 hours.

---

Charter Pilots Page

The Backoffice > Charter > Pilots page tracks the people side of charter operations:

• Active assignments — one row per claimed contract, with leg progress, the next deadline, an at-risk/on-track indicator, and Message / View contract / Unassign actions.
• Applications awaiting review — pending applications grouped by contract, with Accept/Reject.
• Restricted pilots — every pilot currently on a contract cooldown, showing when the block expires and the last failed mission. Staff can Clear restriction to lift the cooldown early; this never refunds the penalty points and is recorded in the activity log.

---

Mission Lifecycle

1. Publishing

Once a draft mission is ready, staff publishes it, transitioning the status to Open. Publishing is refused if any of the customer's entitlement caps are exhausted (daily, monthly, or live-at-once). Pilots can now see the mission on their Contracts page.

2. Getting a Pilot

An open mission is assigned to a pilot through one of two paths, depending on its claiming mode:

Instant claim (instant contracts) — The first eligible pilot to claim the contract gets it immediately and the mission transitions straight to Assigned, with no staff review. Simultaneous claims are safe: only one pilot can win.

In both paths, a contract whose flight window has already fully closed cannot be applied to, claimed, or assigned (not even with a staff override) — it would only get the pilot auto-failed by the expiry check. Edit the windows to make it claimable again. If a window is already open at assignment time, the leg becomes bookable immediately instead of waiting for the next cron run.

Application review (reviewed contracts) — Pilots apply while the mission is Open; each application records the pilot and timestamp. When staff accepts an application:

• The selected application is marked as Accepted.
• The mission is assigned to the pilot and transitions to Assigned.
• All other pending applications are automatically Rejected, and rejected pilots receive a notification.
• The accepted pilot receives a Contract Assigned notification.

In both modes staff can also assign a pilot directly from the overview (see Assigning a Pilot Directly).

3. Leg Activation

Legs are activated in two ways:

• Automatically — When a leg's window_starts_at time is reached, the system opens it (checked every 5 minutes).
• Manually — Staff can open individual legs from the mission dashboard.

Opening a leg sets it to Available and, if the mission was in Assigned status, transitions the mission to In Progress. The assigned pilot is notified.

4. Booking and Flying

The assigned pilot books an available leg from the Contracts page or via the API. Booking creates a standard flight booking with:

• The mission's aircraft
• The leg's departure and arrival airports
• The leg's flight number — either a customer-branded number (e.g. 6537) or the default CHR{missionId}-{sequence} format

Once the pilot flies the leg through their ACARS client, the system automatically detects the completed flight and marks the leg as completed.

If the pilot cancels their booking before flying the leg, the leg returns to Available status and can be booked again. This does not affect the mission status or time windows — the pilot must still complete the leg within its original window.

5. Mission Completion

When all legs are completed, the mission automatically transitions to Completed:

• The aircraft is unlocked for other operations.
• The pilot receives effective points (base points multiplied by the customer's multiplier).
• A Contract Completed notification is sent.
• If the aircraft ended up at an airport with no outbound schedules available for it, a repositioning bounty is automatically created to ferry the aircraft back to its base. This bounty has no causer restriction, so any pilot can claim it.

---

Pilot Workflow

Pilot page: /contracts

From the Contracts page, pilots can:

1. Browse open missions and view details (customer, aircraft, legs, points).
2. Apply to reviewed missions they want to fly, or Claim instant missions — instant contracts carry an orange Instant bolt badge and a Claim this Contract button that assigns the contract immediately and jumps to My Contracts.
3. View their active assignments with leg-by-leg progress.
4. Book available legs and fly them via their ACARS client.
5. Forfeit an active contract from its detail view. Forfeiting before any flight window has opened is free — the contract simply returns to the board (completed legs are kept). Once a window has opened, forfeiting costs the same penalty and cooldown as failing the contract, and the confirmation dialog says so before the pilot commits.
6. Review their contract history (completed and failed missions).

Pilots who are currently in a cooldown period (after a failed contract) will see a blocked indicator and cannot apply to or claim new missions until the cooldown expires. Pilots are also limited to a maximum number of active contracts at once (see System Settings); the limit is enforced on both applying and claiming.

---

Points and Penalties

Point Awards

When a mission is completed successfully, the assigned pilot receives points calculated as:

Effective Points = Base Points Award x Customer Points Multiplier

For example, a mission with 100 base points for a customer with a 2.5x multiplier awards 250 points.

Penalties

When a mission fails (due to an expired time window or manual staff action), or a pilot forfeits after the flight window has opened:

Consequence	Details
Point Deduction	The pilot loses points equal to the configured penalty (default: 500 points).
Contract Cooldown	The pilot is blocked from applying to new contracts for the configured cooldown period (default: 90 days).
Booking Cleanup	All bookings for incomplete legs are automatically deleted.

Lifting a Contract Restriction

Administrators can clear or adjust a pilot's contract restriction from the user edit page (Backoffice > Users > Edit). When the pilot has an active block, a "Contract Restriction" section appears with options to:

• Adjust the date — change when the restriction expires
• Clear the restriction — remove the block entirely

Clearing or adjusting the restriction does not refund the penalty points that were deducted.

---

Aircraft Repositioning

The system monitors whether the assigned aircraft is at the correct departure airport for the first leg. This check runs every 30 minutes.

Scenario	Action
Aircraft at departure airport	Aircraft is locked to prevent other operations from moving it. Any pending repositioning bounty is cancelled.
Aircraft elsewhere, within lead time	A repositioning bounty is created so other pilots can ferry the aircraft to the correct location. The lead time is configurable (default: 48 hours before the first leg window).
Aircraft elsewhere, window already started	The aircraft is automatically teleported to the departure airport. The staff member who created the mission receives a notification.

Repositioning bounties integrate with the existing ferry/repositioning system. If a bounty pilot delivers the aircraft before the window starts, the bounty is completed normally and the aircraft is locked.

---

Auto-Generation

The system can automatically create draft missions for customers that have auto-generation enabled. The daily GenerateCharterContracts job:

1. Iterates all customers with auto-generation enabled.
2. Checks whether the configured interval (randomised between min and max days) has elapsed since the last generation.
3. Performs a weighted random selection from the customer's route pool.
4. Picks a random aircraft from the customer's aircraft pool.
5. Creates a DRAFT mission with legs based on the selected route, each with a default 24-hour time window starting the next day.

Staff must then review the generated mission, set the points award, adjust time windows if needed, and publish it.

---

System Settings

The following settings control charter contract behaviour. Configure them at Backoffice > Settings > System Settings under the Contracts module.

Setting	Default	Description
Contract Penalty Points	500	Points deducted when a pilot fails a contract.
Contract Cooldown Days	90	Days a pilot is blocked from new contracts after a failure.
Contract Repositioning Lead Hours	48	Hours before the first leg window to auto-create a repositioning bounty for the aircraft.
Maximum Active Contracts per Pilot	2	How many assigned or in-progress contracts a pilot may hold at once (0 = unlimited). Enforced when applying and claiming; staff can override per assignment.

---

Status Reference

Mission Status

Status	Description
Draft	Created but not yet visible to pilots.
Open	Published and accepting pilot applications.
Assigned	A pilot has been accepted; awaiting leg activation.
In Progress	At least one leg has been opened for the pilot.
Completed	All legs flown successfully; points awarded.
Failed	Mission failed; penalty applied.
Cancelled	Staff cancelled the mission; no penalty.

Leg Status

Status	Description
Pending	Leg created but not yet available.
Available	Opened for the pilot to book.
Booked	Pilot has booked this leg.
In Progress	Flight is underway.
Completed	Flight completed successfully.
Failed	Leg failed.
Cancelled	Leg cancelled.

Claim Mode

Mode	Meaning
instant	First eligible pilot claims the contract directly.
review	Pilots apply; staff accept one application.

Mission payloads also expose claim_mode and published_at.

Application Status

Status	Description
Pending	Application submitted, awaiting staff review.
Accepted	Application accepted; pilot assigned to mission.
Rejected	Application rejected (another pilot was selected).

---

Background Jobs

The following automated jobs keep charter operations running smoothly. Each job runs through a tenant-aware dispatcher that ensures correct database context in multi-tenant deployments.

Job	Frequency	Purpose
Check Leg Windows	Every 5 minutes	Opens legs whose time window has started.
Check Expired Windows	Every 5 minutes	Fails missions with legs past their deadline.
Check Repositioning	Every 30 minutes	Manages aircraft positioning (lock, bounty, or teleport).
Generate Contracts	Daily	Creates draft missions for customers with auto-generation enabled.

---

API

Charter contract data is available through the Private API v1. All endpoints require API key authentication.

Method	Endpoint	Description
GET	/api/v1/charter-customers	List charter customers.
GET	/api/v1/charter-customers/{id}	Get customer detail.
GET	/api/v1/charter-missions	List charter missions.
GET	/api/v1/charter-missions/{id}	Get mission detail.
POST	/api/v1/charter-missions/{id}/apply	Apply to a reviewed mission (422 for instant missions).
POST	/api/v1/charter-missions/{id}/claim	Claim an instant mission (422 with a reason when ineligible).
POST	/api/v1/charter-missions/{id}/forfeit	Forfeit an assigned contract (free before the window opens, penalized after).
DELETE	/api/v1/charter-missions/{id}/apply	Withdraw an application.
GET	/api/v1/charter-missions/{id}/legs	List legs for a mission.
POST	/api/v1/charter-missions/{id}/legs/{leg}/book	Book a leg.

Refer to the auto-generated API documentation at /docs/v1 for full request/response schemas.