# Payment schedules **Understand how payment schedules represent when and how much is charged for a booking, using data returned in /orders/preview for accommodation and car rental (v3.2).** ## In this guide * What payment schedules are. * How schedules are structured in /orders/preview. * Key fields and concepts (dates, pay, display) * Accommodation vs car rental differences. * Worked examples. * UI and integration guidance. ## What are payment schedules? Payment schedules define the **full breakdown of payments across a booking lifecycle**. A single order may involve multiple payment events, depending on: * Payment timing (see [Payment timings guide](/demand/docs/payments/payments-timings)) * Supplier or property policies. * Taxes, deposits, and extra charges. * Payment method rules. Use payment schedules data to: ✓ Show **exact payment breakdowns across time.** ✓ Separate **upfront vs later charges**. ✓ Display **all booking-related costs transparently**. ✓ Prevent unexpected charges at checkout or fulfilment. ## Payment schedule structure (orders/preview) In /orders/preview, payment timing is expanded into a schedule of payment events, that **defines when and how much is charged.** ### Dates * Each payment timing contains a `dates` array. * Each item in `dates` represents a single **payment event**. ### Payment event structure * Each event includes: * `at` → when the payment occurs. * `price` (accommodation) or `amount` (car) → how much is charged. ### Monetary values Each monetary value may include: * `pay` → the actual amount that will be charged. * `display` → the amount shown to the traveller (may differ due to currency or rounding). ### Key rules * A schedule may include multiple payment events. * The sum of all `pay` values represents the total collected via the API. * Some charges may be excluded due to legal or supplier constraints. The sum of all payment events in `dates` represents the total amount collected through the API. Extra charges Some additional charges (for example, tourist taxes, deposits, etc) may not be included in this total and are paid at the property or pickup. ### Payment method requirement The `method_required` field indicates whether a payment method must be provided at booking time. * `true` → the traveller must provide a payment method (even if no charge is made at booking). * `false` → no payment method is required at booking. #### Typical use cases * Guaranteeing bookings without upfront payment. * Deferred charging models. * Supplier-managed payments. See the [payment methods](/demand/docs/payments/payments-methods) section for more details. ### Extra charges Some charges are handled separately due to legal or supplier rules. Examples include: * Tourist taxes (legal requirement) * Security deposits. * Damage excess. * Fuel or service fees. These: * May not be included in upfront payment events. * May appear as separate schedule entries. * May be collected at property or pick-up. Refer to the [Accommodation pricing section](/demand/docs/accommodations/prices-accommodations) for more details. ### Key difference: accommodation vs car | Aspect | Accommodation | Car rental | | --- | --- | --- | | Payment structure | Grouped by timing object | Attached per price component | | Data location | `payment.dates` | `price.*.pay/display.timing` | | Evaluation model | Schedule-level | Field-level | | Complexity | Policy-driven | Component-driven | ## Accommodation schedules in orders/preview Accommodation schedules are returned in: `data.accommodation.general_policies.payment` ### Pay online now - example In the following orders/preview response taken as example, there are 2 events "2025-01-18" (booking date) and "2025-02-10" (checkin date) together with `price` to pay each date: ```json { "accommodation": { "general_policies": { "payment": { "pay_online_now": { "method_required": true, "dates": [ { "at": "2025-01-18", "price": { "accommodation_currency": 200.64, "booker_currency": 200.64 } }, { "at": "2025-02-10", "price": { "accommodation_currency": 5.14, "booker_currency": 5.14 } } ] } } } } } ``` **Interpretation:** * Full amount is charged at booking. * Any other additional payments such as extra charges are collected at checkin. ### Pay online later - example In this orders/preview response, there are 3 date events "2025-01-18" (booking date), "2025-02-02" (payment date) and "2025-02-10" (checkin date): ```json { "accommodation": { "general_policies": { "payment": { "pay_online_later": { "method_required": true, "dates": [ { "at": "2025-01-18", "price": { "accommodation_currency": 0.00, "booker_currency": 0.00 } }, { "at": "2025-02-02", "price": { "accommodation_currency": 200.64, "booker_currency": 200.64 } }, { "at": "2025-02-10", "price": { "accommodation_currency": 5.14, "booker_currency": 5.14 } } ], "methods": { "cards": [1, 2, 3, 4, ...] } } } } } } ``` **Interpretation:** * At booking: no charge. * Before cancellation deadline: full amount is charged. * Check-in: extra charges (if applicable) Not supported for certain credit card types (see [payment timings details](/demand/docs/payments/payments-timings#payment-timing-values)). ### Pay at the property - example In the following orders/preview response taken as example, there are 2 date items "2026-11-18" (booking date) and "2026-12-01" (checkin date): ```json { "accommodation": { "general_policies": { "payment": { "pay_at_the_property": { "method_required": true, "dates": [ { "at": "2026-11-18", "price": { "accommodation_currency": 0.00, "booker_currency": 0.00 } }, { "at": "2026-12-01", "price": { "accommodation_currency": 205.78, "booker_currency": 205.78 } } ], "methods": { "cards": [1, 2, 3, 4, ...] } } } } } } ``` **Interpretation:** * At booking: no charge * At check-in: full amount is paid at the property. #### Pay at the property with prepayment There are cases when the property sets a prepayment policy, scheduling an instalment between the booking and checkin date. Example: ```json { "general_policies": { "payment": { "pay_at_the_property": { "method_required": true, "dates": [ { "at": "2026-11-18", "price": { "accommodation_currency": 0.00, "booker_currency": 0.00 } }, { "at": "2026-11-30", "price": { "accommodation_currency": 57.27, "booker_currency": 57.27 } }, { "at": "2026-12-01", "price": { "accommodation_currency": 76.29, "booker_currency": 76.29 } } ] } } } } ``` **Interpretation:** * At booking: no charge. * Before arrival: partial prepayment. * At check-in: remaining balance. This flexible split is controlled by property policy. ## Car rental payment schedules in orders/preview Car rental does not group payments into timing objects. Instead, timing is defined at **field level**. Timing appears in: * `price.base` * `price.total` * `extra_charges` * `policies.payment.dates` (deposit, excess, etc.) Important * Each monetary field must be evaluated independently. * There is no global schedule object for car rental payments. ### Car rental - pay_online_now example ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "car": { "offer": 123456789, "currency": { "booker": "EUR", "payment": "EUR" }, "price": { "base": { "display": { "value": 129.99, "currency": "EUR", "timing": "pay_online_now" }, "pay": { "value": 129.99, "currency": "EUR", "timing": "pay_online_now" } }, "extra_charges": [ { "non_conditional": [ { "charge_type": "one_way_fee", "amount": { "display": { "value": 15.0, "currency": "EUR" }, "pay": { "value": 15.0, "currency": "EUR", "timing": "pay_online_now" } } } ] } ], "total": { "value": 144.99, "currency": "EUR", "timing": "pay_online_now" } }, "policies": { "cancellation": { "details": { "context": "before_pickup", "duration": "PT48H" }, "type": "free_cancellation" }, "damage_excess": { "amount": { "display": { "value": 1000.0, "currency": "EUR", "timing": "pay_at_pickup" }, "pay": { "value": 1000.0, "currency": "EUR", "timing": "pay_at_pickup" } } }, "deposit": { "amount": { "display": { "value": 200.0, "currency": "EUR", "timing": "pay_at_pickup" }, "pay": { "value": 200.0, "currency": "EUR", "timing": "pay_at_pickup" } } }, "fuel_policy": "return_same", "mileage": { "distance_limit": 300.0, "distance_unit": "kilometers", "type": "limited" }, "payment": { "dates": [ { "at": "2026-04-20", "amount": { "display": { "value": 169.99, "currency": "EUR", "timing": "pay_online_now" }, "pay": { "value": 169.99, "currency": "EUR", "timing": "pay_online_now" } } } ] } }, ... ``` ### Example scenario - A mixed payment order In many rentals, the total cost is split. In the example below, the rental price is paid online, but the damage excess are handled at the desk. ```json { "price": { "total": { "value": 129.99, "currency": "EUR", "timing": "pay_online_now" } }, "policies": { "damage_excess": { "amount": { "display": { "value": 300.00, "currency": "EUR", "timing": "pay_at_pickup" }, "pay": { "value": 300.00, "currency": "EUR", "timing": "pay_at_pickup" } } } } ``` **Interpretation:** **Immediate Payment (pay_online_now)** * The `price.total` shows €129.99. * Charged when booking online. * Since the timing is `pay_online_now`, the checkout UI should trigger a payment gateway (credit card, digital wallet, etc.) for this amount immediately. **Counter information (pay_at_pickup)** * Not charged online. * Traveller must provide a card at the rental desk. * The `damage.excess` shows €300.00. * The UI should inform the traveller that they need to have a credit card available at the rental desk for a pre-authorisation, but this amount is not charged during the online checkout. Curious to know more? For additional information: * [Displaying payments guide](/demand/docs/payments/payments-display) * [Payment methods](/demand/docs/payments/payments-methods) * [Payment timings](/demand/docs/payments/payments-timings)