import \{ Callout } from 'nextra/components'

Pre-Order Information & Estimates

Before creating an order, you must use the aggregated preorder endpoint to gather all essential pre-order information. This single endpoint provides everything you need to present booking options to your customers and make informed decisions.

Get Aggregated Pre-Order Information

The aggregated preorder endpoint is your one-stop solution for retrieving comprehensive pre-order data, including:

Service Availability - Which services are currently available for your route
Service Capabilities - Passenger and luggage capacity for each service tier
Estimated Prices - Real-time pricing with currency formatting
Expected Arrival Time - ETA ranges for driver pickup

This endpoint provides all the information needed to present complete booking options to your users.

Endpoint

GET https://api.gett.com/v1/private/preorder/aggregated

Headers

Content-Type: application/json
Authorization: Bearer {your_token}

Query Parameters

Parameter	Type	Required	Description
`partner_id`	string	Yes	Your partner ID provided by Gett

Request Body

Parameter	Type	Required	Description
`stops`	array	Yes	Array of stop objects defining the route
`stops[].type`	string	Yes	Type of stop: `origin`, `destination`, or `on_going`
`stops[].location`	object	Yes	Location coordinates
`stops[].location.lat`	float	Yes	Latitude coordinate
`stops[].location.lng`	float	Yes	Longitude coordinate
`scheduled_at`	string	No	Pickup time in ISO8601 format (e.g., `2025-09-28T13:35:00Z`)
`category`	string	Yes	Service category: `transportation` or `delivery`
`locale`	string	Yes	Language code (e.g., `en`, `es`, `fr`)
`payment_type`	string	Yes	Payment method: `cash` (only option for partners)

Example Request

curl --location 'https://api.gett.com/v1/private/preorder/aggregated?partner_id=1f4c281e-b3eb-4676-beb7-b3a61caba0e6' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {token}' \
  --data '{
    "stops": [
      {
        "type": "origin",
        "location": {
          "lat": 51.473401, 
          "lng": -0.0221145
        }
      },
      {
        "type": "destination",
        "location": {
          "lat": 51.4712475, 
          "lng": 0.0357987
        }
      }
    ],
    "category": "transportation",
    "locale": "en",
    "payment_type": "cash"
  }'

Example Response

{
  "routes": [
    {
      "uuid": "c41116f6-697c-4799-80e6-af0953a61b00",
      "provider": "google",
      "polyline": "mldyHdgCa@PK?_@Mw@iAG?U[Da@HUN_@Xs@p@yBf@eBj@iCXiBRwCJmBDk@@i@?aBA_ACaAB{@H_ANSh@eBb@qAPw@Fm@F{@?yAIaCWeFe@uHEoBFeCLcBPmCAM@_@D_@D{@VgDd@wGN}@^{FPmCDkBCwBMmE_Cmb@k@mKIqAG_@YmAO[IUASBUFMHi@J_AC]u@mMe@iIKoBEKCGSoCGw@@m@@OIcAa@_IWcFIoAK}AKYK_AKkAg@eFi@cGO{@EGKCWUKWIi@?a@Fg@LY@k@@q@SgBWmDYqEI{EAsDHmBTEtB]jAORFJNP^DNbBoAdBiAtBwAnA{@jBiAz@_@`Ac@EYm@qE]gDEq@O_E",
      "scheduled_at": "2025-10-06T10:34:43Z",
      "distance": 4624,
      "duration": 703,
      "duration_unit": "s",
      "distance_unit": "m",
      "selected_route": true,
      "label": ["manual"]
    }
  ],
  "product_with_prices": [
    {
      "product": {
        "product_id": "74352801-2d3d-4235-966e-11e07b0e076a",
        "name": "Guest Booking",
        "icon": "https://static.gett.com/services/media/media_files/28207/uk_black-cab__1.png",
        "description": "Iconic, spacious black cabs with 5 or 6 seats that can cut through traffic using the bus lanes to get you to your destination faster",
        "eta_sec": 206,
        "eta_description": "Under 4 min",
        "booking_settings": {
          "on_demand": {
            "allowed": true
          },
          "pre_book": {
            "allowed": true,
            "pre_book_in_advance_min": 30,
            "edit_enabled": true,
            "edit_before_scheduled_at_min": 30,
            "destination_mandatory": false
          },
          "stops": {
            "mandatory_origin": true,
            "mandatory_destination": false,
            "ongoing_stops": {
              "allowed": true,
              "max_ongoing_stops": 3
            }
          },
          "multi_riders": {
            "allowed": true,
            "max_tracked_riders": 5
          },
          "max_available_seats": 5,
          "note_to_driver": {
            "allowed": true,
            "mandatory": false
          }
        }
      },
      "price": {
        "pricing_options": [
          {
            "estimation_id": "6f1caae3-d3fa-4b18-992f-ae0a374acfab",
            "price_concept": "meter_range",
            "calculated_as": "meter",
            "include_vat": true,
            "currency": "£",
            "currency_iso": "GBP",
            "tech_fee": {
              "applicable": false,
              "value": 0
            },
            "additional_fee": [
              {
                "name": "driving",
                "value": "18.6",
                "min": 17,
                "max": 20
              }
            ],
            "properties": [
              {
                "name": "meter_total",
                "min": 17,
                "max": 20,
                "is_range": true,
                "amount": "18.6",
                "percentage": null
              }
            ]
          }
        ]
      },
      "eta_to_destination": "0001-01-01T00:00:00Z"
    }
  ]
}

Understanding the Pre-Order Response

The aggregated response provides four critical pieces of information through two main sections:

Routes Section

Contains route and journey information:

Route Details: Distance (in meters), duration (in seconds), and route polyline
Scheduling: Confirmation of scheduled pickup time
Provider: Route calculation provider (e.g., Google)

Product with Prices Section

Contains available services and their details:

1. Service Availability

Each product includes booking settings that indicate availability:

On Demand: Whether immediate booking is allowed
Pre-book: Whether advance booking is allowed with minimum advance time
Stops Configuration: Maximum ongoing stops and destination requirements

2. Service Capabilities

Detailed service capabilities in booking_settings:

max_available_seats: Maximum passenger capacity
max_ongoing_stops: Maximum intermediate stops allowed
max_tracked_riders: Maximum riders that can be tracked
note_to_driver: Whether driver notes are supported

3. Estimated Prices

Pricing information in the price.pricing_options array:

estimation_id: Unique quote identifier used as quote_id when creating orders
price_concept: Pricing model - meter, meter_range, or fixed_price
- meter: Final price calculated by taxi meter (estimate may be 0 or minimal)
- meter_range: Final price calculated by meter, with estimated range provided (min/max values)
- fixed_price: Price is committed when you create the order using this estimation_id as quote_id
calculated_as: Method used to calculate the price (e.g., "meter", "distance")
currency & currency_iso: Currency symbol and ISO code
include_vat: Whether VAT is included in pricing
tech_fee: Technology fee details and applicability
additional_fee: Additional fees with min/max ranges (for meter_range pricing)
properties: Pricing breakdown with amounts and ranges
- is_range: Indicates if the price includes min/max estimates
- min & max: Price range boundaries (for meter_range)
- amount: Estimated or fixed price amount

Price Commitment: When price_concept is fixed_price, providing the estimation_id as quote_id in your order creation request commits the displayed price. For meter or meter_range pricing, the quote_id is still required but the final price will be determined by the taxi meter.

4. Expected Arrival Time (ETA)

Driver pickup time estimates:

eta_sec: ETA in seconds from booking
eta_description: Human-readable ETA description
eta_to_destination: Estimated arrival time at destination

Service Details

Additional service information:

product_id: Unique identifier for booking
name & description: Service display information
icon: Service icon URL for UI display

Always call the aggregated endpoint before creating orders. Prices, availability, and ETAs can change rapidly. Never attempt to create an order without first getting current pre-order information.

Pricing Types

The aggregated response includes pricing information with different pricing models:

Meter Pricing

When price_concept is "meter" or "meter_range", the price shown is an estimate only:

Simple Meter Pricing:

{
  "estimation_id": "4f3cc8ba-b24e-42d9-aef8-3ce528f603fd",
  "price_concept": "meter",
  "calculated_as": "meter",
  "properties": [
    {
      "name": "meter_total",
      "amount": "0",
      "is_range": false
    }
  ]
}

Meter Range Pricing (with estimated range):

{
  "estimation_id": "6f1caae3-d3fa-4b18-992f-ae0a374acfab",
  "price_concept": "meter_range",
  "calculated_as": "meter",
  "additional_fee": [
    {
      "name": "driving",
      "value": "18.6",
      "min": 17,
      "max": 20
    }
  ],
  "properties": [
    {
      "name": "meter_total",
      "min": 17,
      "max": 20,
      "is_range": true,
      "amount": "18.6"
    }
  ]
}

The estimation_id must be provided as quote_id when creating the order
The final price will be calculated by the taxi meter during the ride
For meter_range, the displayed range (min/max) and estimated amount are for reference only
The actual fare may differ from the estimate

Fixed Price

When price_concept is "fixed_price", the price is committed when you create the order:

{
  "estimation_id": "1a22584a-9685-4153-a629-271ebc34dcda",
  "price_concept": "fixed_price",
  "calculated_as": "distance",
  "properties": [
    {
      "name": "fixed_total",
      "amount": "25.50",
      "is_range": false
    }
  ]
}

Providing the estimation_id as quote_id locks in the displayed price
The customer pays exactly the amount shown, regardless of route changes
Price is guaranteed at order creation time

Fixed Price Advantage: When fixed_price is available, using the quote_id guarantees the exact fare to your customer, providing price certainty and transparency.

Integration Workflow

Required Pre-Order Flow

User selects route → Call aggregated endpoint
Display options → Show available services with prices, capacity, and ETAs
User selects service → Validate selection is still available
Create order → Use the product_id and estimation_id (as quote_id) from the aggregated response

When creating an order, you must provide the quote_id parameter with the value of estimation_id from the selected product's pricing_options array. For services with price_concept: "fixed_price", this commits the displayed price. For price_concept: "meter", the quote is required but the final price is determined by the taxi meter.

Best Practices

Real-time Updates

Cache pre-order data for maximum 2-3 minutes to balance performance and accuracy
Refresh automatically when route parameters change
Show users when information was last updated
Re-fetch before order creation if data is older than 2 minutes

Handling Availability Changes

async function getPreOrderInfo(routeData) {
  try {
    const response = await fetch(`/v1/private/preorder/aggregated?partner_id=${partnerId}`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(routeData)
    });

    if (!response.ok) {
      if (response.status === 400) {
        throw new Error('Invalid route parameters');
      } else if (response.status === 404) {
        throw new Error('No services available for this route');
      }
      throw new Error('Failed to get pre-order information');
    }

    const data = await response.json();
    
    // Check if we have products and routes
    if (!data.product_with_prices || data.product_with_prices.length === 0) {
      throw new Error('No services currently available for this route');
    }

    if (!data.routes || data.routes.length === 0) {
      throw new Error('No valid routes found for this request');
    }

    // Filter products that allow the requested booking type
    const availableServices = data.product_with_prices.filter(item => {
      const isOnDemand = !routeData.scheduled_at;
      if (isOnDemand) {
        return item.product.booking_settings.on_demand?.allowed;
      } else {
        return item.product.booking_settings.pre_book?.allowed;
      }
    });
    
    if (availableServices.length === 0) {
      throw new Error('No services available for the requested booking type');
    }

    return {
      ...data,
      product_with_prices: availableServices
    };
  } catch (error) {
    console.error('Pre-order info request failed:', error);
    throw error;
  }
}

Multiple Stops

For routes with multiple stops, include all stops in the request:

{
  "stops": [
    {
      "type": "origin",
      "location": {
        "lat": 51.4988787,
        "lng": -0.020746
      }
    },
    {
      "type": "on_going",
      "location": {
        "lat": 51.4899,
        "lng": -0.0125
      }
    },
    {
      "type": "destination",
      "location": {
        "lat": 51.4712475,
        "lng": 0.0357987
      }
    }
  ]
}

Essential Integration Requirements

Mandatory Pre-Order Check: You must call the aggregated endpoint for every booking attempt. This is not optional - it's required to ensure service availability and get current pricing.

Critical Implementation Points

Always Check All Four Aspects:
- ✅ Service availability before showing options
- ✅ Service capabilities to match user needs
- ✅ Current prices for accurate billing
- ✅ Real ETAs for user expectations
User Experience Guidelines:
- Display all available service tiers with clear capability differences
- Show real-time ETAs to set proper expectations
- Update information when route changes
- Handle "no services available" scenarios gracefully
Technical Requirements:
- Never cache pre-order data longer than 2-3 minutes
- Always validate selected service is still available before order creation
- Implement proper loading states during API calls
- Handle network failures and API errors appropriately

Complete Integration Example

class BookingFlow {
  async displayBookingOptions(origin, destination, scheduledTime) {
    // Step 1: Get all pre-order information
    const preOrderData = await this.getPreOrderInfo({
      stops: [
        { type: 'origin', location: origin },
        { type: 'destination', location: destination }
      ],
      scheduled_at: scheduledTime,
      category: 'transportation',
      locale: 'en',
      payment_type: 'cash'
    });

    // Step 2: Extract route information
    const selectedRoute = preOrderData.routes.find(route => route.selected_route) || preOrderData.routes[0];
    const routeInfo = {
      distance: `${(selectedRoute.distance / 1000).toFixed(1)} km`,
      duration: `${Math.round(selectedRoute.duration / 60)} min`,
      scheduledAt: selectedRoute.scheduled_at
    };

    // Step 3: Process available services
    const availableServices = preOrderData.product_with_prices.filter(item => {
      const isOnDemand = !scheduledTime;
      return isOnDemand 
        ? item.product.booking_settings.on_demand?.allowed
        : item.product.booking_settings.pre_book?.allowed;
    });

    if (availableServices.length === 0) {
      throw new Error('No services available for this route at this time');
    }

    // Step 4: Format service options for display
    return availableServices.map(item => {
      const product = item.product;
      const pricing = item.price.pricing_options[0];
      
      return {
        id: product.product_id,
        name: product.name,
        description: product.description,
        icon: product.icon,
        eta: product.eta_description,
        etaSeconds: product.eta_sec,
        maxSeats: product.booking_settings.max_available_seats,
        maxOngoingStops: product.booking_settings.stops.ongoing_stops.max_ongoing_stops,
        pricing: {
          concept: pricing.price_concept,
          currency: pricing.currency,
          currencyIso: pricing.currency_iso,
          includeVat: pricing.include_vat,
          techFee: pricing.tech_fee
        },
        bookingSettings: product.booking_settings,
        routeInfo: routeInfo
      };
    });
  }

  async createOrderWithValidation(selectedProductId, orderData) {
    // Re-validate availability before creating order
    const currentInfo = await this.getPreOrderInfo(orderData.routeInfo);
    const selectedProduct = currentInfo.product_with_prices.find(
      item => item.product.product_id === selectedProductId
    );

    if (!selectedProduct) {
      throw new Error('Selected service is no longer available');
    }

    // Check booking type availability
    const isOnDemand = !orderData.scheduled_at;
    const bookingAllowed = isOnDemand 
      ? selectedProduct.product.booking_settings.on_demand?.allowed
      : selectedProduct.product.booking_settings.pre_book?.allowed;

    if (!bookingAllowed) {
      throw new Error('Selected booking type is not available for this service');
    }

    // Get the estimation_id (quote_id) from the pricing options
    const quoteId = selectedProduct.price.pricing_options[0].estimation_id;

    // Proceed with order creation using validated product_id and quote_id
    return await this.createOrder({
      ...orderData,
      product_id: selectedProductId,
      quote_id: quoteId
    });
  }

  formatPriceDisplay(pricingOptions) {
    const pricing = pricingOptions[0];
    
    // Handle meter pricing - show as estimate
    if (pricing.price_concept === 'meter') {
      return {
        displayText: `${pricing.currency} Metered pricing`,
        type: 'meter',
        isEstimate: true,
        note: 'Final price determined by taxi meter'
      };
    }
    
    // Handle meter range pricing - show range estimate
    if (pricing.price_concept === 'meter_range') {
      const mainProperty = pricing.properties.find(p => p.name.includes('total'));
      if (mainProperty && mainProperty.is_range) {
        return {
          displayText: `${pricing.currency}${mainProperty.min}-${mainProperty.max}`,
          estimatedAmount: `${pricing.currency}${mainProperty.amount}`,
          type: 'meter_range',
          isEstimate: true,
          note: 'Estimated range - final price determined by taxi meter'
        };
      }
    }
    
    // Handle fixed pricing - show exact amount
    if (pricing.price_concept === 'fixed_price') {
      const mainProperty = pricing.properties.find(p => p.name.includes('total'));
      if (mainProperty && mainProperty.amount !== "0") {
        return {
          displayText: `${pricing.currency}${mainProperty.amount}`,
          type: 'fixed_price',
          isEstimate: false,
          note: 'Price guaranteed at booking'
        };
      }
    }
    
    // Fallback for other pricing types
    return {
      displayText: `${pricing.currency} Variable pricing`,
      type: 'variable',
      isEstimate: true,
      note: 'Contact support for pricing details'
    };
  }
}