Agency Reporting API Reference

Pull your sales data, bookings, and revenue reports from AviaFrame. All data is scoped to your agency — you can only access your own bookings.

Authentication

All requests must include your API key in the Authorization header using the Bearer scheme.

# Example request with API key
curl https://peaceful-amazement-production-629f.up.railway.app/api/agency/reports/bookings \
  -H "Authorization: Bearer avf_live_YOUR_API_KEY"

Key properties

• Scope: reports:read — read-only access, no mutations possible
• Keys can be revoked at any time by your AviaFrame account manager
• Multiple keys can be issued (e.g. for different internal systems)

Errors

All errors return a consistent JSON structure with an error object:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required. Use Authorization: Bearer <key>"
  }
}

Pagination

List endpoints return a pagination object alongside data:

{
  "data": [ /* ... */ ],
  "pagination": {
    "total": 143,
    "page": 1,
    "limit": 50,
    "pages": 3
  }
}

Use ?page=2&limit=50 to paginate. Maximum limit is 200.

List Bookings

# Fetch issued bookings for August 2026
curl "https://peaceful-amazement-production-629f.up.railway.app/api/agency/reports/bookings\
?from=2026-08-01&to=2026-08-31&status=ticketed&limit=50" \
  -H "Authorization: Bearer avf_live_YOUR_API_KEY"

# Response
{
  "data": [
    {
      "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "order_number": "AVF12345678",
      "status": "ticketed",
      "origin": "TBS",
      "destination": "DXB",
      "departure_time": "2026-09-01T06:00:00Z",
      "airline_name": "Georgian Airways",
      "flight_number": "A9111",
      "passengers": { "ADT": 2, "CHD": 1 },
      "base_price": 620.00,
      "taxes": 48.50,
      "baggage_price": 0.00,
      "total_price": 668.50,
      "currency": "USD",
      "ticket_number": "257-1234567890",
      "pnr": "ABCDEF",
      "issued_at": "2026-08-15T14:30:00Z",
      "created_at": "2026-08-14T09:12:00Z"
    }
  ],
  "pagination": { "total": 47, "page": 1, "limit": 50, "pages": 1 }
}

Get Booking

# Get single booking detail
curl "https://peaceful-amazement-production-629f.up.railway.app\
/api/agency/reports/bookings/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer avf_live_YOUR_API_KEY"

Revenue

# Revenue by month, last 3 months
curl "https://peaceful-amazement-production-629f.up.railway.app\
/api/agency/reports/revenue?from=2026-06-01&to=2026-08-31&group_by=month" \
  -H "Authorization: Bearer avf_live_YOUR_API_KEY"

# Response
{
  "data": [
    { "period": "2026-06", "bookings_count": 31, "revenue": 14820.00, "cancelled_count": 2, "currency": "USD" },
    { "period": "2026-07", "bookings_count": 44, "revenue": 21340.50, "cancelled_count": 3, "currency": "USD" },
    { "period": "2026-08", "bookings_count": 47, "revenue": 22150.00, "cancelled_count": 1, "currency": "USD" }
  ],
  "group_by": "month"
}

Summary

# Response
{
  "data": {
    "period": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-08-31T23:59:59.999Z" },
    "total_bookings": 47,
    "ticketed_count": 43,
    "cancelled_count": 1,
    "total_revenue": 22150.00,
    "currency": "USD",
    "top_routes": [
      { "origin": "TBS", "destination": "DXB", "count": 18 },
      { "origin": "TBS", "destination": "IST", "count": 12 }
    ]
  }
}

Export CSV

# Download CSV for August — open directly in Excel
curl -OJ "https://peaceful-amazement-production-629f.up.railway.app\
/api/agency/reports/export?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer avf_live_YOUR_API_KEY"

# Output file: aviaframe-bookings-2026-08-01-to-2026-08-31.csv

CSV columns: order_number, status, origin, destination, departure_time, airline_name, flight_number, pax_ADT, pax_CHD, pax_INF, base_price, taxes, baggage_price, total_price, currency, ticket_number, pnr, issued_at, created_at

Booking Object

All booking endpoints return booking objects with these fields:

Order Statuses