Order Management

This section covers the complete lifecycle of managing orders through the Gett B2C API, from creation to cancellation.

Creating Orders

Endpoint

POST https://api.gett.com/v1/private/orders/create

Headers

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

Request Parameters

Parameter	Type	Required	Description
`partner_id`	string	Yes	Your partner ID provided by Gett
`product_id`	string	Yes	Product ID from pricing response or provided by Gett
`quote_id`	string	Yes	Estimation ID from the aggregated call response. This commits the price for the journey when `price_concept` is `fixed_price`. For `meter` pricing, the final price is calculated by the meter
`user_accepted_terms_and_privacy`	boolean	Yes	Must be `true` - indicates user accepted T&C
`category`	string	Yes	Service category: `transportation` or `delivery`
`lc`	string	No	Language code: `en` (English) or `he` (Hebrew)
`scheduled_at`	string	No	Pickup time in ISO8601 format. Omit for immediate booking
`stops`	array	Yes	Array of stop objects (minimum 2: origin and destination)
`payment`	object	Yes	Payment configuration
`preferences`	object	No	Additional preferences for the order

Stop Object Structure

Parameter	Type	Required	Description
`type`	string	Yes	Stop type: `origin`, `on_going`, or `destination`
`actions`	array	Yes	Array of action objects for this stop
`location`	object	Yes	Location details

Action Object Structure

Parameter	Type	Required	Description
`type`	string	Yes	Action type: `pick_up`, `drop_off`, or `stop_by`
`user`	object	Yes	User information
`user.name`	string	Yes	Passenger name
`user.phone`	string	Yes	Phone number in international format (without +)

Location Object Structure

Parameter	Type	Required	Description
`lat`	float	Yes	Latitude coordinate
`lng`	float	Yes	Longitude coordinate
`full_address`	string	No	Complete address string
`address`	object	No	Detailed address breakdown

Address Object Structure (Optional)

Parameter	Type	Required	Description
`house`	string	No	House/building number
`street`	string	No	Street name
`city`	string	No	City name
`state`	string	No	State/province name
`country`	string	No	Country name
`postcode`	string	No	Postal/ZIP code
`notes`	string	No	Special delivery notes for driver
`address_place`	object	No	Address provider information

Example Request

curl --request POST 'https://api.gett.com/v1/private/orders/create' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {your_token}' \
  --data '{
    "partner_id": "1f4c281e-b3eb-4676-beb7-b3a61caba0e6",
    "product_id": "economy",
    "quote_id": "1a22584a-9685-4153-a629-271ebc34dcda",
    "user_accepted_terms_and_privacy": true,
    "category": "transportation",
    "lc": "en",
    "scheduled_at": "2024-10-01T13:50:00+03:00",
    "stops": [
      {
        "type": "origin",
        "actions": [
          {
            "type": "pick_up",
            "user": {
              "name": "John Doe",
              "phone": "447700123456"
            }
          }
        ],
        "location": {
          "lat": 51.4988787,
          "lng": -0.020746,
          "full_address": "London Bridge Station, London, UK",
          "address": {
            "street": "Railway Approach",
            "city": "London",
            "postcode": "SE1 9SP",
            "country": "United Kingdom"
          }
        }
      },
      {
        "type": "destination",
        "actions": [
          {
            "type": "drop_off",
            "user": {
              "name": "John Doe",
              "phone": "447700123456"
            }
          }
        ],
        "location": {
          "lat": 51.4712475,
          "lng": 0.0357987,
          "full_address": "Canary Wharf Station, London, UK",
          "address": {
            "street": "Heron Quays",
            "city": "London",
            "postcode": "E14 4JB",
            "country": "United Kingdom"
          }
        }
      }
    ],
    "payment": {
      "payment_type": "cash"
    },
    "preferences": {
      "num_of_passengers": 1,
      "num_of_suitcases": 1
    }
  }'

Example Response

{
  "ride_request_id": "67a4cc3a-d9e5-430c-862f-b134c22035c7",
  "status": "success",
  "order": {
    "id": "72576544"
  }
}

Order Flows

Immediate Booking

For immediate pickup, omit the scheduled_at parameter:

{
  "partner_id": "your-partner-id",
  "product_id": "economy",
  "user_accepted_terms_and_privacy": true,
  "category": "transportation",
  "stops": [...],
  "payment": {
    "payment_type": "cash"
  }
}

Scheduled Booking

For future pickup, include scheduled_at:

{
  "partner_id": "your-partner-id",
  "product_id": "economy",
  "user_accepted_terms_and_privacy": true,
  "category": "transportation",
  "scheduled_at": "2024-10-01T13:50:00+03:00",
  "stops": [...],
  "payment": {
    "payment_type": "cash"
  }
}

Multi-Stop Journey

For routes with intermediate stops:

{
  "stops": [
    {
      "type": "origin",
      "actions": [
        {
          "type": "pick_up",
          "user": {
            "name": "John Doe",
            "phone": "447700123456"
          }
        }
      ],
      "location": {...}
    },
    {
      "type": "on_going",
      "actions": [
        {
          "type": "stop_by",
          "user": {
            "name": "John Doe",
            "phone": "447700123456"
          }
        }
      ],
      "location": {...}
    },
    {
      "type": "destination",
      "actions": [
        {
          "type": "drop_off",
          "user": {
            "name": "John Doe",
            "phone": "447700123456"
          }
        }
      ],
      "location": {...}
    }
  ]
}

Canceling Orders

Endpoint

POST https://api.gett.com/v1/private/orders/cancel/{order_id}

Query Parameters

Parameter	Type	Required	Description
`partner_id`	string	Yes	Your partner ID

Example Request

curl --request POST 'https://api.gett.com/v1/private/orders/cancel/500475?partner_id=1f4c281e-b3eb-4676-beb7-b3a61caba0e6' \
  --header 'Authorization: Bearer {your_token}' \
  --header 'Content-Type: application/json'

Example Response

Success (204 No Content):

HTTP/1.1 204 No Content

The API returns a 204 No Content status code for successful cancellations with an empty response body.

Handling Cancellation Response

async function cancelOrder(orderId, partnerId) {
  try {
    const response = await fetch(
      `https://api.gett.com/v1/private/orders/cancel/${orderId}?partner_id=${partnerId}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    );

    if (response.status === 204) {
      console.log('Order cancelled successfully');
      return { success: true, cancelled: true };
    } else if (response.status === 404) {
      throw new Error('Order not found');
    } else if (response.status === 400) {
      throw new Error('Order cannot be cancelled (may already be in progress)');
    } else {
      throw new Error(`Cancellation failed with status: ${response.status}`);
    }

  } catch (error) {
    console.error('Order cancellation failed:', error.message);
    throw error;
  }
}

Getting Order Details

Endpoint

GET https://api.gett.com/v1/private/orders/{order_id}

Query Parameters

Parameter	Type	Required	Description
`partner_id`	string	Yes	Your partner ID

Example Request

curl --request GET 'https://api.gett.com/v1/private/orders/72576544?partner_id=1f4c281e-b3eb-4676-beb7-b3a61caba0e6' \
  --header 'Authorization: Bearer {your_token}' \
  --header 'Content-Type: application/json'

Example Response

{
  "order": {
    "order_id": "72576544",
    "status": "Confirmed",
    "type": "private",
    "source": "api",
    "product": {
      "uuid": "f765c6a7-7c14-48a0-b247-de0882880846",
      "category": "transportation",
      "name": "b2c bc taxi butler"
    },
    "payment": {
      "payment_type": "cash"
    },
    "pricing": {
      "quote_id": null
    },
    "note_to_driver": "",
    "scheduled_at": "2025-10-06T10:26:48+01:00",
    "created_at": "2025-10-06T10:26:48+01:00",
    "rides": {
      "full_ride": {
        "stops": [
          {
            "uuid": "5f0a5e5b-8736-4c9f-b27e-674b15c6275f",
            "type": "origin",
            "progress_status": "Confirmed",
            "location": {
              "lat": 51.50665859,
              "lng": -0.1442844643,
              "type": "street_address",
              "address": {
                "full_address": "Flemings Mayfair Hotel, 7-12 Half Moon St, London W1J 7BH, United Kingdom",
                "city": "London",
                "house": "1-5",
                "state": "England",
                "street": "Clarges Street",
                "country": "United Kingdom",
                "postcode": "W1J 8AB",
                "notes": null
              },
              "address_place": null,
              "is_airport": false
            },
            "actions": [
              {
                "type": "pick_up",
                "user": {
                  "name": "John D",
                  "phone": "447700123456"
                },
                "status": "pending_pickup"
              }
            ]
          },
          {
            "uuid": "74c140cf-0360-4146-b70f-b8f70adeed5f",
            "type": "destination",
            "progress_status": "Pending",
            "location": null,
            "actions": [
              {
                "type": "drop_off",
                "user": {
                  "name": "John D",
                  "phone": "447700123456"
                },
                "status": "pending_drop_off"
              }
            ]
          }
        ]
      }
    },
    "actual": {
      "supplier": {
        "fleet": {
          "name": "Gett UK",
          "phone": "442073974300",
          "pickup_instructions": null
        },
        "driver": {
          "driver_id": 1234567,
          "driver_name": "John Smith",
          "driver_phone": "+447700987654",
          "car_model": "TXE (6 Seater)",
          "car_color": "Black",
          "plate_number": "AB12CDE",
          "photo_url": "https://example.com/driver-photo.jpg",
          "rating": 5,
          "license": {
            "number": ""
          },
          "location": {
            "lat": 51.5079095284033,
            "lon": -0.1440413978223828,
            "bearing": 52.67864227294922
          }
        }
      },
      "will_arrive_at": "2025-10-06T10:30:12+01:00",
      "arrived_at": null,
      "started_at": null,
      "ended_at": null,
      "cancelled_at": null,
      "cancelled_by": null,
      "ride_start_pin_code": null
    },
    "flight": null,
    "preferences": null
  },
  "route_info": {
    "eta_to_destination_minutes": 2,
    "distance_to_destination": {
      "unit": "meter",
      "value": 549.9008388675134
    }
  },
  "droppedoff_at": null
}

Order Status Tracking

Orders go through various states throughout their lifecycle:

Order Status Values

Status	Description
`Pending`	Order created, awaiting processing
`Reserved`	Future order scheduled, not yet dispatched (driver is not yet on the way)
`Unreserved`	Future order unreserved, released from schedule
`Routing`	Looking for driver
`Confirmed`	Driver is on the way to pickup
`Waiting`	Driver is waiting at pickup location
`Driving`	Order is progressing (passenger on board)
`Completed`	Order is completed
`Cancelled`	Order is cancelled
`Rejected`	Failed to find a driver
`CareReq`	Support team is manually handling the order

Action Status Values

Each stop action also has its own status:

Status	Description
`pending_pickup`	Waiting for passenger pickup
`pending_drop_off`	Waiting for passenger drop-off
`completed`	Action completed successfully

Tracking Information

The response provides comprehensive tracking data:

Driver Information: Name, phone, vehicle details, current location
ETA Updates: Real-time arrival estimates
Progress Status: Current status of each stop
Route Information: Distance and time to destination
Timestamps: Created, scheduled, arrival, start, and end times

📘
Webhook Notifications
Contact Gett support for details on webhook notifications for real-time order status updates.

Best Practices

Validation Before Creation

Verify Locations: Ensure coordinates are valid and reachable
Check Phone Numbers: Validate phone numbers are in international format
Confirm Terms Acceptance: Always ensure user_accepted_terms_and_privacy is true
Product Availability: Use recent pricing data to select available products

Error Handling

async function createOrder(orderData) {
  try {
    const response = await fetch('/v1/private/orders/create', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(orderData)
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch(response.status) {
        case 400:
          throw new Error(`Invalid request: ${error.message}`);
        case 402:
          throw new Error('Payment required or insufficient funds');
        case 404:
          throw new Error('Product not available');
        case 422:
          throw new Error('Validation failed: check your parameters');
        default:
          throw new Error('Order creation failed');
      }
    }

    return await response.json();
  } catch (error) {
    console.error('Order creation failed:', error);
    throw error;
  }
}

Cancellation Policy

Orders can typically be cancelled free of charge within a few minutes of creation
Cancellation fees may apply for last-minute cancellations
Some orders cannot be cancelled once a driver is assigned and en route

❗️
Cancellation Policies
Check with Gett for specific cancellation policies and fee structures for your integration.

Order Management

Order Management

Creating Orders

Endpoint

Headers

Request Parameters

Stop Object Structure

Action Object Structure

Location Object Structure

Address Object Structure (Optional)

Example Request

Example Response

Order Flows

Immediate Booking

Scheduled Booking

Multi-Stop Journey

Canceling Orders

Endpoint

Query Parameters

Example Request

Example Response

Handling Cancellation Response

Getting Order Details

Endpoint

Query Parameters

Example Request

Example Response

Order Status Tracking

Order Status Values

Action Status Values

Tracking Information

📘
Webhook Notifications

Best Practices

Validation Before Creation

Error Handling

Cancellation Policy

❗️
Cancellation Policies

Order Management

Creating Orders

Endpoint

Headers

Request Parameters

Stop Object Structure

Action Object Structure

Location Object Structure

Address Object Structure (Optional)

Example Request

Example Response

Order Flows

Immediate Booking

Scheduled Booking

Multi-Stop Journey

Canceling Orders

Endpoint

Query Parameters

Example Request

Example Response

Handling Cancellation Response

Getting Order Details

Endpoint

Query Parameters

Example Request

Example Response

Order Status Tracking

Order Status Values

Action Status Values

Tracking Information

📘Webhook Notifications

Best Practices

Validation Before Creation

Error Handling

Cancellation Policy

❗️Cancellation Policies

📘
Webhook Notifications

❗️
Cancellation Policies