Car rental tutorial

Follow this end-to-end tutorial to build a complete Search, look and book integration for car rentals using Demand API Beta version.

Before following this tutorial, complete the Getting started prerequisites.

Make sure you have:

✓ A valid API key token.
✓ Your X-Affiliate-Id
✓ Access to the try out console.

Throughout this tutorial we'll follow a single booking journey.

A traveller wants to rent a car at Barcelona Airport (BCN)
Pickup and Drop-off: Barcelona Airport (BCN) Duration: 3 days, 2 adults, unlimited mileage preferred.
Payment: Pay at pickup. The selected offer does not require a credit card to be supplied with the booking.

We'll progressively build the booking flow using the data returned at each step.

During the availability step, you'll learn how to identify whether a pay at pickup offer requires a credit card and how this determines whether payment and card details must be included when creating the order.

The Search, look and book flow consists of these steps:

You'll use several identifiers throughout the integration.

→ Call the cars/search to discover available rental cars.

{
    "booker": {
      "country": "es"
    },
    "language": "en-gb",
    "currency": "EUR",
    "driver": {
      "age": 30
    },
    "route": {
      "pickup": {
        "datetime": "2026-11-10T11:05:00",
        "location": {
          "airport": "BCN"
        }
      },
      "dropoff": {
        "datetime": "2026-11-15T11:05:00",
        "location": {
          "airport": "BCN"
        }
      }
    }
  }

At this stage you should display enough information for travellers to compare available vehicles and choose the option that best suits their needs.

The search response intentionally contains only summary information.

Use the static car reference endpoints to retrieve additional reference data that can be stored and reused:

• /cars/details
• /cars/suppliers
• /cars/depots

→ Call /cars/details using your regular synchronisation process.

{
    "last_modified": "2026-08-31T10:00:00+00:00",
    "maximum_results": 100
}

→ Try it yourself

Combine the dynamic search results with the static vehicle information to display a richer product page.

Recommended information includes:

• Vehicle photo.
• Transmission.
• Fuel type.
• Passenger capacity.
• Luggage capacity.
• Supplier branding.
• Depot information.

Once a traveller selects an offer, call /cars/availability using the following values returned by /cars/search:

• offer
• search_token
• currency

{
  "offer": 664812451,
  "search_token": "your_search_token",
  "currency": "EUR"
}

→ Try it yourself

Check price.credit_card_required to determine whether a credit card must be supplied when the order is created.

The field can return:

{
    "request_id": "01kb0at8s75xpngj1gg88mpbrt",
    "data": {
        "offer": 664812451,
        "currency": "EUR",
        "policies": {
            "payment": {
                "timing": "pay_at_pickup"
            }
        },
        "price": {
            "base": 83.90,
            "total": 83.90,
            "credit_card_required": true,
            "extra_charges": []
        }
    }
}

In this case, collect the traveller's card details and include the payment object when calling /orders/create.

{
    "request_id": "01kb0at8s75xpngj1gg88mpbrt",
    "data": {
        "offer": 664812451,
        "currency": "EUR",
        "policies": {
            "payment": {
                "timing": "pay_at_pickup"
            }
        },
        "price": {
            "base": 83.90,
            "total": 83.90,
            "credit_card_required": false,
            "extra_charges": []
        }
    }
}

In this case, if there is no amount payable online, you do not need to collect card details for the booking and can omit payment when calling /orders/create.

Some car rental offers include an optional third-party insurance product. The complete, bookable insurance quote is returned in the /cars/availability response.

If the insurance object is present:

1. Display the insurance option and its price to the traveller.
2. Provide access to the returned policy documentation before purchase.
3. If the traveller selects the insurance, store its quote_reference.
4. Pass the quote_reference in the /orders/preview request.

Example:

{
  "insurance": {
    "quote_reference": "ABC123",
    "name": "Full Protection",
    "id": "999",
    "price": {
      "display": {
        "value": 144.70,
        "currency": "GBP"
      },
      "pay": {
        "value": 144.70,
        "currency": "EUR",
        "timing": "pay_online_now"
      }
    },
    "documents": [
      {
        "name": "policy_document",
        "url": "https://staging.rentalcover.com/en/pds"
      },
      {
        "name": "ipid",
        "url": "https://staging.rentalcover.com/en/pds"
      }
    ]
  }
}

• The quote_reference identifies the selected insurance quote - Do not use the insurance id as a replacement for the quote_reference.

• If the insurance payment timing is pay_online_now, include the required payment details when creating the order - The final payment requirements are determined during the preview and creation steps.

→ Use the cars/terms-and-conditions endpoint.

{
  "offer": "664812451", 
  "search_token": "12456895645246585",
  "currency": "EUR",
  "language": "es"
}

• Damage excess and deposit amounts.
• Accepted credit/debit cards.
• Driver & licence requirements.
• Mileage rules.
• Included insurance and waivers.

→ Try it yourself

→ Use /orders/preview to confirm:

• What will be booked.
• Price and currency.
• Payment timing and amounts.
• Cancellation and policies.

To construct the orders/preview request, you need the same values returned in previous steps:

• offer
• search_token
• currency

Example:

{
  "currency": "EUR",
  "car": {
    "offer": 664812451, 
    "search_token": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

The orders/preview response returns the validated booking information and an order_token that you use to create the order.

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "car": {
      "offer": 123456789,
      "currency": {
        "booker": "EUR",
        "payment": "EUR"
      },
      "price": {
        "base": {
          "display": {
            "value": 129.99,
            "currency": "EUR",
            "timing": "pay_at_pickup"
          },
          "pay": {
            "value": 129.99,
            "currency": "EUR",
            "timing": "pay_at_pickup"
          }
        },
        "extra_charges": [],
        "total": {
          "display": {
            "value": 154.99,
            "currency": "EUR",
            "timing": "pay_at_pickup"
          },
          "pay": {
            "value": 154.99,
            "currency": "EUR",
            "timing": "pay_at_pickup"
          }
        }
      },
      "policies": {
        "cancellation": {
          "details": {
            "context": "before_pickup",
            "duration": "PT48H"
          },
          "type": "free_cancellation"
        },
        "damage_excess": {
          "amount": {
            "display": {
              "value": 900.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            },
            "pay": {
              "value": 900.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            }
          }
        },
        "deposit": {
          "amount": {
            "display": {
              "value": 300.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            },
            "pay": {
              "value": 300.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            }
          }
        },
        "fuel_policy": "return_same",
        "mileage": {
          "distance_limit": 300,
          "distance_unit": "kilometers",
          "amount": 0.25,
          "type": "limited"
        },
        "theft_excess": {
          "amount": {
            "display": {
              "value": 1200.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            },
            "pay": {
              "value": 1200.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            }
          }
        }
      }
    },
    "order_token": "eyJhIjoiYmNkIn0"
  }
}

→ Try it yourself

Before creating the order, use the latest selected offer and the /orders/preview response to determine whether payment details are required.

Check:

• Whether the selected offer is payable at pickup.
• Whether the offer returns credit_card_required=false.
• Whether the accepted price has any amount to be paid online.

For example in this case a selected damage_excess must be paid online:

      "policies": {
        "cancellation": {
          "details": {
            "context": "before_pickup",
            "duration": "PT48H"
          },
          "type": "free_cancellation"
        },
        "damage_excess": {
          "amount": {
            "display": {
              "value": 900.00,
              "currency": "EUR",
              "timing": "pay_online_now"
            },
            "pay": {
              "value": 900.00,
              "currency": "EUR",
              "timing": "pay_online_now"
            }
          }
        },
        "deposit": {
          "amount": {
            "display": {
              "value": 300.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            },
            "pay": {
              "value": 300.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            }
          }
        },
        "fuel_policy": "return_same",
        "mileage": {
          "distance_limit": 300,
          "distance_unit": "kilometers",
          "amount": 0.25,
          "type": "limited"
        },
        "theft_excess": {
          "amount": {
            "display": {
              "value": 1200.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            },
            "pay": {
              "value": 1200.00,
              "currency": "EUR",
              "timing": "pay_at_pickup"
            }
          }
        }
      }
    },
    "order_token": "eyJhIjoiYmNkIn0"
  }
}

You can now present the traveller with the final booking summary, including:

• What they are booking.
• What they will have to pay.
• When and how they can pay it.
• And the cancellation terms that will apply.

→ Select the data from your /orders/preview response to provide the appropriate information on your preview page.

After checking the details of the order, collect payment information when required for the selected offer, then proceed with the booking.

→ Call /orders/create to submit the car rental order request.

Include:

• Driver details in car.driver, including the mandatory car.driver.email.
• The required booker details.
• The payment object when the selected offer requires payment details:
  • Use the latest offer and the value from the latest /cars/availability response, to determine whether you must provide card details.
  • The payment.timing value alone does not determine whether the payment object is required.
• The order_token returned by /orders/preview.

Include payment with method=card and the required card details when:

• The accepted price contains a pay_online_now component, including when a selected add-on, such as insurance or damage_excess, must be paid online.
• The car offer is pay_at_pickup and returns credit_card_required=true.
• The car offer is pay_at_pickup and credit_card_required is null, missing or unavailable.

This includes pay_online_now, pay_partial_online_now and pay_at_pickup orders where the rental company requires a card guarantee.

Example:

{
  "order_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.car-preview-token",
  "car": {
    "driver": {
      "title": "Mr",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@booking.com",
      "telephone": "+44 20 1234 5678",
      "address": {
        "address_line1": "221B Baker Street",
        "address_line2": "",
        "city": "London",
        "country": "gb",
        "postcode": "NW1 6XE"
      }
    },
    "label": "summer_campaign_2025"
  },
  "booker": {
    "address": {
      "address_line": "221B Baker Street",
      "city": "London",
      "country": "gb",
      "post_code": "NW1 6XE"
    },
    "company": "ACME Travel",
    "email": "john.doe@example.com",
    "language": "en-gb",
    "name": {
      "first_name": "John",
      "last_name": "Doe"
    },
    "telephone": "+44 20 1234 1111"
  },
  "payment": {
    "timing": "pay_at_pickup",
    "method": "card",
    "card": {
      "cardholder": "John Doe",
      "number": "4111111111111111",
      "expiry_date": "2028-12",
      "cvc": "123",
      "authentication": {
        "3d_secure": {
          "authentication_value": "AAABBJg0VhI0VniQEjRGAAAAAAA=",
          "eci": "05",
          "transaction": "3ds-trans-123456"
        }
      }
    },
    "include_receipt": true
  }
}

→ Try it yourself

You may omit both the payment object and booker.address only when all of the following conditions apply:

• The payment timing is pay_at_pickup.
• The latest offer information explicitly returns credit_card_required=false in /cars/availability.
• The accepted price does not contain any pay_online_now component.

For example, a pay-at-pickup car offer with credit_card_required=false can be booked without card details when no selected add-ons introduce an amount payable online.

For example, the following request creates an eligible cardless car order:

{
  "order_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.car-preview-token",
  "car": {
    "driver": {
      "title": "Mr",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@booking.com",
      "telephone": "+44 20 1234 5678",
      "address": {
        "address_line1": "221B Baker Street",
        "address_line2": "",
        "city": "London",
        "country": "gb",
        "postcode": "NW1 6XE"
      }
    },
    "label": "summer_campaign_2025"
  },
  "booker": {
    "company": "ACME Travel",
    "email": "john.doe@example.com",
    "language": "en-gb",
    "name": {
      "first_name": "John",
      "last_name": "Doe"
    },
    "telephone": "+44 20 1234 1111"
  }
}

The response confirms that the booking request has been accepted and contains:

• order - Unique identifier for the order.
• reservation_id - Booking reference for the car reservation.
• status - Always returns Processing - Use /orders/details/cars/live to retrieve the latest booking status.

{
  "request_id": "01kb1f9r4s8z3n7q2w5x6y8z9a",
  "data": {
    "order": "987654321",
    "car": {
      "reservation_id": "CAR-123456789",
      "status": "Processing"
    }
  }
}

Including a car insurance in the order can affect whether card details are required when creating the order.

Insurance does not by itself require a card. However, if the selected insurance introduces an amount payable online, you must include payment with method=card and the required card details.

You may omit both payment and booker.address only when:

• The selected car offer returns credit_card_required=false.
• There are not additional amounts that must be paid online.
• The selected offer is payable at pickup.

If the selected insurance must be paid online:

• You must include the booker.address and payment object with valid card details when calling /orders/create.
• This is mandatory even if the car offer returns credit_card_required=false.

If the selected insurance does not result in an amount that must be paid online:

• It does not by itself require card details.
• The booking can remain cardless provided the car offer returns credit_card_required=false and there is no online payment amounts.

You should now support:

After creating the order, choose one of the following options to keep your system up to date and provide a post-booking experience for travellers.

Call /orders/details/cars/live to retrieve the latest status and reservation details for the order.

This endpoint lets you:

• Check whether the order has been confirmed.
• Retrieve the supplier confirmation number.
• Display pickup instructions.
• Retrieve insurance documents, if purchased.
• Display the latest order details to the traveller.

You can also use the Notifications service to receive a notification in your system whenever a car order is updated.

• This allows you to keep your local order data up to date without repeatedly polling /orders/details/cars/live.
• The Notifications service is separate from the Demand API and requires additional setup. Before using it, make sure that you meet the Notifications service requirements.

Continue with the Post-booking management section to learn how to manage confirmed orders.