Create the reservation (booking step 8)

Final step of the booking flow. Validates the dates, availability, charges and discounts again, links or creates the customer, and saves the reservation. Send the full booking context: nothing from the earlier steps is stored.

Resulting status. By default the reservation gets the account's default status for new reservations (open unless configured otherwise, and always open when bookings are confirmed without payment). Use action to choose another status.

Customer. Resolved in this order: customer_id; customer_first_name/customer_last_name (+ customer_email), which reuses a contact with exactly the same first name, last name and email or creates one; customer_full_name/customer_email; otherwise the generic contact fields (first_name, last_name, birthdate, field_<id>) as in step 6, including contact_id or external_contact_type + external_contact_id. customer_* address and driver's license fields are written to the contact, except when customer_id is sent; then they are ignored.

Side effects. Sends the customer confirmation email unless skip_confirmation_email is true (the default follows the setting that disables confirmation emails for API bookings), and sends the internal new-booking notification. Records prepaid_amount as an approved payment, adds comments and additional_drivers, stores the OTA source and reference, and closes the reservation attempt of reservation_attempt_uuid (and other attempts with the customer's email or phone). With return_payment_link, an online payment is started and its link returned in data.transaction.payment_link.

Retries. Send an Idempotency-Key header to make retries safe. A key already used on this path in the last 24 hours is rejected with 422, and errors.idempotency_value holds the ID of the reservation the first request created. If it is empty, read the reservation before retrying (see Rate limits and idempotency). A business-rule failure (HTTP 200, success: false) also uses up the key, so send a new key after fixing the request. An error response does not guarantee that nothing was created, so look the reservation up before retrying. Cancelling a reservation through the API resets every stored key of your account, so a retry after a cancellation is not deduplicated. The created reservation ID is also returned in the X-Idempotent-Id header.

Request

Authorization

Header Params

Body Params application/jsonRequired

Example

{
    "pick_up_date": "2026-12-01",
    "pick_up_time": "10:00",
    "return_date": "2026-12-05",
    "return_time": "10:00",
    "pick_up_location": 1,
    "return_location": 1,
    "brand_id": 1,
    "vehicle_class_id": 3,
    "additional_charges": [
        "12"
    ],
    "customer_id": 4821,
    "return_payment_link": true,
    "payment_external_redirect": "https://www.example.com/booking/thank-you",
    "reservation_attempt_uuid": "6f1d2c9a-3b7e-4f61-8d2a-0c5e9b4a7f13"
}

Responses

🟢200OK

application/json

HTTP 200 is also used for failures: always check success. When it is false, the body is an ErrorBusinessRule (status_code 410) or an ErrorUnauthorized (status_code 401 or 403). Business-rule failures here include a class or vehicle that is no longer available, an invalid coupon, customer form errors, "A customer is required to create a reservation" and "Reservation Already Exists". No reservation is created in those cases.

Headers

Bodyapplication/json

Examples

Reservation created with a payment linkClass no longer available (HTTP 200)

{
    "success": true,
    "status_code": 200,
    "errors": [],
    "data": {
        "reservation": {
            "id": 1052,
            "header": "Jane Doe - RA #1052",
            "pick_up_date": "2026-12-01 10:00:00",
            "return_date": "2026-12-05 10:00:00",
            "flight_arrival_date": "2026-12-01 10:00:00",
            "flight_departure_date": "2026-12-05 10:00:00",
            "flight_number": "",
            "flight_departure_number": "",
            "pick_up_location": {
                "id": 1,
                "name": "Miami Airport",
                "timezone": "America/New_York"
            },
            "return_location": {
                "id": 1,
                "name": "Miami Airport",
                "timezone": "America/New_York"
            },
            "vehicle_class_id": 3,
            "customer_id": 4821,
            "public_link": "https://yourcompany.example.com/public/car-rental/reservations/step1?id=0d8e5b7a-2c4f-4a1e-9b3d-7f6a5c4e3b21&contact_uuid=5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
            "comments": [],
            "distance_limits": {
                "distance_allowed": 0,
                "distance_limit_per_day": 0,
                "distance_unit": "mi",
                "distance_unlimited": true,
                "distance_extra_price": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "0.00",
                    "usd_amount": "0.00",
                    "amount_for_display": "$0.00"
                },
                "distance_extra_price_with_tax": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "0.00",
                    "usd_amount": "0.00",
                    "amount_for_display": "$0.00"
                }
            },
            "status": "open",
            "uuid": "0d8e5b7a-2c4f-4a1e-9b3d-7f6a5c4e3b21",
            "distance_driven": 0
        },
        "tour_operator": [],
        "selected_vehicle_class": {
            "vehicle_class_id": 3,
            "sipp_code": "CDAR",
            "price": {
                "total_days": 4,
                "base_price": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "180.00",
                    "usd_amount": "180.00",
                    "amount_for_display": "$180.00"
                },
                "base_price_with_taxes": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "198.00",
                    "usd_amount": "198.00",
                    "amount_for_display": "$198.00"
                },
                "details": [],
                "total_price_with_mandatory_charges_and_taxes": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "220.00",
                    "usd_amount": "220.00",
                    "amount_for_display": "$220.00"
                }
            },
            "vehicle_class": {
                "label": "Compact",
                "short_description": "Nissan Versa or similar",
                "description": "",
                "features": [],
                "image": "https://yourcompany.example.com/public/fleets/images/3f1c9e2a-7b4d-4c8e-9a6f-1d2e3c4b5a69/vehicle-class",
                "recommended": false
            }
        },
        "selected_additional_charges": [
            {
                "id": 12,
                "label": "GPS",
                "selection_type": "only_one",
                "selected_quantity": 1,
                "charge_type": "daily",
                "base_price": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "5.00",
                    "usd_amount": "5.00",
                    "amount_for_display": "$5.00"
                },
                "total_price": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "20.00",
                    "usd_amount": "20.00",
                    "amount_for_display": "$20.00"
                }
            }
        ],
        "external_charges": [],
        "vehicle_damages": [],
        "applicable_discounts": [],
        "applicable_taxes": [
            {
                "name": "Sales Tax (10%)",
                "base_price": 10,
                "charge_type": "percent",
                "total_amount": {
                    "currency": "usd",
                    "currency_icon": "$",
                    "amount": "20.00",
                    "usd_amount": "20.00",
                    "amount_for_display": "$20.00"
                }
            }
        ],
        "total": {
            "show_security_deposit": true,
            "show_security_deposit_excess": false,
            "outstanding_balance": {
                "currency": "usd",
                "currency_icon": "$",
                "amount": "220.00",
                "usd_amount": "220.00",
                "amount_for_display": "$220.00"
            },
            "outstanding_security_deposit": {
                "currency": "usd",
                "currency_icon": "$",
                "amount": "300.00",
                "usd_amount": "300.00",
                "amount_for_display": "$300.00"
            },
            "security_deposit": {
                "currency": "usd",
                "currency_icon": "$",
                "amount": "300.00",
                "usd_amount": "300.00",
                "amount_for_display": "$300.00"
            },
            "security_deposit_excess": {
                "currency": "usd",
                "currency_icon": "$",
                "amount": "0.00",
                "usd_amount": "0.00",
                "amount_for_display": "$0.00"
            },
            "total_paid": {
                "currency": "usd",
                "currency_icon": "$",
                "amount": "0.00",
                "usd_amount": "0.00",
                "amount_for_display": "$0.00"
            },
            "total_price": {
                "currency": "usd",
                "currency_icon": "$",
                "amount": "220.00",
                "usd_amount": "220.00",
                "amount_for_display": "$220.00"
            }
        },
        "customer": {
            "id": 4821,
            "entity": "person",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone_number": "+1 305 555 0142",
            "country": "US",
            "birthdate": "1990-04-15"
        },
        "additional_drivers": [],
        "transaction": {
            "id": 311,
            "amount": {
                "currency": "usd",
                "currency_icon": "$",
                "amount": "220.00",
                "usd_amount": "220.00",
                "amount_for_display": "$220.00"
            },
            "label": "Reservation #1052",
            "uuid": "9b2f6c3e-58a1-4d4e-9a57-2f0c1d7e8a90",
            "gateway": "Stripe",
            "payment_link": "https://yourcompany.example.com/public/payment-gateways/payment-transactions/9b2f6c3e-58a1-4d4e-9a57-2f0c1d7e8a90/external"
        }
    }
}

🟠422Record Not Found

🟠404Parameter Error