> ## Documentation Index
> Fetch the complete documentation index at: https://docs.planeconnection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Charter Marketplace Reference

> Statuses, fields, messaging states, settings schema, and configuration for the PlaneConnection charter marketplace system.

The charter marketplace connects operators seeking lift with pilots offering their services. The marketplace requires the **Ops** module with **Charter Marketplace** enabled.

<Warning>
  The charter marketplace is currently in beta and may have limited availability. Features and
  statuses are subject to change. Contact support to enable the marketplace for your workspace.
</Warning>

## Charter Request Statuses

A charter request represents a trip published to the marketplace. Each request follows a defined lifecycle.

| Status                                      | API Value       | Description                                                                                                             |
| ------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| <Badge color="blue">Open</Badge>            | `open`          | Request is published and accepting applications from pilots. Visible to marketplace participants.                       |
| <Badge color="yellow">Proposal Sent</Badge> | `proposal_sent` | The organization has sent a proposal to a pilot or is in negotiation.                                                   |
| <Badge color="green">Approved</Badge>       | `approved`      | The request has been approved and a pilot has been selected.                                                            |
| <Badge color="cyan">Assigned</Badge>        | `assigned`      | A pilot has been assigned to the request. The trip is confirmed and ready for operations.                               |
| <Badge color="green">Completed</Badge>      | `completed`     | The trip has been flown and completed. Terminal state.                                                                  |
| <Badge color="red">Cancelled</Badge>        | `cancelled`     | The requesting organization cancelled the request. All pending applications are automatically rejected. Terminal state. |

### Request Lifecycle

```mermaid theme={}
stateDiagram-v2
    [*] --> open : Request published
    open --> proposal_sent : Proposal sent to pilot
    open --> cancelled : Organization cancels
    proposal_sent --> approved : Pilot/org agrees
    proposal_sent --> open : Proposal declined, reopen
    proposal_sent --> cancelled : Organization cancels
    approved --> assigned : Pilot assigned to trip
    approved --> cancelled : Organization cancels
    assigned --> completed : Trip flown
    assigned --> cancelled : Trip cancelled
    completed --> [*]
    cancelled --> [*]
```

<Note>
  A request in **Proposal Sent** can return to **Open** if the proposal is declined, allowing
  additional pilots to apply.
</Note>

## Application Statuses

An application represents a pilot's bid to fulfill a charter request. Each application is tied to one request and one pilot.

| Status                                | API Value   | Description                                                                          |
| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
| <Badge color="blue">Pending</Badge>   | `pending`   | Application has been submitted by the pilot. Awaiting organization review.           |
| <Badge color="green">Approved</Badge> | `approved`  | Application has been accepted. The pilot is selected for the trip. Terminal state.   |
| <Badge color="red">Rejected</Badge>   | `rejected`  | Application was not selected. The organization may provide a reason. Terminal state. |
| <Badge color="gray">Withdrawn</Badge> | `withdrawn` | The pilot withdrew their application before a decision was made. Terminal state.     |

### Application Lifecycle

```mermaid theme={}
stateDiagram-v2
    [*] --> pending : Pilot applies
    pending --> approved : Organization accepts
    pending --> rejected : Not selected
    pending --> withdrawn : Pilot withdraws
    rejected --> [*]
    approved --> [*]
    withdrawn --> [*]
```

### Automatic Status Transitions

The system transitions application statuses automatically under the following conditions:

| Trigger                  | Effect                                              |
| ------------------------ | --------------------------------------------------- |
| Request cancelled        | All `pending` applications move to `rejected`       |
| One application approved | All other `pending` applications move to `rejected` |

## Charter Request Fields

| Field               | Type      | Required | Description                                                                        |
| ------------------- | --------- | -------- | ---------------------------------------------------------------------------------- |
| `title`             | String    | Yes      | Short summary of the trip (e.g., "KTEB to KPBI, Mar 15-17").                       |
| `origin`            | String    | Yes      | Departure airport name or ICAO code.                                               |
| `destination`       | String    | Yes      | Arrival airport name or ICAO code.                                                 |
| `departure_date`    | Date      | Yes      | Requested departure date.                                                          |
| `return_date`       | Date      | No       | Requested return date for round trips.                                             |
| `required_role`     | Enum      | Yes      | Required crew role: `PIC`, `SIC`, or `BOTH`. Default: PIC.                         |
| `duration_days`     | Number    | No       | Duration of the assignment in days.                                                |
| `compensation`      | Number    | No       | Offered compensation amount.                                                       |
| `compensation_type` | Enum      | No       | Compensation structure: `hourly`, `daily`, or `fixed`.                             |
| `requirements`      | Array     | No       | Specific requirements (type ratings, certifications, experience).                  |
| `status`            | Enum      | Auto     | Current request status. See [Charter Request Statuses](#charter-request-statuses). |
| `created_at`        | Timestamp | Auto     | When the request was created.                                                      |
| `updated_at`        | Timestamp | Auto     | When the request was last modified.                                                |

## Application Fields

| Field                        | Type      | Required | Description                                                                    |
| ---------------------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `charter_request_id`         | String    | Auto     | Reference to the parent charter request.                                       |
| `pilot_id`                   | String    | Auto     | User ID of the applying pilot.                                                 |
| `status`                     | Enum      | Auto     | Current application status. See [Application Statuses](#application-statuses). |
| `proposal_message`           | Text      | No       | Pilot's cover message or proposal.                                             |
| `proposed_compensation`      | Number    | No       | Pilot's counter-offer amount.                                                  |
| `proposed_compensation_type` | Enum      | No       | Counter-offer structure: `hourly`, `daily`, or `fixed`.                        |
| `pilot_qualifications`       | Array     | No       | Relevant qualifications and certifications.                                    |
| `organization_response`      | Text      | No       | Organization's response to the application.                                    |
| `applied_at`                 | Timestamp | Auto     | When the application was submitted.                                            |

## Messaging States

Each charter request has a messaging thread for communication between the organization and pilots. Messages follow these rules:

| State                             | Who Can Send                          | Visibility                                                                                             |
| --------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Request Open**                  | Organization and all applicant pilots | Each pilot sees only their own thread with the organization. Pilots cannot see other pilots' messages. |
| **Proposal Sent**                 | Organization and relevant pilot       | Thread continues between the two parties.                                                              |
| **Assigned**                      | Organization and assigned pilot only  | Thread continues between the two parties. Other pilots lose messaging access.                          |
| **Request Cancelled / Completed** | No new messages                       | Existing threads become read-only.                                                                     |

### Message Fields

| Field                | Type      | Description                                 |
| -------------------- | --------- | ------------------------------------------- |
| `message_id`         | String    | Unique identifier.                          |
| `charter_request_id` | String    | Reference to the parent charter request.    |
| `sender_id`          | String    | User who sent the message.                  |
| `sender_type`        | Enum      | `organization` or `pilot`.                  |
| `message`            | Text      | Message body.                               |
| `attachments`        | Array     | Optional file attachments.                  |
| `is_read`            | Boolean   | Whether the recipient has read the message. |
| `created_at`         | Timestamp | When the message was sent.                  |

## Settings Schema

Workspace administrators can configure marketplace behavior through the charter request settings:

| Setting        | Type    | Default | Description                                                  |
| -------------- | ------- | ------- | ------------------------------------------------------------ |
| `is_active`    | Boolean | `false` | Master toggle for marketplace participation.                 |
| `acknowledged` | Boolean | `false` | Whether the organization has acknowledged marketplace terms. |
| `roles`        | Array   | `[]`    | Roles allowed to submit charter requests.                    |
| `emails`       | Array   | `[]`    | Notification email addresses for marketplace activity.       |

### Allowed Users

Organizations can maintain a whitelist of users allowed to view and apply to their charter requests through the **Charter Allowed Users** table.

## Related

<CardGroup cols={2}>
  <Card title="Trip Statuses" href="/reference/trip-statuses">
    How marketplace trips integrate with trip lifecycle after assignment.
  </Card>

  <Card title="Use the Charter Marketplace" href="/how-to/ops/use-charter-marketplace">
    Request publishing and application submission.
  </Card>

  <Card title="Crew Roles" href="/reference/crew-roles">
    Crew role definitions for marketplace trip assignments.
  </Card>

  <Card title="Notification Channels" href="/reference/notification-channels">
    Configure how you receive marketplace notifications.
  </Card>
</CardGroup>