Objects

Reference

Objects

The Muvon API objects: Quote, Booking and Event, field by field.

Objects can gain fields: ignore the ones you don't know. We never remove or change a field within v1.

Quote

idstringrequired

Quote id (qt_…). You send it when booking.

objectstringrequired

Always quote.

Values: quote

livemodebooleanrequired

true with a live key, false with a test key.

expires_atstring (date-time)required

Until when this quote can be booked.

currencystringrequired

Always USD in v1.

Values: USD

requestobjectrequired

What you asked for, normalized (place names, date with offset).

optionsobject[]required

One option per vehicle type that fits; always at least one. When none fits, the quote answers a 422 error (passengers_out_of_range, too_many_bags, notice_too_short or route_not_priceable).

options[].vehicle_type_idstringrequired

Vehicle type. You send it when booking.

options[].namestringrequired

Vehicle type name.

options[].max_passengersintegerrequired

Passenger capacity.

options[].max_bagsintegerrequired

Bag capacity.

options[].price_centsintegerrequired

Total public price in US cents, extras included. What your customer pays.

options[].commission_centsintegerrequired

Your commission in cents, per your agreement with Muvon.

options[].kmnumbernullable

Trip distance in km (null for hourly).

Example

{
  "id": "qt_8f3a1c9e2b7d4f60",
  "object": "quote",
  "livemode": false,
  "expires_at": "2026-11-14T18:40:00-05:00",
  "currency": "USD",
  "request": {
    "service_type": "airport_pickup",
    "pickup_at": "2026-12-20T14:30:00-05:00",
    "pickup": {
      "place_id": "pl_cun",
      "name": "Cancun Airport (CUN)",
      "address": null
    },
    "dropoff": {
      "place_id": "pl_hotel52",
      "name": "Hotel 52 Playa del Carmen",
      "address": null
    },
    "hours": null,
    "passengers": {
      "adults": 2,
      "children": 1
    },
    "bags": 3,
    "extras": [
      {
        "code": "BOOSTER_SEAT",
        "quantity": 1
      }
    ]
  },
  "options": [
    {
      "vehicle_type_id": "vt_sedan",
      "name": "Sedan / SUV / Tesla",
      "max_passengers": 3,
      "max_bags": 3,
      "price_cents": 9500,
      "commission_cents": 950,
      "km": 54.2
    },
    {
      "vehicle_type_id": "vt_van",
      "name": "Van",
      "max_passengers": 12,
      "max_bags": 12,
      "price_cents": 13000,
      "commission_cents": 1300,
      "km": 54.2
    }
  ]
}

Booking

idstringrequired

Booking id.

objectstringrequired

Always booking.

Values: booking

kindstringrequired

Product. Always transfer in v1; Muvon rentals will come with their own value.

Values: transfer

codestringrequired

Code the customer sees: MVN-000123 in live, TEST-000001 in test. Works as ref in paths.

livemodebooleanrequired

false for test bookings.

statusstringrequired

Ride status. See Booking lifecycle.

Values: new, assigned, confirmed, on_the_way, arrived, on_board, dropped_off, completed, no_show, cancelled

payment_statusstringrequired

unpaid or paid. refunded once the team records a refund.

payment_urlstring (uri)nullable

Payment link for your customer. See Payment link.

hold_expires_atstring (date-time)nullable

Cancelled automatically if not paid by then. If your customer opens the payment near the end, it can stretch by up to 35 minutes so they can finish paying. null once paid or cancelled.

external_refstringnullable

Your reference.

service_typestringrequired

Service type.

Values: airport_pickup, airport_dropoff, point_to_point, hourly

pickup_atstring (date-time)required

Pickup, with Cancun's offset.

pickupobject

Origin.

pickup.place_idstringnullable

Place id, or null when it was an address.

pickup.namestring

Name the pilot sees.

pickup.addressstringnullable

Address, when given.

dropoffobjectnullable

Destination (for hourly without one, the same as pickup).

dropoff.place_idstringnullable

Place id, or null when it was an address.

dropoff.namestring

Name the pilot sees.

dropoff.addressstringnullable

Address, when given.

hoursintegernullable

Hours, only for hourly.

vehicle_type_idstringrequired

Booked vehicle type.

passengersobjectrequired

Passengers.

passengers.adultsintegerrequired

Adults.

passengers.childrenintegerrequired

Children.

bagsintegerrequired

Bags.

extrasobject[]required

Booked extras.

extras[].codestringrequired

Code.

extras[].quantityintegerrequired

Quantity.

extras[].price_centsintegerrequired

Unit price in cents (the line costs price × quantity).

flight_numberstringnullable

Flight.

roomstringnullable

Room.

notesstringnullable

Your notes.

passengerobjectrequired

Who travels.

passenger.first_namestringrequired

First name.

passenger.last_namestringrequired

Last name.

passenger.emailstring (email)required

Email.

passenger.phonestringnullable

Phone.

passenger.languagestringrequired

Language.

Values: es, en

price_centsintegerrequired

Total public price in cents.

currencystringrequired

USD.

Values: USD

commission_centsintegerrequired

Your commission in cents.

tracking_urlstring (uri)nullable

Ride page for the passenger: status, pilot on the way, contact.

cancel_reasonstringnullable

Why it was cancelled. payment_timeout when the hold ran out unpaid.

created_atstring (date-time)required

Created.

updated_atstring (date-time)required

Last change.

Example

{
  "id": "bk_5d2e8a41c07f4b9e",
  "object": "booking",
  "kind": "transfer",
  "code": "TEST-000001",
  "livemode": false,
  "status": "new",
  "payment_status": "unpaid",
  "payment_url": "https://api.muvon.mx/pay/r/3c9f0b7e6a5d4c2b1a09f8e7d6c5b4a3",
  "hold_expires_at": "2026-11-14T20:10:00-05:00",
  "external_ref": "ORDER-5521",
  "service_type": "airport_pickup",
  "pickup_at": "2026-12-20T14:30:00-05:00",
  "pickup": {
    "place_id": "pl_cun",
    "name": "Cancun Airport (CUN)",
    "address": null
  },
  "dropoff": {
    "place_id": "pl_hotel52",
    "name": "Hotel 52 Playa del Carmen",
    "address": null
  },
  "hours": null,
  "vehicle_type_id": "vt_sedan",
  "passengers": {
    "adults": 2,
    "children": 1
  },
  "bags": 3,
  "extras": [
    {
      "code": "BOOSTER_SEAT",
      "quantity": 1,
      "price_cents": 1000
    }
  ],
  "flight_number": "AA1234",
  "room": null,
  "notes": "Viajamos con una carriola",
  "passenger": {
    "first_name": "Ana",
    "last_name": "García",
    "email": "ana@example.com",
    "phone": "+5215512345678",
    "language": "es"
  },
  "price_cents": 9500,
  "currency": "USD",
  "commission_cents": 950,
  "tracking_url": "https://api.muvon.mx/track?t=a1b2c3d4e5f6",
  "cancel_reason": null,
  "created_at": "2026-11-14T18:10:00-05:00",
  "updated_at": "2026-11-14T18:10:00-05:00"
}

Event

idstringrequired

Event id (evt_…). Use it to avoid processing the same one twice.

objectstringrequired

Always event.

Values: event

typestringrequired

What happened. See Webhooks.

Values: booking.created, booking.paid, booking.assigned, booking.confirmed, booking.on_the_way, booking.arrived, booking.on_board, booking.dropped_off, booking.completed, booking.no_show, booking.cancelled, ping

createdstring (date-time)required

When it happened.

livemodebooleanrequired

Booking mode.

dataobjectrequired

Event content.

data.objectobject

The full booking as it was after the change. On ping it is { "object": "ping", "message": "…" }.

Example

{
  "id": "evt_0a9b8c7d6e5f4a3b",
  "object": "event",
  "type": "booking.paid",
  "created": "2026-11-14T18:22:41-05:00",
  "livemode": false,
  "data": {
    "object": {
      "id": "bk_5d2e8a41c07f4b9e",
      "object": "booking",
      "kind": "transfer",
      "code": "TEST-000001",
      "livemode": false,
      "status": "new",
      "payment_status": "paid",
      "payment_url": "https://api.muvon.mx/pay/r/3c9f0b7e6a5d4c2b1a09f8e7d6c5b4a3",
      "hold_expires_at": null,
      "external_ref": "ORDER-5521",
      "service_type": "airport_pickup",
      "pickup_at": "2026-12-20T14:30:00-05:00",
      "pickup": {
        "place_id": "pl_cun",
        "name": "Cancun Airport (CUN)",
        "address": null
      },
      "dropoff": {
        "place_id": "pl_hotel52",
        "name": "Hotel 52 Playa del Carmen",
        "address": null
      },
      "hours": null,
      "vehicle_type_id": "vt_sedan",
      "passengers": {
        "adults": 2,
        "children": 1
      },
      "bags": 3,
      "extras": [
        {
          "code": "BOOSTER_SEAT",
          "quantity": 1,
          "price_cents": 1000
        }
      ],
      "flight_number": "AA1234",
      "room": null,
      "notes": "Viajamos con una carriola",
      "passenger": {
        "first_name": "Ana",
        "last_name": "García",
        "email": "ana@example.com",
        "phone": "+5215512345678",
        "language": "es"
      },
      "price_cents": 9500,
      "currency": "USD",
      "commission_cents": 950,
      "tracking_url": "https://api.muvon.mx/track?t=a1b2c3d4e5f6",
      "cancel_reason": null,
      "created_at": "2026-11-14T18:10:00-05:00",
      "updated_at": "2026-11-14T18:22:41-05:00"
    }
  }
}

Quote

idstringrequired

Quote id (qt_…). You send it when booking.

objectstringrequired

Always quote.

Values: quote

livemodebooleanrequired

true with a live key, false with a test key.

expires_atstring (date-time)required

Until when this quote can be booked.

currencystringrequired

Always USD in v1.

Values: USD

requestobjectrequired

What you asked for, normalized (place names, date with offset).

optionsobject[]required

One option per vehicle type that fits; always at least one. When none fits, the quote answers a 422 error (passengers_out_of_range, too_many_bags, notice_too_short or route_not_priceable).

options[].vehicle_type_idstringrequired

Vehicle type. You send it when booking.

options[].namestringrequired

Vehicle type name.

options[].max_passengersintegerrequired

Passenger capacity.

options[].max_bagsintegerrequired

Bag capacity.

options[].price_centsintegerrequired

Total public price in US cents, extras included. What your customer pays.

options[].commission_centsintegerrequired

Your commission in cents, per your agreement with Muvon.

options[].kmnumbernullable

Trip distance in km (null for hourly).

Example

{
  "id": "qt_8f3a1c9e2b7d4f60",
  "object": "quote",
  "livemode": false,
  "expires_at": "2026-11-14T18:40:00-05:00",
  "currency": "USD",
  "request": {
    "service_type": "airport_pickup",
    "pickup_at": "2026-12-20T14:30:00-05:00",
    "pickup": {
      "place_id": "pl_cun",
      "name": "Cancun Airport (CUN)",
      "address": null
    },
    "dropoff": {
      "place_id": "pl_hotel52",
      "name": "Hotel 52 Playa del Carmen",
      "address": null
    },
    "hours": null,
    "passengers": {
      "adults": 2,
      "children": 1
    },
    "bags": 3,
    "extras": [
      {
        "code": "BOOSTER_SEAT",
        "quantity": 1
      }
    ]
  },
  "options": [
    {
      "vehicle_type_id": "vt_sedan",
      "name": "Sedan / SUV / Tesla",
      "max_passengers": 3,
      "max_bags": 3,
      "price_cents": 9500,
      "commission_cents": 950,
      "km": 54.2
    },
    {
      "vehicle_type_id": "vt_van",
      "name": "Van",
      "max_passengers": 12,
      "max_bags": 12,
      "price_cents": 13000,
      "commission_cents": 1300,
      "km": 54.2
    }
  ]
}

Booking

idstringrequired

Booking id.

objectstringrequired

Always booking.

Values: booking

kindstringrequired

Product. Always transfer in v1; Muvon rentals will come with their own value.

Values: transfer

codestringrequired

Code the customer sees: MVN-000123 in live, TEST-000001 in test. Works as ref in paths.

livemodebooleanrequired

false for test bookings.

statusstringrequired

Ride status. See Booking lifecycle.

Values: new, assigned, confirmed, on_the_way, arrived, on_board, dropped_off, completed, no_show, cancelled

payment_statusstringrequired

unpaid or paid. refunded once the team records a refund.

payment_urlstring (uri)nullable

Payment link for your customer. See Payment link.

hold_expires_atstring (date-time)nullable

Cancelled automatically if not paid by then. If your customer opens the payment near the end, it can stretch by up to 35 minutes so they can finish paying. null once paid or cancelled.

external_refstringnullable

Your reference.

service_typestringrequired

Service type.

Values: airport_pickup, airport_dropoff, point_to_point, hourly

pickup_atstring (date-time)required

Pickup, with Cancun's offset.

pickupobject

Origin.

pickup.place_idstringnullable

Place id, or null when it was an address.

pickup.namestring

Name the pilot sees.

pickup.addressstringnullable

Address, when given.

dropoffobjectnullable

Destination (for hourly without one, the same as pickup).

dropoff.place_idstringnullable

Place id, or null when it was an address.

dropoff.namestring

Name the pilot sees.

dropoff.addressstringnullable

Address, when given.

hoursintegernullable

Hours, only for hourly.

vehicle_type_idstringrequired

Booked vehicle type.

passengersobjectrequired

Passengers.

passengers.adultsintegerrequired

Adults.

passengers.childrenintegerrequired

Children.

bagsintegerrequired

Bags.

extrasobject[]required

Booked extras.

extras[].codestringrequired

Code.

extras[].quantityintegerrequired

Quantity.

extras[].price_centsintegerrequired

Unit price in cents (the line costs price × quantity).

flight_numberstringnullable

Flight.

roomstringnullable

Room.

notesstringnullable

Your notes.

passengerobjectrequired

Who travels.

passenger.first_namestringrequired

First name.

passenger.last_namestringrequired

Last name.

passenger.emailstring (email)required

Email.

passenger.phonestringnullable

Phone.

passenger.languagestringrequired

Language.

Values: es, en

price_centsintegerrequired

Total public price in cents.

currencystringrequired

USD.

Values: USD

commission_centsintegerrequired

Your commission in cents.

tracking_urlstring (uri)nullable

Ride page for the passenger: status, pilot on the way, contact.

cancel_reasonstringnullable

Why it was cancelled. payment_timeout when the hold ran out unpaid.

created_atstring (date-time)required

Created.

updated_atstring (date-time)required

Last change.

Example

{
  "id": "bk_5d2e8a41c07f4b9e",
  "object": "booking",
  "kind": "transfer",
  "code": "TEST-000001",
  "livemode": false,
  "status": "new",
  "payment_status": "unpaid",
  "payment_url": "https://api.muvon.mx/pay/r/3c9f0b7e6a5d4c2b1a09f8e7d6c5b4a3",
  "hold_expires_at": "2026-11-14T20:10:00-05:00",
  "external_ref": "ORDER-5521",
  "service_type": "airport_pickup",
  "pickup_at": "2026-12-20T14:30:00-05:00",
  "pickup": {
    "place_id": "pl_cun",
    "name": "Cancun Airport (CUN)",
    "address": null
  },
  "dropoff": {
    "place_id": "pl_hotel52",
    "name": "Hotel 52 Playa del Carmen",
    "address": null
  },
  "hours": null,
  "vehicle_type_id": "vt_sedan",
  "passengers": {
    "adults": 2,
    "children": 1
  },
  "bags": 3,
  "extras": [
    {
      "code": "BOOSTER_SEAT",
      "quantity": 1,
      "price_cents": 1000
    }
  ],
  "flight_number": "AA1234",
  "room": null,
  "notes": "Viajamos con una carriola",
  "passenger": {
    "first_name": "Ana",
    "last_name": "García",
    "email": "ana@example.com",
    "phone": "+5215512345678",
    "language": "es"
  },
  "price_cents": 9500,
  "currency": "USD",
  "commission_cents": 950,
  "tracking_url": "https://api.muvon.mx/track?t=a1b2c3d4e5f6",
  "cancel_reason": null,
  "created_at": "2026-11-14T18:10:00-05:00",
  "updated_at": "2026-11-14T18:10:00-05:00"
}

Event

idstringrequired

Event id (evt_…). Use it to avoid processing the same one twice.

objectstringrequired

Always event.

Values: event

typestringrequired

What happened. See Webhooks.

createdstring (date-time)required

When it happened.

livemodebooleanrequired

Booking mode.

dataobjectrequired

Event content.

data.objectobject

The full booking as it was after the change. On ping it is { "object": "ping", "message": "…" }.

Example

{
  "id": "evt_0a9b8c7d6e5f4a3b",
  "object": "event",
  "type": "booking.paid",
  "created": "2026-11-14T18:22:41-05:00",
  "livemode": false,
  "data": {
    "object": {
      "id": "bk_5d2e8a41c07f4b9e",
      "object": "booking",
      "kind": "transfer",
      "code": "TEST-000001",
      "livemode": false,
      "status": "new",
      "payment_status": "paid",
      "payment_url": "https://api.muvon.mx/pay/r/3c9f0b7e6a5d4c2b1a09f8e7d6c5b4a3",
      "hold_expires_at": null,
      "external_ref": "ORDER-5521",
      "service_type": "airport_pickup",
      "pickup_at": "2026-12-20T14:30:00-05:00",
      "pickup": {
        "place_id": "pl_cun",
        "name": "Cancun Airport (CUN)",
        "address": null
      },
      "dropoff": {
        "place_id": "pl_hotel52",
        "name": "Hotel 52 Playa del Carmen",
        "address": null
      },
      "hours": null,
      "vehicle_type_id": "vt_sedan",
      "passengers": {
        "adults": 2,
        "children": 1
      },
      "bags": 3,
      "extras": [
        {
          "code": "BOOSTER_SEAT",
          "quantity": 1,
          "price_cents": 1000
        }
      ],
      "flight_number": "AA1234",
      "room": null,
      "notes": "Viajamos con una carriola",
      "passenger": {
        "first_name": "Ana",
        "last_name": "García",
        "email": "ana@example.com",
        "phone": "+5215512345678",
        "language": "es"
      },
      "price_cents": 9500,
      "currency": "USD",
      "commission_cents": 950,
      "tracking_url": "https://api.muvon.mx/track?t=a1b2c3d4e5f6",
      "cancel_reason": null,
      "created_at": "2026-11-14T18:10:00-05:00",
      "updated_at": "2026-11-14T18:22:41-05:00"
    }
  }
}