Charter Contracts

Backoffice path: Backoffice > Charter > Customers (/backoffice/charter/customers) and Backoffice > Charter > Missions (/backoffice/charter/missions)

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 apply to fly the contract. 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.

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.

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 that may be assigned to their missions. When auto-generating, the system picks a random aircraft from this pool.

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 missions at Backoffice > Charter > Missions.

Creating a Mission

Staff creates a charter mission in Draft status with the following details:

Field	Description
Customer	The charter customer requesting the operation.
Aircraft	The specific aircraft assigned to the mission.
Title	A descriptive title for the mission.
Description	Details about the mission purpose and requirements.
Points Award	Base points awarded on successful completion (before multiplier).

Defining Legs

Each mission consists of one or more legs flown in sequence. A leg represents a single flight segment:

Field	Description
Sequence	The order in which legs must be flown (1, 2, 3, etc.).
Flight Number	Auto-assigned based on the customer's prefix settings. Shown as a badge on the dashboard.
Departure Airport	The origin airport for this leg.
Arrival Airport	The destination airport for this leg.
Window Start	The earliest allowed departure time.
Window End	The latest allowed arrival time.

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

---

Mission Lifecycle

1. Publishing

Once a draft mission is ready, staff publishes it, transitioning the status to Open. Pilots can now see the mission and submit applications from their Contracts page.

2. Pilot Applications

Pilots apply to fly the mission while it is Open. Each application records the pilot and timestamp. Staff reviews applications and selects the best candidate.

3. Accepting an Application

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.

4. 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.

5. 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.

6. 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 missions they want to fly.
3. View their active assignments with leg-by-leg progress.
4. Book available legs and fly them via their ACARS client.
5. 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 new missions until the cooldown expires.

---

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):

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.

---

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.

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 mission.
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.