Broker API

Search Surprice stations, price vehicles for your rate codes, and create, amend or cancel car-rental reservations over a JSON REST API.

REST + JSON
Bearer API key
17 endpoints
Version 1

Authenticate your requestsHeaders, date formats and request conventions
Follow the booking flowFrom station search to a committed reservation
Handle errors and retriesHTTP statuses, business codes and safe retries

Sample reservationCORP-EXAMPLE-001

PickupHER10 May, 12:00

ReturnHER15 May, 12:00

Vehicle: ECMR
Rate code: EXAMPLE_RATE
Status: committed

Built from the examples on this page.

All endpoints

Method	Endpoint	Purpose
GET	`/v1/location/search`	Find stations
GET	`/v1/location/details`	Station details and policies
GET	`/v1/rateCodes`	Broker rate codes
POST	`/v1/availability`	Availability for one rate code
POST	`/v1/getRate`	Verify quoted pricing
POST	`/v1/reservation`	Create a reservation
GET	`/v1/reservation/:orderId`	Read a reservation
PUT	`/v1/reservation/:orderId/amend`	Amend a reservation
PUT	`/v1/reservation/:orderId/commit`	Accept a pending amendment
PUT	`/v1/reservation/:orderId/ignore`	Discard a pending trip change
PUT	`/v1/reservation/:orderId/cancel`	Cancel a reservation
GET	`/v1/location/extras`	Station extras catalog
GET	`/v1/location/insurances`	Station insurance catalog
GET	`/v1/cities`	List cities
GET	`/v1/countries`	List countries
GET	`/v1/sipp-info`	SIPP reference
GET	`/status`	Service health

Examples show demo values and optional fields. Replace them with your account details and values returned by the API. Optional fields may be absent; unavailable values may be null and arrays may be empty.

Authentication and conventions#

Use your assigned base URL and active broker API key. All endpoints except /status require:

Request headers

Authorization: Bearer <BROKER_API_KEY>
Accept: application/json
Content-Type: application/json

Use Bearer with this exact casing and an active API key.

cURL · POSIX shell

curl "$BASE_URL/v1/rateCodes" \
  --header "Authorization: Bearer $BROKER_API_KEY" \
  --header 'Accept: application/json'

POST/PUT bodies must be JSON objects. Use the documented field names and types; unknown fields can be rejected.

Dates: rental requests use YYYY-MM-DDTHH:mm:ss without a timezone suffix or milliseconds. Use the station’s local time. Reservation GET returns YYYY-MM-DD HH:mm:ss; change the space to T before reusing it. Birth and license dates use YYYY-MM-DD.

Extended location codes are optional; include them to narrow the station match.

Booking flow#

vendorRateID valid for 20 minutesCovers steps 02 to 04

Price guaranteedVehicle not held

Stations & ratesPolicies · Rate codes
AvailabilitySelect an offer & extras
Verify pricinggetRate · optional
Create bookingStatus: committed
GET bookingUse the stored corporateOrderId

Rate expired or vehicle gone?A vendorRateID expires after 20 minutes, and vehicles can sell out sooner. Request availability again and use the new quote’s vendorRateID.

Availability and getRate do not hold stock. A quote’s price is guaranteed for 20 minutes through its vendorRateID.

How long a quote holds

Every availability offer comes with a vendorRateID. It locks the price for 20 minutes, but not the car.

Price

Guaranteed

Expired

Vehicle

Not held, can sell out any time

Quote received+20 min

Within 20 minutes, book with the offer’s vendorRateID and you get the quoted price.
The vehicle isn’t reserved. Fleet availability changes all the time, so it can sell out before you book, even inside the 20 minutes. If booking fails, request availability again.
After 20 minutes, the vendorRateID expires. Request availability again and book with the new one.

To create a booking, use the same pickup and return stations, dates and times as the selected availability offer. Copy its rateCode and vendorRateID, and include promotionCode if one was used. Add the customer’s details and, optionally, your own unique brokerOrderId. Store the corporateOrderId returned in the booking response, which is Surprice’s reservation number, together with your brokerOrderId; use either reference to retrieve, amend or cancel the booking.

Booking references

Every booking response carries three identifiers. Store corporateOrderId: it is Surprice’s reservation number.

corporateOrderIdStore this

Surprice’s reservation number. Keep it with the booking and use it as :orderId to read, amend, commit, ignore or cancel.

CORP-EXAMPLE-001

brokerOrderIdYour reference

Your own unique booking reference, sent on create or generated if omitted. Also accepted as :orderId.

BROKER-EXAMPLE-001

orderInfo.idCan change

Record UUID. It can change after an update, so don’t keep it as the booking’s reference.

11111111-1111-…

Amendment flow

Dates/times or vehicle group changependingReview the returned offer

CommitorIgnore

Other accepted changescommittedApplied immediately

GET the latest booking after either path

After an amendment, check ammendedOrderInfo.status: pending requires commit or ignore; committed is already applied.

Reservation statuses

A booking is always in one of four statuses. The diagram shows which call moves it from one to the next.

Every transition is only possible before pickup. Cancel needs a committed booking, so resolve a pending amendment first. Pending amendments can expire.

Find stations#

GET/v1/location/search

Find active stations matching all supplied filters.

Request

GET /v1/location/search?locationCode=HER&limit=20&offset=0

Field	Type / requirement	Use
`locationCode / extendedLocationCode`	Optional strings	Exact code filters.
`locationName`	Optional string	Case-insensitive name substring.
`stationId`	Optional string	Exact station ID; not included in the response.
`includeAllSchedules`	Optional boolean query	Default false: current seasonal schedules. True: all seasonal schedules.
`limit / offset`	Optional integers	See pagination.

200 response

{
  "limit": 20,
  "offset": 0,
  "total": 1,
  "results": [
    {
      "stationType": "Airport",
      "locationCode": "HER",
      "extendedLocationCode": "HERA01",
      "name": "Example station",
      "isMeetAndGreet": false,
      "address": {
        "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
        "city": "Heraklion",
        "postalCode": "71601",
        "country": {"code": "GR", "name": "Greece"},
        "coordinates": {"lat": 35.34, "lon": 25.18}
      },
      "telephone": "+30 2810 000000",
      "additionalInfo": {
        "text": "Meet our representative at the arrivals exit.",
        "operationTime": [
          {
            "days": ["Monday"],
            "schedule": {
              "from": "01/01",
              "to": "31/12",
              "normal": {"start": "08:00:00", "end": "22:00:00"},
              "extended": {"start": "22:00:00", "end": "23:59:00"}
            }
          }
        ]
      }
    }
  ]
}

Optional: additionalInfo.operationTime[].schedule.extended.

Schedule dates use DD/MM; times use HH:mm:ss.

No matches or an empty page returns 404, code 168.

Station details and policies#

GET/v1/location/details

Get station details, pickup instructions, opening hours and policies.

Request

GET /v1/location/details?locationCode=HER&extendedLocationCode=HERA01&translation_lang=en

Field	Type / requirement	Use
`locationCode`	Required nonempty string	Station location code.
`extendedLocationCode`	Optional string	Narrows the station match when supplied.
`translation_lang`	Optional string	Language code: 2–10 letters/hyphens. Missing translations use default text.

200 response

{
  "locationDetail": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "policies": [
    {"type": "DRIVER_REQUIREMENTS", "text": "Example policy: present a valid driving licence at pickup."}
  ]
}

Optional: locationDetail.additionalInfo.operationTime[].schedule.extended.

Station details returns the current seasonal schedule. Use availability for schedules matching your pickup and return dates.

200 details · 404: code 229 station missing/inactive; 656 or 383 station details unavailable

Broker rate codes#

GET/v1/rateCodes

Get your active rate codes. No parameters or pagination.

200 response

[
  {
    "id": "22222222-2222-4222-8222-222222222222",
    "rate_code": "EXAMPLE_RATE",
    "is_retail": false,
    "is_domestic": false,
    "insurance_extra_id": "CDW",
    "prevent_promo_code": false
  }
]

What a rate code combines

Rate codeEXAMPLE_RATE

PaymentPrepaidorPay on arrival

CoverageCDWorFDWfor examplefrom insurance_extra_id

Each rate code is either prepaid or pay on arrival. On a pay-on-arrival rate code, rateTotalAmount is not prepaid either.
Each rate code comes with one coverage, such as CDW or FDW, and only rates relevant to it are returned. It appears as the base rentalRate.insurance in availability.

Use the returned rate_code as rateCode in subsequent availability, getRate and booking requests. prevent_promo_code indicates promotion restrictions. Availability checks eligibility for the trip. No assigned rates returns [].

Availability for one rate code#

POST/v1/availability

Find available vehicles and prices for one rate code.

Request body

{
  "pickUpDateTime": "2027-05-10T12:00:00",
  "returnDateTime": "2027-05-15T12:00:00",
  "pickUpLocationCode": "HER",
  "pickUpExtendedLocationCode": "HERA01",
  "returnLocationCode": "HER",
  "returnExtendedLocationCode": "HERA01",
  "rateCode": "EXAMPLE_RATE",
  "driverAge": 35,
  "returnExtras": true,
  "promotionCode": "EXAMPLE10",
  "vehicleGroupsPrefAccriss": [
    "ECMR"
  ],
  "vehicleGroupsPrefCode": [
    "ECONOMY"
  ],
  "currencyCode": "EUR",
  "mileagePolicy": "LIM"
}

Field	Type / requirement	Use
`pickUpDateTime / returnDateTime`	Required strings	Use the rental datetime format. Pickup cannot be past; return cannot precede pickup. Use a positive duration.
`pickUpLocationCode / returnLocationCode`	Required nonempty strings	Station codes; different stations require an allowed one-way route.
`pickUpExtendedLocationCode / returnExtendedLocationCode`	Optional strings	Narrow the pickup and return station matches when supplied.
`rateCode`	Required nonempty string	Broker rate code for this search. It sets the payment type (prepaid or pay on arrival) and coverage; see what a rate code combines.
`vehicleGroupsPrefAccriss`	Optional string array	Filter by SIPP codes.
`vehicleGroupsPrefCode`	Optional string array	Filter by vendor vehicle-group codes.
`driverAge`	Optional positive number	Main driver’s age for eligibility and surcharges.
`promotionCode`	Optional string	Promotion code; an empty string is treated as omitted.
`currencyCode`	Optional string	Three-letter currency code. See currency behavior.
`returnExtras`	Optional boolean	Default true. False omits optional extras and purchasable insurance lists.
`mileagePolicy`	Optional string	UNL for unlimited or LIM for limited mileage.

200 response

{
  "pickupStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "returnStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "productOfferings": [
    {
      "vehicle": {
        "airConditionInd": true,
        "code": "ECMR",
        "description": "Example economy car",
        "passengerQuantity": 5,
        "transmissionType": "Manual",
        "vendorCarType": "ECONOMY",
        "vehMakeModel": "Example economy car",
        "pictureURL": "https://example.com/vehicles/economy.jpg",
        "doorsNum": 5,
        "suitcasesNum": 2,
        "minDriverAge": 21,
        "maxDriverAge": 75,
        "youngDriverAge": 25,
        "oldDriverAge": 1,
        "sippCategoryId": "E",
        "sippTypeId": "C",
        "sippTransmissionId": "M",
        "sippFuelId": "R",
        "insuranceExcess": 900,
        "insuranceDeposit": 500,
        "thirdPartyLiability": true,
        "theftWaiver": true,
        "theftExcess": 900
      },
      "rentalDetails": [
        {
          "rentalRate": {
            "rateQualifier": {"rateCode": "EXAMPLE_RATE", "promotionCode": "EXAMPLE10", "vendorRateID": "EXAMPLE-VENDOR-RATE-001"},
            "mileagePolicy": {
              "distUnitName": "km",
              "unlimited": false,
              "vehiclePeriodUnitName": "per-day",
              "quantity": 200,
              "additionalMileageCost": 0.25,
              "totalIncludedMileage": 1000
            },
            "vehicleCharges": [
              {
                "currencyCode": "EUR",
                "detailedDescription": "",
                "guaranteedInd": true,
                "includedInEstTotalInd": true,
                "includedInRate": true,
                "purpose": 1,
                "taxInclusive": true,
                "isPrepaid": true,
                "amount": 150,
                "description": "Product Cost",
                "breakdown": [
                  {"amount": 120.97, "description": "Base Rental"},
                  {"amount": 29.03, "description": "VAT"}
                ],
                "calculationInfo": {"quantity": 5, "unitCharge": 30, "unitName": "Day"}
              },
              {
                "currencyCode": "EUR",
                "detailedDescription": "Example location surcharge",
                "guaranteedInd": true,
                "includedInEstTotalInd": true,
                "includedInRate": false,
                "purpose": 2,
                "taxInclusive": true,
                "isPrepaid": false,
                "amount": 20,
                "originalAmount": 25,
                "maxCost": 40,
                "discountValue": 5,
                "discountedQuantity": 1,
                "description": "EXAMPLE_FEE",
                "allowQuantity": false,
                "calculationInfo": {"quantity": 5, "unitCharge": 5, "unitName": "Day"}
              },
              {
                "currencyCode": "EUR",
                "detailedDescription": "",
                "guaranteedInd": true,
                "includedInEstTotalInd": false,
                "includedInRate": false,
                "purpose": 7,
                "taxInclusive": true,
                "isPrepaid": true,
                "amount": 26.13,
                "description": "VAT",
                "calculationInfo": {"quantity": 5, "unitCharge": 5.23, "unitName": "Day"}
              },
              {
                "currencyCode": "EUR",
                "detailedDescription": "",
                "guaranteedInd": true,
                "includedInEstTotalInd": true,
                "includedInRate": true,
                "purpose": 10,
                "taxInclusive": true,
                "amount": -15,
                "description": "Promo Code",
                "calculationInfo": {"quantity": 1, "unitCharge": -1, "unitName": "Rental", "amount": -10, "type": "percentage"}
              }
            ],
            "includedExtras": [
              {
                "amount": 0,
                "currencyCode": "EUR",
                "description": "GPS",
                "detailedDescription": "Navigation device included",
                "allowQuantity": false,
                "purpose": 13,
                "taxInclusive": true,
                "isPrepaid": true,
                "calculationInfo": {"quantity": 5, "unitCharge": 0, "unitName": "Day"}
              }
            ],
            "insurance": {"description": "CDW", "detailedDescription": "Collision damage waiver", "purpose": 7},
            "extras": [
              {
                "amount": 25,
                "originalAmount": 30,
                "maxCost": 50,
                "discountValue": 5,
                "discountedQuantity": 1,
                "currencyCode": "EUR",
                "description": "CHILD_SEAT",
                "detailedDescription": "Child seat",
                "allowQuantity": true,
                "purpose": 15,
                "taxInclusive": true,
                "isPrepaid": false,
                "calculationInfo": {"quantity": 5, "unitCharge": 6, "unitName": "Day"}
              }
            ],
            "purchasableInsurances": [
              {
                "amount": 40,
                "originalAmount": 50,
                "discountValue": 10,
                "discountedQuantity": 1,
                "currencyCode": "EUR",
                "description": "EXAMPLE_COVER",
                "detailedDescription": "Reduced excess cover",
                "allowQuantity": false,
                "purpose": 7,
                "taxInclusive": true,
                "isPrepaid": false,
                "insuranceExcess": 100,
                "insuranceDeposit": 200,
                "thirdPartyLiability": true,
                "theftWaiver": true,
                "theftExcess": 100,
                "calculationInfo": {"quantity": 5, "unitCharge": 10, "unitName": "Day"}
              }
            ]
          },
          "totalCharge": {"currencyCode": "EUR", "estimatedTotalAmount": 155, "rateTotalAmount": 135, "VAT": 26.13, "VATPercentage": 24}
        }
      ]
    }
  ]
}

Optional: rentalRate.extras and rentalRate.purchasableInsurances are omitted when returnExtras is false. Discount/cap fields and vehicle details can also be absent; see optional response fields.

Select one rentalDetails[] entry within a productOfferings[] vehicle. Its rentalRate includes the quote, mileage, charges, includedExtras, base insurance, and optional extras / purchasableInsurances with their prices.

Keep the quote’s trip, product, rate and promotion together. Re-search if they change. No sellable offer returns 422, code 221.

Each offer’s vendorRateID is valid for 20 minutes and guarantees its price when you book with it. It doesn’t hold the vehicle: fleet availability changes all the time. How long a quote holds

Verify quoted pricing#

POST/v1/getRate

Optionally verify availability pricing before booking, including selected equipment and quantities. This does not reserve a vehicle.

Book within the vendorRateID’s 20-minute window to keep the quoted price. The vehicle itself isn’t held. How long a quote holds

Request body

{
  "pickUpDateTime": "2027-05-10T12:00:00",
  "returnDateTime": "2027-05-15T12:00:00",
  "pickUpLocationCode": "HER",
  "pickUpExtendedLocationCode": "HERA01",
  "returnLocationCode": "HER",
  "returnExtendedLocationCode": "HERA01",
  "rateCode": "EXAMPLE_RATE",
  "vendorRateID": "EXAMPLE-VENDOR-RATE-001",
  "specialEquipmentPreferences": [
    {
      "equipType": 15,
      "quantity": 1
    }
  ],
  "promotionCode": "EXAMPLE10",
  "vehicleGroupPrefAccriss": "ECMR"
}

Field	Type / requirement	Use
`pickUpDateTime / returnDateTime`	Required strings	Same rental datetimes as the quote.
`pickUpLocationCode / returnLocationCode`	Required strings	Same stations as the quote.
`pickUpExtendedLocationCode / returnExtendedLocationCode`	Optional strings	If supplied, use the quote’s extended station codes.
`rateCode / vendorRateID`	Required nonempty strings	Values from the selected rental detail. The `vendorRateID` is valid for 20 minutes.
`vehicleGroupPrefAccriss`	Optional string	If sent, must match the quote’s SIPP code.
`promotionCode`	Optional string	Keep the selected promotion.
`specialEquipmentPreferences`	Optional array	Objects with numeric equipType and quantity from the offer. Use positive codes and whole quantities.

200 response

{
  "pickupStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "returnStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "vehicle": {
    "airConditionInd": true,
    "code": "ECMR",
    "description": "Example economy car",
    "passengerQuantity": 5,
    "transmissionType": "Manual",
    "vendorCarType": "ECONOMY",
    "vehMakeModel": "Example economy car",
    "pictureURL": "https://example.com/vehicles/economy.jpg",
    "doorsNum": 5,
    "suitcasesNum": 2,
    "minDriverAge": 21,
    "maxDriverAge": 75,
    "youngDriverAge": 25,
    "oldDriverAge": 1,
    "sippCategoryId": "E",
    "sippTypeId": "C",
    "sippTransmissionId": "M",
    "sippFuelId": "R",
    "insuranceExcess": 900,
    "insuranceDeposit": 500,
    "thirdPartyLiability": true,
    "theftWaiver": true,
    "theftExcess": 900
  },
  "pricedEquips": [
    {
      "amount": 25,
      "originalAmount": 30,
      "maxCost": 50,
      "discountValue": 5,
      "discountedQuantity": 1,
      "currencyCode": "EUR",
      "description": "CHILD_SEAT",
      "detailedDescription": "Child seat",
      "guaranteedInd": true,
      "includedInEstTotalInd": true,
      "includedInRate": false,
      "isPrepaid": false,
      "purpose": 15,
      "taxInclusive": true,
      "calculationInfo": {"quantity": 5, "unitCharge": 6, "unitName": "Day"},
      "equipInfo": {"type": "EQP", "quantity": 1}
    }
  ],
  "pricedCoverages": [
    {
      "amount": 15,
      "currencyCode": "EUR",
      "description": "CDW",
      "detailedDescription": "Collision damage waiver",
      "guaranteedInd": true,
      "includedInEstTotalInd": false,
      "includedInRate": false,
      "purpose": 7,
      "taxInclusive": true,
      "calculationInfo": {"quantity": 5, "unitCharge": 3, "unitName": "Day"},
      "coverageInfo": {"code": 7, "type": "VCT"}
    }
  ],
  "rentalRate": {
    "mileagePolicy": {
      "distUnitName": "km",
      "unlimited": false,
      "vehiclePeriodUnitName": "per-day",
      "quantity": 200,
      "additionalMileageCost": 0.25,
      "totalIncludedMileage": 1000
    },
    "vehicleCharges": [
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 1,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 150,
        "description": "Product Cost",
        "breakdown": [
          {"amount": 120.97, "description": "Base Rental"},
          {"amount": 29.03, "description": "VAT"}
        ],
        "calculationInfo": {"quantity": 5, "unitCharge": 30, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "Example location surcharge",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": false,
        "purpose": 2,
        "taxInclusive": true,
        "isPrepaid": false,
        "amount": 20,
        "originalAmount": 25,
        "maxCost": 40,
        "discountValue": 5,
        "discountedQuantity": 1,
        "description": "EXAMPLE_FEE",
        "calculationInfo": {"quantity": 5, "unitCharge": 5, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": false,
        "includedInRate": false,
        "purpose": 7,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 26.13,
        "description": "VAT",
        "calculationInfo": {"quantity": 5, "unitCharge": 5.23, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 10,
        "taxInclusive": true,
        "amount": -15,
        "description": "Promo Code",
        "calculationInfo": {"quantity": 1, "unitCharge": -1, "unitName": "Rental", "amount": -10, "type": "percentage"}
      }
    ]
  },
  "totalCharge": {"currencyCode": "EUR", "estimatedTotalAmount": 180, "rateTotalAmount": 135, "VAT": 26.13, "VATPercentage": 24}
}

Optional: Discount/cap fields, charge breakdowns and some vehicle details; see optional response fields.

The total excludes additional-driver fees, which are calculated when booking. Prices use the rate’s original currency, which may differ from availability. Read totalCharge.currencyCode for this response’s currency.

Create a reservation#

POST/v1/reservation

Create from an availability quote. Success is HTTP 200 with orderInfo.status: "committed"; no commit call is needed.

Send the vendorRateID within 20 minutes to book at the quoted price. If the vehicle has sold out in the meantime, request availability again. How long a quote holds

Request body

{
  "pickUpDateTime": "2027-05-10T12:00:00",
  "returnDateTime": "2027-05-15T12:00:00",
  "pickUpLocationCode": "HER",
  "pickUpExtendedLocationCode": "HERA01",
  "returnLocationCode": "HER",
  "returnExtendedLocationCode": "HERA01",
  "rateCode": "EXAMPLE_RATE",
  "vendorRateID": "EXAMPLE-VENDOR-RATE-001",
  "brokerOrderId": "BROKER-EXAMPLE-001",
  "customerInfo": {
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com",
      "phone": "+30 690 0000000",
      "addressLine": "1 Example Street",
      "city": "Athens",
      "country": "GR",
      "postalCode": "10557",
      "lang": "en",
      "dateOfBirth": "1991-06-15",
      "driverLicenseNumber": "DEMO-LICENCE-001",
      "driverLicenseCountryId": "GR",
      "driverLicenseIssueDate": "2015-06-15",
      "driverLicenseExpirationDate": "2030-06-15",
      "acceptedMarketing": false
    },
    "additionalDrivers": [
      {
        "name": "Taylor Example",
        "dateOfBirth": "1990-02-10",
        "driverLicenseNumber": "DEMO-LICENCE-002",
        "driverLicenseCountryId": "GR",
        "driverLicenseIssueDate": "2012-02-10",
        "driverLicenseExpirationDate": "2032-02-10"
      }
    ],
    "additionalUnknownDriversNum": 0,
    "corporateCustomer": {
      "company": "Example Travel Ltd",
      "email": "travel@example.com",
      "phone": "+30 210 0000000",
      "addressLine": "2 Example Street",
      "country": "GR",
      "vatNumber": "DEMO-VAT-001"
    }
  },
  "promotionCode": "EXAMPLE10",
  "specialEquipmentPreferences": [
    {
      "equipType": 15,
      "quantity": 1
    }
  ],
  "purchasableInsurance": {
    "equipType": 7
  },
  "notes": "Child seat requested.",
  "flightNo": "EX123",
  "vehicleGroupPrefAccriss": "ECMR",
  "arrivalDatetime": "2027-05-10T11:45:00",
  "partnerId": "55555555-5555-4555-8555-555555555555"
}

Field	Type / requirement	Use
`pickUpDateTime / returnDateTime`	Required strings	Use the quote’s rental datetimes.
`pickUpLocationCode / returnLocationCode`	Required strings	Use the quote’s stations.
`pickUpExtendedLocationCode / returnExtendedLocationCode`	Optional strings	If supplied, use the quote’s extended station codes.
`rateCode / vendorRateID`	Required nonempty strings	Use the selected quote. The `vendorRateID` is valid for 20 minutes and guarantees the price, not the vehicle.
`customerInfo`	Required object	Main customer name and email are required; see customer fields.
`brokerOrderId`	Optional string; recommended	Unique booking reference, e.g. BROKER-123. Avoid UUIDs and corporate-reference collisions. Reuse is rejected even after cancellation. Omitted: generated automatically.
`vehicleGroupPrefAccriss`	Optional string	Must match the selected quote’s SIPP code.
`promotionCode`	Optional string	Keep the quoted promotion.
`specialEquipmentPreferences`	Optional array	Objects with positive numeric equipType and quantity ≥ 0. Use offered codes and whole quantities.
`purchasableInsurance`	Optional object	One selected insurance: {"equipType": number}. See insurance.
`flightNo / notes`	Optional strings	Arrival flight and booking notes.
`arrivalDatetime`	Optional string	Arrival time in YYYY-MM-DDTHH:mm:ss format.
`partnerId`	Optional UUID string	Must identify an active partner. Use only an assigned ID.

200 response

{
  "orderInfo": {
    "id": "11111111-1111-4111-8111-111111111111",
    "corporateOrderId": "CORP-EXAMPLE-001",
    "brokerOrderId": "BROKER-EXAMPLE-001",
    "status": "committed",
    "reservationDate": "2027-04-20 10:30:00",
    "franchisee": "Example rental company",
    "pickUpDateTime": "2027-05-10T12:00:00",
    "returnDateTime": "2027-05-15T12:00:00",
    "notes": "Child seat requested.",
    "flightNo": "EX123"
  },
  "pickupStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "returnStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "customerInfo": {
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com",
      "phone": "+30 690 0000000",
      "addressLine": "1 Example Street",
      "city": "Athens",
      "country": "GR",
      "postalCode": "10557",
      "lang": "en",
      "dateOfBirth": "1991-06-15",
      "driverLicenseNumber": "DEMO-LICENCE-001",
      "driverLicenseCountryId": "GR",
      "driverLicenseIssueDate": "2015-06-15",
      "driverLicenseExpirationDate": "2030-06-15"
    },
    "additionaldrivers": [
      {
        "name": "Taylor Example",
        "dateOfBirth": "1990-02-10",
        "driverLicenseNumber": "DEMO-LICENCE-002",
        "driverLicenseCountryId": "GR",
        "driverLicenseIssueDate": "2012-02-10",
        "driverLicenseExpirationDate": "2032-02-10"
      }
    ]
  },
  "vehicleInfo": {
    "airConditionInd": true,
    "code": "ECMR",
    "description": "Example economy car",
    "passengerQuantity": 5,
    "transmissionType": "Manual",
    "vendorCarType": "ECONOMY",
    "vehMakeModel": "Example economy car",
    "pictureURL": "https://example.com/vehicles/economy.jpg",
    "doorsNum": 5,
    "suitcasesNum": 2,
    "minDriverAge": 21,
    "maxDriverAge": 75,
    "youngDriverAge": 25,
    "oldDriverAge": 1,
    "sippCategoryId": "E",
    "sippTypeId": "C",
    "sippTransmissionId": "M",
    "sippFuelId": "R",
    "insuranceExcess": 900,
    "insuranceDeposit": 500,
    "thirdPartyLiability": true,
    "theftWaiver": true,
    "theftExcess": 900
  },
  "pricedEquips": [
    {
      "amount": 25,
      "originalAmount": 30,
      "maxCost": 50,
      "discountValue": 5,
      "discountedQuantity": 1,
      "currencyCode": "EUR",
      "description": "CHILD_SEAT",
      "detailedDescription": "Child seat",
      "guaranteedInd": true,
      "includedInEstTotalInd": true,
      "includedInRate": false,
      "isPrepaid": false,
      "purpose": 15,
      "taxInclusive": true,
      "calculationInfo": {"quantity": 5, "unitCharge": 6, "unitName": "Day"},
      "equipInfo": {"type": "EQP", "quantity": 1}
    }
  ],
  "pricedCoverages": [
    {
      "amount": 15,
      "currencyCode": "EUR",
      "description": "CDW",
      "detailedDescription": "Collision damage waiver",
      "guaranteedInd": true,
      "includedInEstTotalInd": false,
      "includedInRate": false,
      "purpose": 7,
      "taxInclusive": true,
      "calculationInfo": {"quantity": 5, "unitCharge": 3, "unitName": "Day"},
      "coverageInfo": {"code": 7, "type": "VCT"}
    }
  ],
  "purchasableInsurance": {
    "amount": 40,
    "originalAmount": 50,
    "discountValue": 10,
    "discountedQuantity": 1,
    "currencyCode": "EUR",
    "description": "EXAMPLE_COVER",
    "detailedDescription": "Reduced excess cover",
    "guaranteedInd": true,
    "includedInEstTotalInd": true,
    "includedInRate": false,
    "isPrepaid": false,
    "insuranceExcess": 100,
    "insuranceDeposit": 200,
    "thirdPartyLiability": true,
    "theftWaiver": true,
    "theftExcess": 100,
    "purpose": 7,
    "taxInclusive": true,
    "calculationInfo": {"quantity": 5, "unitCharge": 10, "unitName": "Day"},
    "equipInfo": {"type": 7}
  },
  "rentalRate": {
    "mileagePolicy": {
      "distUnitName": "km",
      "unlimited": false,
      "vehiclePeriodUnitName": "per-day",
      "quantity": 200,
      "additionalMileageCost": 0.25,
      "totalIncludedMileage": 1000
    },
    "vehicleCharges": [
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 1,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 150,
        "description": "Product Cost",
        "breakdown": [
          {"amount": 120.97, "description": "Base Rental"},
          {"amount": 29.03, "description": "VAT"}
        ],
        "calculationInfo": {"quantity": 5, "unitCharge": 30, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "Example location surcharge",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": false,
        "purpose": 2,
        "taxInclusive": true,
        "isPrepaid": false,
        "amount": 20,
        "originalAmount": 25,
        "maxCost": 40,
        "discountValue": 5,
        "discountedQuantity": 1,
        "description": "EXAMPLE_FEE",
        "calculationInfo": {"quantity": 5, "unitCharge": 5, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "Additional driver",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": false,
        "purpose": 12,
        "taxInclusive": true,
        "isPrepaid": false,
        "amount": 20,
        "description": "ADS",
        "calculationInfo": {"quantity": 5, "unitCharge": 4, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": false,
        "includedInRate": false,
        "purpose": 7,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 26.13,
        "description": "VAT",
        "calculationInfo": {"quantity": 5, "unitCharge": 5.23, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 10,
        "taxInclusive": true,
        "amount": -15,
        "description": "Promo Code",
        "calculationInfo": {"quantity": 1, "unitCharge": -1, "unitName": "Rental", "amount": -10, "type": "percentage"}
      }
    ]
  },
  "totalCharge": {"currencyCode": "EUR", "estimatedTotalAmount": 240, "rateTotalAmount": 135, "VAT": 26.13, "VATPercentage": 24}
}

Optional: orderInfo.notes, orderInfo.flightNo, purchasableInsurance, and the optional response fields.

Store orderInfo.corporateOrderId from this response: it is Surprice’s reservation number and the reference to use for every later request. Booking references

Duplicate references or bookings return codes 127 or 128. After a timeout or duplicate error, look up the booking before retrying.

Read a reservation#

GET/v1/reservation/:orderId

Get the latest reservation belonging to your broker account.

Request

GET /v1/reservation/CORP-EXAMPLE-001

:orderId accepts the current orderInfo.id (UUID), corporateOrderId or brokerOrderId. URL-encode it as one path segment.

Use the stored corporateOrderId, Surprice’s reservation number. Unlike orderInfo.id, it is a stable reference. Booking references

200 response

{
  "orderInfo": {
    "id": "11111111-1111-4111-8111-111111111111",
    "corporateOrderId": "CORP-EXAMPLE-001",
    "brokerOrderId": "BROKER-EXAMPLE-001",
    "status": "committed",
    "reservationDate": "2027-04-20 10:30:00",
    "franchisee": "Example rental company",
    "pickUpDateTime": "2027-05-10 12:00:00",
    "returnDateTime": "2027-05-15 12:00:00",
    "notes": "Child seat requested.",
    "flightNo": "EX123"
  },
  "pickupStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "returnStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": ["Example Airport Road 1", "(35.34,25.18)"],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {"code": "GR", "name": "Greece"},
      "coordinates": {"latitude": 35.34, "longitude": 25.18}
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": ["Monday"],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {"start": "08:00:00", "end": "22:00:00"},
            "extended": {"start": "22:00:00", "end": "23:59:00"}
          }
        }
      ]
    }
  },
  "customerInfo": {
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com",
      "phone": "+30 690 0000000",
      "addressLine": "1 Example Street",
      "city": "Athens",
      "country": "GR",
      "postalCode": "10557",
      "lang": "en",
      "dateOfBirth": "1991-06-15",
      "driverLicenseNumber": "DEMO-LICENCE-001",
      "driverLicenseCountryId": "GR",
      "driverLicenseIssueDate": "2015-06-15",
      "driverLicenseExpirationDate": "2030-06-15"
    },
    "additionaldrivers": [
      {
        "name": "Taylor Example",
        "dateOfBirth": "1990-02-10",
        "driverLicenseNumber": "DEMO-LICENCE-002",
        "driverLicenseCountryId": "GR",
        "driverLicenseIssueDate": "2012-02-10",
        "driverLicenseExpirationDate": "2032-02-10"
      }
    ]
  },
  "vehicleInfo": {
    "airConditionInd": true,
    "code": "ECMR",
    "description": "Example economy car",
    "passengerQuantity": 5,
    "transmissionType": "Manual",
    "vendorCarType": "ECONOMY",
    "vehMakeModel": "Example economy car",
    "pictureURL": "https://example.com/vehicles/economy.jpg",
    "doorsNum": 5,
    "suitcasesNum": 2,
    "minDriverAge": 21,
    "maxDriverAge": 75,
    "youngDriverAge": 25,
    "oldDriverAge": 1,
    "sippCategoryId": "E",
    "sippTypeId": "C",
    "sippTransmissionId": "M",
    "sippFuelId": "R",
    "insuranceExcess": 900,
    "insuranceDeposit": 500,
    "thirdPartyLiability": true,
    "theftWaiver": true,
    "theftExcess": 900
  },
  "pricedEquips": [
    {
      "amount": 25,
      "originalAmount": 30,
      "maxCost": 50,
      "discountValue": 5,
      "discountedQuantity": 1,
      "currencyCode": "EUR",
      "description": "CHILD_SEAT",
      "detailedDescription": "Child seat",
      "guaranteedInd": true,
      "includedInEstTotalInd": true,
      "includedInRate": false,
      "isPrepaid": false,
      "purpose": 15,
      "taxInclusive": true,
      "calculationInfo": {"quantity": 5, "unitCharge": 6, "unitName": "Day"},
      "equipInfo": {"type": "EQP", "quantity": 1}
    }
  ],
  "pricedCoverages": [
    {
      "amount": 15,
      "currencyCode": "EUR",
      "description": "CDW",
      "detailedDescription": "Collision damage waiver",
      "guaranteedInd": true,
      "includedInEstTotalInd": false,
      "includedInRate": false,
      "purpose": 7,
      "taxInclusive": true,
      "calculationInfo": {"quantity": 5, "unitCharge": 3, "unitName": "Day"},
      "coverageInfo": {"code": 7, "type": "VCT"}
    }
  ],
  "purchasableInsurance": {
    "amount": 40,
    "originalAmount": 50,
    "discountValue": 10,
    "discountedQuantity": 1,
    "currencyCode": "EUR",
    "description": "EXAMPLE_COVER",
    "detailedDescription": "Reduced excess cover",
    "guaranteedInd": true,
    "includedInEstTotalInd": true,
    "includedInRate": false,
    "isPrepaid": false,
    "insuranceExcess": 100,
    "insuranceDeposit": 200,
    "thirdPartyLiability": true,
    "theftWaiver": true,
    "theftExcess": 100,
    "purpose": 7,
    "taxInclusive": true,
    "calculationInfo": {"quantity": 5, "unitCharge": 10, "unitName": "Day"},
    "equipInfo": {"type": 7}
  },
  "rentalRate": {
    "mileagePolicy": {
      "distUnitName": "km",
      "unlimited": false,
      "vehiclePeriodUnitName": "per-day",
      "quantity": 200,
      "additionalMileageCost": 0.25,
      "totalIncludedMileage": 1000
    },
    "vehicleCharges": [
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 1,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 150,
        "description": "Product Cost",
        "breakdown": [
          {"amount": 120.97, "description": "Base Rental"},
          {"amount": 29.03, "description": "VAT"}
        ],
        "calculationInfo": {"quantity": 5, "unitCharge": 30, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "Example location surcharge",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": false,
        "purpose": 2,
        "taxInclusive": true,
        "isPrepaid": false,
        "amount": 20,
        "originalAmount": 25,
        "maxCost": 40,
        "discountValue": 5,
        "discountedQuantity": 1,
        "description": "EXAMPLE_FEE",
        "calculationInfo": {"quantity": 5, "unitCharge": 5, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "Additional driver",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": false,
        "purpose": 12,
        "taxInclusive": true,
        "isPrepaid": false,
        "amount": 20,
        "description": "ADS",
        "calculationInfo": {"quantity": 5, "unitCharge": 4, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": false,
        "includedInRate": false,
        "purpose": 7,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 26.13,
        "description": "VAT",
        "calculationInfo": {"quantity": 5, "unitCharge": 5.23, "unitName": "Day"}
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 10,
        "taxInclusive": true,
        "amount": -15,
        "description": "Promo Code",
        "calculationInfo": {"quantity": 1, "unitCharge": -1, "unitName": "Rental", "amount": -10, "type": "percentage"}
      }
    ]
  },
  "totalCharge": {"currencyCode": "EUR", "estimatedTotalAmount": 240, "rateTotalAmount": 135, "VAT": 26.13, "VATPercentage": 24}
}

Optional: purchasableInsurance, and the optional response fields.

Returns the reservation model. Rental and reservation datetimes use YYYY-MM-DD HH:mm:ss. Missing bookings, old UUIDs and bookings outside your account return 422, code 284.

The reservation id can change after an update. Use corporateOrderId or brokerOrderId for later requests.

Amend a reservation#

PUT/v1/reservation/:orderId/amend

Update a committed booking before pickup, subject to your amendment policy. All top-level fields are optional; send a nonempty object with the changes. Use a saved brokerOrderId or corporateOrderId as :orderId.

Dates/times or vehicle group changependingReview the returned offer

CommitorIgnore

Other accepted changescommittedApplied immediately

GET the latest booking after either path

Request body · all supported fields

{
  "pickUpDateTime": "2027-05-10T12:00:00",
  "returnDateTime": "2027-05-16T12:00:00",
  "pickUpLocationCode": "HER",
  "pickUpExtendedLocationCode": "HERA01",
  "returnLocationCode": "HER",
  "returnExtendedLocationCode": "HERA01",
  "vehicleGroupPrefAccriss": "ECMR",
  "customerInfo": {
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com",
      "phone": "+30 690 0000000",
      "addressLine": "1 Example Street",
      "city": "Athens",
      "postalCode": "10557",
      "lang": "en",
      "dateOfBirth": "1991-06-15",
      "driverLicenseNumber": "DEMO-LICENCE-001",
      "driverLicenseCountryId": "GR",
      "driverLicenseIssueDate": "2015-06-15",
      "driverLicenseExpirationDate": "2030-06-15"
    },
    "additionalDrivers": [
      {
        "name": "Taylor Example",
        "dateOfBirth": "1990-02-10",
        "driverLicenseNumber": "DEMO-LICENCE-002",
        "driverLicenseCountryId": "GR",
        "driverLicenseIssueDate": "2012-02-10",
        "driverLicenseExpirationDate": "2032-02-10"
      }
    ],
    "additionalUnknownDriversNum": 0
  },
  "specialEquipmentPreferences": [
    {
      "equipType": 15,
      "quantity": 1
    }
  ],
  "purchasableInsurance": {
    "equipType": 7
  },
  "flightNo": "EX123",
  "arrivalDatetime": "2027-05-10T11:45:00",
  "notes": "Child seat requested.",
  "partnerId": "55555555-5555-4555-8555-555555555555"
}

Field	Type / requirement	Use
`pickUpDateTime / returnDateTime`	Optional strings	Changed dates or times trigger repricing and pending status.
`vehicleGroupPrefAccriss`	Optional string	A changed SIPP code triggers repricing and pending status.
`pickUpLocationCode / pickUpExtendedLocationCode / returnLocationCode / returnExtendedLocationCode`	Optional strings	If supplied, must identify the original stations; station moves are rejected.
`customerInfo`	Optional object	See customer fields and customer updates below.
`specialEquipmentPreferences`	Optional array	Objects with positive numeric `equipType` and whole-number `quantity`. See replacement rules below.
`purchasableInsurance`	Optional object	One insurance selected by `equipType`. See replacement rules below.
`flightNo / notes`	Optional strings	Arrival flight and booking notes.
`arrivalDatetime`	Optional string	Arrival time in `YYYY-MM-DDTHH:mm:ss` format.
`partnerId`	Optional UUID string	Assigned partner UUID.

200 response

{
  "ammendedOrderInfo": {
    "id": "33333333-3333-4333-8333-333333333333",
    "corporateOrderId": "CORP-EXAMPLE-001",
    "brokerOrderId": "BROKER-EXAMPLE-001",
    "status": "pending",
    "reservationDate": "2027-04-20T10:30:00.000Z",
    "franchisee": "Example rental company",
    "pickUpDateTime": "2027-05-10T12:00:00",
    "returnDateTime": "2027-05-16T12:00:00",
    "notes": "Child seat requested.",
    "flightNo": "EX123"
  },
  "pickupStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": [
        "Example Airport Road 1",
        "(35.34,25.18)"
      ],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {
        "code": "GR",
        "name": "Greece"
      },
      "coordinates": {
        "latitude": 35.34,
        "longitude": 25.18
      }
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": [
            "Monday"
          ],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {
              "start": "08:00:00",
              "end": "22:00:00"
            },
            "extended": {
              "start": "22:00:00",
              "end": "23:59:00"
            }
          }
        }
      ]
    }
  },
  "returnStationInfo": {
    "stationType": "Airport",
    "locationCode": "HER",
    "extendedLocationCode": "HERA01",
    "name": "Example station",
    "isMeetAndGreet": false,
    "address": {
      "addressLine": [
        "Example Airport Road 1",
        "(35.34,25.18)"
      ],
      "city": "Heraklion",
      "postalCode": "71601",
      "country": {
        "code": "GR",
        "name": "Greece"
      },
      "coordinates": {
        "latitude": 35.34,
        "longitude": 25.18
      }
    },
    "telephone": "+30 2810 000000",
    "additionalInfo": {
      "text": "Meet our representative at the arrivals exit.",
      "operationTime": [
        {
          "days": [
            "Monday"
          ],
          "schedule": {
            "from": "01/01",
            "to": "31/12",
            "normal": {
              "start": "08:00:00",
              "end": "22:00:00"
            },
            "extended": {
              "start": "22:00:00",
              "end": "23:59:00"
            }
          }
        }
      ]
    }
  },
  "customerInfo": {
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com",
      "lang": "en"
    },
    "additionaldrivers": [
      {
        "name": "Taylor Example"
      }
    ]
  },
  "vehicleInfo": {
    "airConditionInd": true,
    "code": "ECMR",
    "description": "Example economy car",
    "passengerQuantity": 5,
    "transmissionType": "Manual",
    "vendorCarType": "ECONOMY",
    "vehMakeModel": "Example economy car",
    "pictureURL": "https://example.com/vehicles/economy.jpg",
    "doorsNum": 5,
    "suitcasesNum": 2,
    "minDriverAge": 21,
    "maxDriverAge": 75,
    "youngDriverAge": 25,
    "oldDriverAge": 1,
    "sippCategoryId": "E",
    "sippTypeId": "C",
    "sippTransmissionId": "M",
    "sippFuelId": "R",
    "insuranceExcess": 900,
    "insuranceDeposit": 500,
    "thirdPartyLiability": true,
    "theftWaiver": true,
    "theftExcess": 900
  },
  "pricedEquips": [
    {
      "amount": 30,
      "originalAmount": 36,
      "maxCost": 50,
      "discountValue": 6,
      "discountedQuantity": 1,
      "currencyCode": "EUR",
      "description": "CHILD_SEAT",
      "detailedDescription": "Child seat",
      "guaranteedInd": true,
      "includedInEstTotalInd": true,
      "includedInRate": false,
      "isPrepaid": false,
      "purpose": 15,
      "taxInclusive": true,
      "calculationInfo": {
        "quantity": 6,
        "unitCharge": 6,
        "unitName": "Day"
      },
      "equipInfo": {
        "type": "EQP",
        "quantity": 1
      }
    }
  ],
  "pricedCoverages": [
    {
      "amount": 18,
      "currencyCode": "EUR",
      "description": "CDW",
      "detailedDescription": "Collision damage waiver",
      "guaranteedInd": true,
      "includedInEstTotalInd": false,
      "includedInRate": false,
      "purpose": 7,
      "taxInclusive": true,
      "calculationInfo": {
        "quantity": 6,
        "unitCharge": 3,
        "unitName": "Day"
      },
      "coverageInfo": {
        "code": 7,
        "type": "VCT"
      }
    }
  ],
  "purchasableInsurance": {
    "amount": 48,
    "originalAmount": 60,
    "discountValue": 12,
    "discountedQuantity": 1,
    "currencyCode": "EUR",
    "description": "EXAMPLE_COVER",
    "detailedDescription": "Reduced excess cover",
    "guaranteedInd": true,
    "includedInEstTotalInd": true,
    "includedInRate": false,
    "isPrepaid": false,
    "insuranceExcess": 100,
    "insuranceDeposit": 200,
    "thirdPartyLiability": true,
    "theftWaiver": true,
    "theftExcess": 100,
    "purpose": 7,
    "taxInclusive": true,
    "calculationInfo": {
      "quantity": 6,
      "unitCharge": 10,
      "unitName": "Day"
    },
    "equipInfo": {
      "type": 7
    }
  },
  "rentalRate": {
    "mileagePolicy": {
      "distUnitName": "km",
      "unlimited": false,
      "vehiclePeriodUnitName": "per-day",
      "quantity": 200,
      "additionalMileageCost": 0.25,
      "totalIncludedMileage": 1200
    },
    "vehicleCharges": [
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 1,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 180,
        "description": "Product Cost",
        "breakdown": [
          {
            "amount": 145.16,
            "description": "Base Rental"
          },
          {
            "amount": 34.84,
            "description": "VAT"
          }
        ],
        "calculationInfo": {
          "quantity": 6,
          "unitCharge": 30,
          "unitName": "Day"
        }
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "Example location surcharge",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": false,
        "purpose": 2,
        "taxInclusive": true,
        "isPrepaid": false,
        "amount": 24,
        "originalAmount": 30,
        "maxCost": 40,
        "discountValue": 6,
        "discountedQuantity": 1,
        "description": "EXAMPLE_FEE",
        "calculationInfo": {
          "quantity": 6,
          "unitCharge": 5,
          "unitName": "Day"
        }
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "Additional driver",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": false,
        "purpose": 12,
        "taxInclusive": true,
        "isPrepaid": false,
        "amount": 24,
        "description": "ADS",
        "calculationInfo": {
          "quantity": 6,
          "unitCharge": 4,
          "unitName": "Day"
        }
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": false,
        "includedInRate": false,
        "purpose": 7,
        "taxInclusive": true,
        "isPrepaid": true,
        "amount": 31.35,
        "description": "VAT",
        "calculationInfo": {
          "quantity": 6,
          "unitCharge": 5.23,
          "unitName": "Day"
        }
      },
      {
        "currencyCode": "EUR",
        "detailedDescription": "",
        "guaranteedInd": true,
        "includedInEstTotalInd": true,
        "includedInRate": true,
        "purpose": 10,
        "taxInclusive": true,
        "amount": -18,
        "description": "Promo Code",
        "calculationInfo": {
          "quantity": 1,
          "unitCharge": -1,
          "unitName": "Rental",
          "amount": -10,
          "type": "percentage"
        }
      }
    ]
  },
  "totalCharge": {
    "currencyCode": "EUR",
    "estimatedTotalAmount": 288,
    "rateTotalAmount": 162,
    "VAT": 31.35,
    "VATPercentage": 24
  }
}

Optional: purchasableInsurance and the optional response fields. additionaldrivers[] contains names only.

The response uses ammendedOrderInfo (double m). GET returns the full customer details.

Status: changes to pickup/return dates or times, or vehicle group, return pending. Review the returned offer, then use commit to accept or ignore to decline the pending trip change. Other supported changes return committed and apply immediately. Use the returned prices and total.

Pending amendments can expire. Commit and ignore require the booking to still be pending.

Additional drivers: omit customerInfo.additionalDrivers to keep the list, or send the complete replacement list with each driver’s details. additionalUnknownDriversNum sets the unnamed-driver count. Send [] and 0 to clear all additional drivers.

Equipment extras: omit specialEquipmentPreferences to keep existing selections. Send an array to replace the list, including every extra you want to keep and its quantity. Send [] to remove all selected optional equipment. Use the offered purpose as equipType.

Optional insurance: omit purchasableInsurance to keep the current selection. Send {"equipType": 7} to add or replace it, or {} to remove it. Use the offered purpose from availability’s rentalRate.purchasableInsurances[]; select one insurance.

Request body · remove optional selections

{
  "specialEquipmentPreferences": [],
  "purchasableInsurance": {},
  "customerInfo": {"additionalDrivers": [], "additionalUnknownDriversNum": 0}
}

Customer updates: send the customer’s current details under customerInfo.customer, including name and any birth/license information. Include addressLine when updating an address.

Amendment failures

HTTP / type / code	Meaning
400	Invalid body, field type, or customer/arrival date format.
401	Missing or invalid API key.
422 · 3/284	No latest booking found for your account and reference.
422 · 3/118	The booking is not `committed`. Resolve an existing pending amendment first.
422 · 3/90	Amendments are not permitted, or the request changes a station.
422 · 3/226	The existing or requested pickup time has passed.
422 · 3/135 or 3/230	Invalid rental datetime format, or return is before pickup.
422 · 3/229 or 3/233	Pickup or return station not recognised or inactive.
422 · 3/263	The booking’s saved rate is unavailable. Contact support.
422 · 3/221	No offer is available for the changed dates or vehicle group.
422 · 3/214 or 3/227	The requested pickup or return time cannot be served.
422 · 3/249 or 3/536	The rate or promotion cannot be applied.
422 · 13/188; 500/502	The request could not be completed. See retry guidance.

Changes to dates, times or vehicle group can also return availability errors. See errors and retries for response formats and handling.

Accept a pending amendment#

PUT/v1/reservation/:orderId/commit

Accept a pending amendment before pickup. The booking becomes committed.

Request

PUT /v1/reservation/<CORPORATE_ORDER_ID>/commit
Content-Type: application/json

{}

200 response

{"message": "Operation successful"}

Send {}, then GET by stable reference.

200 success · 422: code 118 wrong state, 226 pickup passed, 284 booking not found

Discard a pending trip change#

PUT/v1/reservation/:orderId/ignore

Decline a pending change to rental dates, times or vehicle group before pickup.

Request

PUT /v1/reservation/<CORPORATE_ORDER_ID>/ignore
Content-Type: application/json

{}

200 response

{"message": "Operation successful"}

Send {}, then GET by stable reference.

200 success · 422: code 95 already ignored, 264 wrong state, 226 pickup passed, 284 booking not found

Cancel a reservation#

PUT/v1/reservation/:orderId/cancel

Cancel a committed booking before pickup. Resolve any pending amendment first.

Request

PUT /v1/reservation/<CORPORATE_ORDER_ID>/cancel
Content-Type: application/json

{"cancellation_reason":"Customer requested cancellation"}

200 response

{"message": "Operation successful"}

Send {} or an optional cancellation_reason string. Success sets the booking status to cancelled.

No cancellation fee or refund amount is returned.

200 success · 422: code 95 already cancelled, 264 wrong state, 226 pickup passed, 284 booking not found

Station extras catalog#

GET/v1/location/extras

Get station catalog extras and default rates. Use availability for bookable options and trip prices.

Request

GET /v1/location/extras?locationCode=HER&extendedLocationCode=HERA01&limit=20&offset=0

Field	Type / requirement	Use
`locationCode`	Required nonempty string	Station location code.
`extendedLocationCode`	Optional string	Narrows the station match when supplied.
`extraId`	Optional string	Filter by the catalog extra identifier.
`limit / offset`	Optional integers	See pagination.

200 response

{
  "limit": 20,
  "offset": 0,
  "total": 1,
  "results": {
    "results": [
      {
        "id": "CHILD_SEAT",
        "description": "Child seat",
        "rate": 6,
        "rate_type": "fixed",
        "rate_period": "per-day",
        "maxCost": 50,
        "vat_included": true,
        "allow_qty": true,
        "included_in_base_rate": false,
        "ota_code_set": "EQP",
        "ota_code": 15
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Optional: results.results[].maxCost.

Read the array at results.results. Book with the offer’s numeric equipment code, not the catalog id. Empty pages return 200.

200 nested page · 404: code 229 station missing or inactive

Station insurance catalog#

GET/v1/location/insurances

Get station catalog insurance rates. Use availability for selectable insurance and trip-specific terms.

Request

GET /v1/location/insurances?locationCode=HER&extendedLocationCode=HERA01&limit=20&offset=0

Field	Type / requirement	Use
`locationCode`	Required nonempty string	Station location code.
`extendedLocationCode`	Optional string	Narrows the station match when supplied.
`insuranceExtraId`	Optional string	Filter by the catalog extra identifier.
`limit / offset`	Optional integers	See pagination.

200 response

{
  "limit": 20,
  "offset": 0,
  "total": 1,
  "results": {
    "results": [
      {
        "id": "EXAMPLE_COVER",
        "description": "Reduced excess cover",
        "rate": 10,
        "rate_type": "fixed",
        "rate_period": "per-day",
        "vat_included": true,
        "insurance_excess": 100,
        "ota_code_set": "VCT",
        "ota_code": 7
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Read the array at results.results. Filter by insuranceExtraId. Empty pages return 200.

200 nested page · 404: code 229 station missing or inactive

List cities#

GET/v1/cities

List cities using optional limit and offset.

Request

GET /v1/cities?limit=20&offset=0

200 response

{
  "results": [
    {"id": 1, "name": "Heraklion", "country_id": "GR", "time_zone": "Europe/Athens"}
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Optional: results[].time_zone may be null.

Use id to identify a city. Empty pages return 404: {"error":"Cities not found"}.

List countries#

GET/v1/countries

List countries using optional limit and offset.

Request

GET /v1/countries?limit=20&offset=0

200 response

{
  "results": [
    {
      "id": "GR",
      "name": "Greece",
      "dialing_prefix": "+30",
      "currency_id": "EUR",
      "stop_selling_id": "44444444-4444-4444-8444-444444444444",
      "created_at": "2027-01-01T10:00:00.000Z",
      "updated_at": "2027-01-02T10:00:00.000Z",
      "tax_percentage": 24
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Optional: results[].stop_selling_id and results[].tax_percentage may be null.

Use id for customer country fields. Empty pages return 404: {"error":"Countries not found"}. Use offer taxes, not country defaults.

SIPP reference#

GET/v1/sipp-info

Get SIPP dictionaries. No parameters or pagination.

200 response

{
  "sippFuelTypes": [
    {"id": "R", "description": "Unspecified Fuel/Power, A/C"}
  ],
  "sippCategoryTypes": [
    {"id": "E", "description": "Economy"}
  ],
  "sippTransmissionTypes": [
    {"id": "M", "description": "Manual Unspecified Drive"}
  ],
  "sippVehicleTypes": [
    {"id": "C", "description": "2/4 Door"}
  ]
}

Match returned IDs to the SIPP fields in availability.

Service health#

GET/status

Check API availability. No authentication required.

Request

GET /status

200 response body

OK

Returns plain text: 200 OK or 500 ERROR.

Customer and driver fields#

Fields belong under customerInfo. Create requires customer name and email; amendment replacement rules apply to updates.

Field	Type / requirement	Use
`customer.name`	Required string	Main customer’s full name. Include whenever sending `customerInfo.customer`.
`customer.email`	String; required on create	Main customer’s email. Optional on amend.
`customer.phone / customer.lang`	Optional strings	Contact number and language code.
`customer.addressLine / customer.city / customer.postalCode / customer.country`	Optional strings	Address line, city name, postal code and country ID. See customer updates for amendment requests.
`customer.dateOfBirth`	Optional date string	YYYY-MM-DD.
`customer.driverLicenseNumber / customer.driverLicenseCountryId`	Optional strings	License number and issuing country ID.
`customer.driverLicenseIssueDate / customer.driverLicenseExpirationDate`	Optional date strings	YYYY-MM-DD.
`customer.acceptedMarketing`	Optional boolean; create only	Marketing opt-in for a new customer.
`corporateCustomer`	Optional object; create only	Requires `company`, `country` and `vatNumber`; optional `email`, `phone` and `addressLine`.
`additionalDrivers`	Optional array	Array of drivers, each with name. Optional dateOfBirth and the four license fields above.
`additionalUnknownDriversNum`	Optional nonnegative integer	Unnamed drivers: appended on create; replaces the unnamed count on amend.

Create customerInfo example

{
  "customerInfo": {
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com",
      "dateOfBirth": "1990-06-15",
      "driverLicenseNumber": "EXAMPLE-LICENSE",
      "driverLicenseCountryId": "GR",
      "driverLicenseIssueDate": "2010-06-15",
      "driverLicenseExpirationDate": "2030-06-15"
    },
    "additionalDrivers": [{"name": "Sam Example", "dateOfBirth": "1992-09-01"}],
    "additionalUnknownDriversNum": 1
  }
}

Select additional drivers through customerInfo. Their charges, including unnamed drivers, appear in rentalRate.vehicleCharges with purpose: 12. Responses use customerInfo.additionaldrivers (lowercase d).

Equipment and insurance#

Availability includes option prices in rentalRate.extras[] and rentalRate.purchasableInsurances[]. Select from these lists; returnExtras defaults to true.

Choice	Selection	Result
`rentalRate.extras[]`	`specialEquipmentPreferences: [{equipType, quantity}]`. Use the offer’s numeric `purpose`.	`pricedEquips[]`: match `purpose`. `equipInfo.type` is `"EQP"`; `equipInfo.quantity` is item count.
`rentalRate.purchasableInsurances[]`	`purchasableInsurance: {equipType}`. Use `purpose`; one insurance, no quantity.	`purchasableInsurance`: the selected insurance and its terms.
`rentalRate.insurance`	Base product insurance, already part of the rate: the coverage combined with the rate code (`insurance_extra_id`), such as CDW or FDW.	Keep distinct from optional purchasable insurance.

Add to create body · only if these codes were offered

{
  "specialEquipmentPreferences": [
    {
      "equipType": 15,
      "quantity": 1
    }
  ],
  "purchasableInsurance": {
    "equipType": 7
  }
}

If allowQuantity is false, select one item. equipInfo.quantity is the item count; calculationInfo.quantity is the pricing period. To remove equipment on amend, leave it out of the replacement list.

Terms include insuranceExcess, insuranceDeposit, thirdPartyLiability, theftWaiver and theftExcess. Read base terms from the vehicle and optional terms from the selected insurance. Deposit and excess are separate amounts.

See the equipment and insurance amendment rules to keep, replace or remove selections.

Response fields#

Object	Contents
`orderInfo`	`id`, `corporateOrderId`, `brokerOrderId`, `status`, `reservationDate`, `franchisee`, trip datetimes, `notes`, `flightNo`. Amend calls it `ammendedOrderInfo`. `corporateOrderId` is Surprice’s reservation number; store it.
`pickupStationInfo / returnStationInfo`	Station identity, address, coordinates, telephone, pickup information and operating schedules.
`customerInfo`	`customer` and `additionaldrivers`. GET returns full customer details; amend returns a summary.
`vehicleInfo`	Vehicle group; called `vehicle` in availability/getRate. Includes `code` (SIPP), `vendorCarType`, description, `vehMakeModel`, `pictureURL`, passengers, doors, suitcases, transmission, air-conditioning, age limits and SIPP IDs.
`vehicleInfo.insuranceExcess / insuranceDeposit`	Base vehicle-group insurance terms; the selected optional insurance has its own returned terms.
`pricedEquips[]`	Equipment charges: numeric `purpose`, `equipInfo.type: "EQP"` and item count in `equipInfo.quantity`.
`pricedCoverages[]`	Coverage charges with `coverageInfo.code` / `type`. May include informational coverage; use returned totals.
`purchasableInsurance`	Optional insurance charge and terms. `equipInfo.type` is the numeric insurance code, matching `purpose`. Returned when an optional insurance is selected.
`rentalRate.mileagePolicy`	`distUnitName`, `unlimited`, `vehiclePeriodUnitName`, `quantity`, `additionalMileageCost`, `totalIncludedMileage`. Check `unlimited` first. For a daily allowance, multiply by rental days; a per-rental allowance applies to the whole trip.
`rentalRate.vehicleCharges[]`	Product Cost, applicable surcharges, discounts and informational tax lines. See pricing below.
`totalCharge`	`currencyCode`, `estimatedTotalAmount`, `rateTotalAmount`, `VAT`, `VATPercentage`. `rateTotalAmount` is invoiceable between Surprice and you; `estimatedTotalAmount` adds any additional costs the customer may pay on arrival. See the two totals.

Check age eligibility using minDriverAge, maxDriverAge and availability with the actual age. oldDriverAge is not a maximum-age field.

Booking statuses include committed, pending, ignored and cancelled. Check each endpoint for allowed actions.

Optional response fields

Shown in the examples when applicable:

schedule.extended: extended station hours.
Vehicle fields that may be absent or null: pictureURL, vendorCarType, vehMakeModel, doorsNum, suitcasesNum, minDriverAge, maxDriverAge, youngDriverAge, oldDriverAge, sippCategoryId, sippTypeId, sippTransmissionId, sippFuelId, insuranceExcess, insuranceDeposit and theftExcess.
originalAmount, discountValue and discountedQuantity: discounted charges; maxCost: capped charges.
breakdown: product price components; allowQuantity: applicable availability charges; isPrepaid: applicable charges.
calculationInfo.amount and calculationInfo.type: promotion charges.
purchasableInsurance: selected optional insurance.

Prices, taxes and currency#

Use totalCharge. Charges are tax-inclusive; do not add VAT, breakdowns or discounts again.

What the two totals mean

Every quote and booking returns both. rateTotalAmount is settled between Surprice and you; estimatedTotalAmount adds any additional costs the customer may pay on arrival.

rateTotalAmount€135

Additional on arrival€105

estimatedTotalAmount€240

`rateTotalAmount`

Invoiceable between Surprice and you. Product cost plus charges included in the rate. Prepaid or paid on arrival, depending on the rate code.

Product Cost€150
Promo Code−€15
rateTotalAmount€135

Additional costs on arrival

Charges in the estimated total but not in the rate. The customer may have to pay these at the counter.

Location surcharge€20
Additional driver€20
Child seat€25
Reduced excess cover€40
Difference€105

Figures from the Create a reservation example response. Charges are tax-inclusive; VAT is included in every amount, and the separate VAT line is informational. Deposits and excess are not part of either total.

Field	Meaning
`estimatedTotalAmount`	The full expected cost of the rental: `rateTotalAmount` plus any additional charges the customer may have to pay on arrival.
`rateTotalAmount`	The invoiceable amount between Surprice and you, the broker: product cost plus charges included in the rate. Prepaid or paid on arrival, depending on the rate code. Not a refund amount.
`amount / currencyCode`	Charge total and currency. Catalog amounts may be numeric strings; totalCharge values are numbers.
`includedInEstTotalInd / includedInRate / isPrepaid`	`includedInRate` and `includedInEstTotalInd` decide which total a charge counts toward; a charge with neither is informational. `isPrepaid` is set per item and shows whether that item is prepaid; check it on each charge rather than inferring it from the rate code. Charges are already in the totals, so don’t add them again.
`VAT / VATPercentage`	Tax information for reference. VAT is always included in every charge amount, so never add it on top.
`breakdown[]`	Components of a charge (description, amount). Some items are only informational and count toward neither `rateTotalAmount` nor `estimatedTotalAmount`; the corresponding inclusion flags on each decide what counts. Never add breakdown amounts to the totals.
`calculationInfo`	quantity, unitCharge and unitName. Rounded unit values need not multiply exactly to the total.
`originalAmount / discountValue / discountedQuantity / maxCost`	Discount/cap details; already applied to amount.

Currency behavior

Request a currency with currencyCode in availability. Booking uses the quote’s currency. Always check the returned currencyCode; it may differ from your request.

Currency can differ in getRate and amendment responses. After an amendment, check the currency again in GET responses.

Deposits and excess are separate from the rental total.

Pagination#

Station search, catalogs, cities and countries accept limit (1–1000) and offset (≥ 0; default 0). Both are integers. Specify limit explicitly for consistent page sizes.

Use returned limit, offset and total. Set the next offset to offset + limit; stop at total. Advance by limit even if fewer results are returned. Results can change between requests.

Empty pages: 404 for stations/cities/countries; 200 with results.results: [] for catalogs. Rate codes and SIPP dictionaries are not paginated.

Errors and retries#

Check HTTP status and body. Request-validation errors use 400, authentication errors 401, and business errors usually 422. The numeric pair below is type/code; codes are not HTTP statuses.

Business error · usually HTTP 422

{"type": 3, "code": 263, "message": "No rate could be found for the given information"}

Validation error · HTTP 400

{"errors": ["pickUpDateTime must be a string"]}

Simple error response

{
  "error": "Missing body"
}

Wrapped business error · HTTP 422

{
  "status": 422,
  "body": {
    "type": 3,
    "code": 263,
    "message": "No rate could be found for the given information"
  }
}

HTTP / code	Handling
400	Correct fields, types or query values.
401	Check Bearer casing and an active, unexpired key.
404	Missing station or empty reference page. Reservation lookup uses 422/284.
422 · 3/168	Broker account unavailable or inactive. Contact support.
422 · 3/221	No matching vehicle. Change the search.
422 · 3/263	Quote unavailable or incompatible. Before booking, re-run availability for the trip. For amendment, the saved booking rate is unavailable; contact support.
422 · 3/127 or 3/128	Duplicate reference or booking. Look up the booking before retrying.
422 · 3/284	No latest booking in your account. Try a stable reference instead of an old UUID.
422 · 3/90, 3/118, 3/95, 3/264	Action blocked by policy or current status. Read the booking first.
422 · 3/226	Pickup date has passed.
422 · 3/229, 3/233	Pickup or return station unknown/inactive.
422 · 3/214, 3/227	Return or pickup outside service hours.
422 · 3/222, 3/224, 3/225	Cross-border or one-way route not permitted.
422 · 3/135, 3/230	Invalid rental datetime format or return before pickup.
422 · rate/promotion errors	249/536: check rate and promotion. 320: invalid data, also used for routes and partner IDs; read the message.
422 · 13/188; HTTP 500 / 502	Service failure. Retry reads with backoff; check booking state before retrying changes. Contact support if persistent.

Retry transient read failures with bounded backoff. After an uncertain create, amend, commit, ignore or cancel, GET the booking by stable reference before retrying. The change may already have succeeded.