Bills

Billing and wallet management. Requires a non-free company plan. Pilots need billing: true on their user record to appear in billing operations.

---

List Bills (Pilot Wallet)

GET /bills/index.json

GET /bills/index/{userId}.json

GET /bills/index/{userId}/{offset}.json

List wallet movement records for a pilot. Managers can view any pilot's bills; regular users (user_group_id ≥ 150) see only their own. Linked flight info is included if the flight is not deleted.

Query Parameters

Parameter	Type	Description
limit	number	Records per page (default: 10)

Response

{
  "bills": [
    {
      "UserBill": {
        "id": "xyz789",
        "user_id": "100",
        "company_id": "42",
        "flight_id": "5678",
        "name": "2025-01-10 LEBL-LEMD",
        "price": "-120.00",
        "total": "-120.00",
        "receipt": false,
        "created": "2025-01-10 15:00:00"
      },
      "Flight": {
        "callsign": "EC-ABC",
        "rules": "IFR",
        "offblocks_time": "1736505000",
        "block_time": "6900",
        "deleted": false
      }
    }
  ],
  "total": 42
}

---

View Bill

GET /bills/view/{id}.json

Full detail for a single bill including client info, company billing settings, and linked flight. Access does not require authentication (allowed in beforeFilter).

Path Parameters

Parameter	Type	Description
id	UUID	Bill ID

Response

{
  "bill": {
    "UserBill": {
      "id": "xyz789",
      "n_id": 12,
      "name": "2025-01-10 LEBL-LEMD",
      "price": -120.00,
      "price_hour": -60.00,
      "airport": 0.0,
      "fuel": 0.0,
      "handling": 0.0,
      "others": 0.0,
      "collected_tax": 0.0,
      "subtotal": -120.00,
      "total": -120.00,
      "packaged": 0.0,
      "packaged_time": 0.0,
      "billed_time": 2.0,
      "balance": -120.00,
      "receipt": false
    },
    "Flight": {
      "date": "2025-01-10",
      "callsign": "EC-ABC",
      "departure_airport": "LEBL",
      "landing_airport": "LEMD",
      "flight_time": "6900",
      "block_time": "6900",
      "rules": "IFR",
      "landings": 1
    },
    "Client": {
      "id": "100",
      "UserDetail": { "name": "John", "surname": "Doe", "passport": "AB123456", "phone": "[phone]", "address": "...", "city": "Barcelona", "pc": "08001", "Country": { "name": "Spain" } },
      "Company": {
        "name": "My FTO",
        "CompanyDetail": { "Country": { "name": "Spain" } },
        "CompanyBillingSetting": { "tax": "21", "billed_person": "pilot", "send_notification": true }
      }
    },
    "Creator": {
      "id": "50",
      "UserDetail": { "name": "Admin", "surname": "User" }
    },
    "UserBillPackageFlight": []
  }
}

---

Create Manual Bill

POST /bills/create.json

Create a manual wallet transaction for one or more pilots. If id is provided, updates an existing record. user_id can be a single UUID, an array of UUIDs, or a pilot group UUID (group members are expanded automatically). Restricted to user_group_id ≤ 145.

Request Body

Field	Type	Required	Description
user_id	string | array	Yes (new)	Pilot UUID(s) or pilot group UUID
price	number	Yes (new)	Amount (negative = charge, positive = credit)
name	string	Yes	Transaction description
created	string	No	Transaction date (defaults to now)
receipt	boolean	No	Mark as a receipt
id	UUID	No	Existing bill ID to update

Response

{
  "result": true,
  "new": true,
  "UserBills": [
    {
      "id": "xyz789",
      "user_id": "100",
      "name": "Manual adjustment",
      "price": "-50.00",
      "creator": "Admin User",
      "client": "John Doe"
    }
  ],
  "errors": []
}

---

Bill a Flight

GET /bills/flight.json?id={flightId}

POST /bills/flight.json?id={flightId}

Retrieve flight billing data (GET) or create/update a flight bill (POST). Flight must be confirmed and not deleted.

Query Parameters

Parameter	Type	Description
id	UUID	Flight ID

Request Body (POST)

Field	Type	Required	Description
user_id	UUID	Yes	Pilot to bill
price_hour	number	Yes	Hourly rate
price	number	Yes	Total flight price
airport	number	No	Airport fees
fuel	number	No	Fuel charges
handling	number	No	Handling charges
others	number	No	Other charges
rate_id	UUID	No	Rate record to use
notify	boolean	No	Send notification email to pilot
use_packages	boolean	No	Deduct from pilot's package balance
created	string	No	Bill date (defaults to onblocks_time)

Response

{
  "defaults": { "tax": "21", "default_airport": "0", ... },
  "payment": { "UserBill": { ... } },
  "flight": { "Flight": { ... }, "Aircraft": { ... }, "UserBill": { ... } },
  "errors": null
}

---

Delete Bill

POST /bills/delete.json

Delete a bill and recalculate the pilot's balance.

Request Body

Field	Type	Required	Description
bill	UUID	Yes	Bill ID to delete

Response

{
  "result": true,
  "balance": -240.00,
  "bill": { "UserBill": { "id": "xyz789", "name": "...", "total": "-120.00" } }
}

---

Auto-Bill a Flight

GET /bills/autobill/{flightId}.json

GET /bills/autobill/{flightId}/{userId}.json

POST /bills/autobill.json

Automatically generate a bill for a flight using the aircraft's default rate. Any existing bill for the flight is replaced. Optionally override which pilot to bill.

Request Body (POST)

Field	Type	Required	Description
flight	UUID	Yes	Flight ID
user	UUID	No	Override pilot to bill

Response

{
  "bill": { "UserBill": { ... } }
}

---

Get Pilot Balance

GET /bills/balance.json

GET /bills/balance/{userId}.json

Returns the current wallet balance for a pilot. Managers can query any billable pilot. Regular users see only their own balance.

Response

{
  "balance": -240.50
}

---

Create Stripe Payment Intent

GET /bills/pay.json

POST /bills/pay.json

Initiate a Stripe Checkout session to allow a pilot to pay their balance. Requires Stripe to be enabled and configured for the company.

Request Body (POST)

Field	Type	Required	Description
amount	number	No	Amount to pay (defaults to current balance)

Response

{
  "result": true,
  "message": "Payment intent created, redirecting to Stripe checkout.",
  "redirect_url": "https://checkout.stripe.com/..."
}

---

Complete Stripe Checkout

GET /bills/checkout/{token}.json

Process a completed Stripe Checkout session. Called automatically via the Stripe success_url redirect. Verifies payment status, records the credit, and notifies company managers.

Path Parameters

Parameter	Type	Description
token	string	Stripe Checkout session ID

Response

{
  "result": true,
  "message": "Payment received, thank you!"
}

---

Download Bills (XLS)

GET /bills/download.json

GET /bills/download/{userId}.json

Download all bills as an Excel file. Regular users see only their own. Requires token query param.

---

List Rates

GET /bills/rates.json

GET /bills/rates/true.json

List all billing rates for the company. Pass true to return only package rates.

Response

{
  "rates": [
    {
      "Rate": {
        "id": "r1",
        "company_id": "42",
        "name": "C172 Standard",
        "hourly_price": "120.00",
        "pack": false,
        "deleted": false
      },
      "Aircraft": [
        { "id": "45", "registration": "EC-ABC" }
      ]
    }
  ]
}

---

View Rate

GET /bills/rate/{id}.json

Retrieve a single rate with linked aircraft.

---

Get Rates for Aircraft

GET /bills/aircraft/{aircraftId}.json

List all rates configured for a specific aircraft.

---

List Packages (Pilot)

GET /bills/packages/{userId}.json

GET /bills/packages/{userId}/true.json

List flight-hour packages for a pilot. Pass true to return only valid packages (non-expired with remaining balance).

Response

{
  "packages": [
    {
      "UserBillPackage": {
        "id": "pkg1",
        "user_id": "100",
        "total": "50.00",
        "balance": "32.50",
        "expiration": "2026-12-31",
        "created": "2025-01-01 10:00:00"
      },
      "Rate": [{ "id": "r1", "name": "C172 Standard", "hourly_price": "120.00" }]
    }
  ]
}

---

View Package

GET /bills/package/{id}.json

Full details for a package including the pilot, creator, linked rate, bills, and associated flights.

---

Create / Update Package

POST /bills/manager_purchase_package.json

Create or update a flight-hour package for a pilot. Optionally creates a debit bill for the package cost.

Request Body

Field	Type	Required	Description
user_id	UUID	Yes (new)	Pilot to assign the package to
rate_id	array	Yes	Array of rate UUIDs to include
total	number	Yes	Total hours in the package
id	UUID	No	Existing package ID to update
expiration	string | timestamp	No	Package expiry date
bill	string	No	1 to also create a debit bill for the package cost

Response

{
  "new": true,
  "package": { "UserBillPackage": { "id": "pkg1", "balance": "50.00", ... } },
  "bill": "xyz789",
  "errors": null
}

---

Delete Package

POST /bills/manager_delete_package.json

Delete a package and its associated bill (if any). Recalculates the pilot's balance.

Request Body

Field	Type	Required	Description
id	UUID	Yes	Package ID

---

Manager: List All Bills

GET /bills/manager_index.json

GET /bills/manager_index/{type}.json

Paginated list of all company bills. type is transactions (default, non-flight bills) or flights (flight-linked bills).

Named Parameters / POST Filters

Parameter	Description
from	Start date filter
to	End date filter
pilot	Filter by pilot user ID
excel	Append excel:true for XLS download (requires token)

---

Manager: Bill Stats

GET /bills/manager_stats/{type}.json

POST /bills/manager_stats/{type}.json

Aggregated stats over the full filtered set (not paginated). Same type and filters as manager_index — from, to, pilot. Filters can be sent as POST body or query string. Designed to be fetched in parallel with the first page of manager_index and refetched on every filter change. Charts read from this response, not from the paginated bill list.

type: transactions (default, flight_id = '') or flights (flight_id <> '').

totalSeconds is SUM(billed_time) * 3600 (billed_time stored as hours). topClients returns up to 10 entries ordered by ABS(SUM(total)) desc.

Filters (POST body or query string)

Parameter	Description
from	Start date (anything strtotime accepts)
to	End date (anything strtotime accepts)
pilot	Filter by pilot user ID

Response

{
  "stats": {
    "type": "transactions",
    "count": 1842,
    "total": 125430.55,
    "avg": 68.10,
    "positive": 145200.00,
    "negative": -19769.45,
    "totalSeconds": 0,
    "monthly": [
      {
        "month": "2026-01",
        "count": 312,
        "total": 21500.00,
        "positive": 24000.00,
        "negative": -2500.00,
        "totalSeconds": 0
      }
    ],
    "topClients": [
      {
        "user_id": "100",
        "name": "John Doe",
        "count": 87,
        "total": 9420.00,
        "totalSeconds": 0
      }
    ]
  }
}

For type=flights, totalSeconds reflects flight billed time across the filtered set.

---

Manager: List Billable Pilots

GET /bills/manager_pilots.json

GET /bills/manager_pilots/{aircraftId}.json

List all active, non-deleted pilots with billing: true. If an aircraft ID is provided, also returns each pilot's configured hourly price for that aircraft.

Response

{
  "pilots": [
    { "id": "100", "name": "John Doe", "group": "170", "groupname": "Pilot", "price": "120.00" }
  ]
}

---

Manager: List All Packages

GET /bills/manager_packages.json

Paginated list of all packages across all company pilots.

---

Manager: Billable Flights

GET /bills/manager_flights.json

Paginated list of flights on billing-enabled aircraft. Supports named parameter filters:

Named Param	Description
pilot	Filter by PIC or SIC user ID
status	billed or notbilled
base	Filter by base ID
flight_type	Filter by flight type ID
flight_rules	Filter by rules (IFR, VFR)
from	Filter from date
to	Filter to date
excel	Append excel:true for XLS download

---

Manager: Create / Update Rate

POST /bills/manager_rate_edit.json

Create or update a billing rate and assign aircraft.

Request Body

Field	Type	Required	Description
Rate.id	UUID	No	Existing rate ID to update
Rate.name	string	Yes	Rate name
Rate.hourly_price	number	Yes	Price per hour
Rate.pack	boolean	No	Is this a package rate
Rate.aircraft_id	array	No	Aircraft UUIDs to link

---

Manager: Delete Rate

POST /bills/manager_rate_delete.json

Soft-delete a rate and remove all aircraft-rate associations.

Request Body

Field	Type	Required	Description
rateId	UUID	Yes	Rate ID to delete