Cancellations and refunds

How cancellation policies readCopy Anchor Link

cancellationPolicies[] is a list of penalty steps. Each step says "from date on, cancelling costs amount". A step with amount 0 means free until the next step's date, and the last step is usually the full price. The steps are cumulative: each amount is the whole penalty from its date, not an extra charge on top of the previous step. Spec

{
  "price": { "amount": 808.04, "currency": "EUR" },
  "cancellationPolicies": [
    { "date": "2026-10-01", "amount": { "amount": 0.0, "currency": "EUR" } },
    { "date": "2026-11-07", "amount": { "amount": 444.46, "currency": "EUR" } },
    { "date": "2026-11-10", "amount": { "amount": 808.04, "currency": "EUR" } }
  ],
  "currentCancellationType": { "deadline": "2026-11-07", "type": "REFUNDABLE" }
}

For a stay from 2026-11-10 to 2026-11-14, this reads:

Each step (CancellationPolicyVO) also carries netPrice, nonCommissionableAmount, commissionPriceAmount and policyAmount, which has a microsite and an operator leg. Spec

type Money = { amount: number; currency: string };
type PolicyStep = { date: string; amount: Money };

/** The penalty on `day` (yyyy-MM-dd): the last step whose date is on or before it. */
export function penaltyOn(steps: PolicyStep[], day: string): Money | null {
  let fee: Money | null = null;
  for (const s of [...steps].sort((a, b) => a.date.localeCompare(b.date))) {
    if (s.date <= day) fee = s.amount;
  }
  return fee; // null: the day is before the first step
}

Use this for display only. For a booked service, the cancellation fee endpoint gives the real number.

Which policy to trustCopy Anchor Link

• currentCancellationType has type and deadline. type is REFUNDABLE (free until deadline), PARTIALLY_REFUNDABLE, NON_REFUNDABLE or UNKNOWN. It only appears in quote responses. Spec
• If Confirm or Prebook returns a CANCELLATION_POLICIES_CHANGE warning, show the new terms and get the guest's consent again. A refundable rate may have become non-refundable.

Show the booking-level dateCopy Anchor Link

The service-level cancelPolicy[].date is serialised in UTC. The booking-level cancellationPolicies[].date is in the operator's local time, which is what agents see in the back office. Near midnight the two differ by a day: for example, the service shows 2026-11-06 while the booking level shows 2026-11-07. Verified

• Show the booking-level date to people.
• Suppliers apply deadlines in the hotel's local time. Tell guests they can cancel free "before <date>", not "until <date>".

Quote the fee, then cancelCopy Anchor Link

Two calls on the same path look alike and do very different things.

const BASE = process.env.NAVA_BASE_URL!;

export async function cancelHotel(
  token: string,
  ref: string, // bookingReference, for example TST-1464
  accRef: string, // accommodation.bookingReference, for example TST-1464-0
  guestAccepts: (fee: Money) => Promise<boolean>,
) {
  const path = `/booking/${encodeURIComponent(ref)}/accommodations/${encodeURIComponent(accRef)}`;

  // 1. Read-only: what does cancelling today cost?
  const { cancellationFee } = await call(token, 'GET', `${path}/cancellation-fee`);
  if (!(await guestAccepts(cancellationFee))) return { outcome: 'kept' as const };

  // 2. Cancel once. Never retried automatically.
  let booking;
  try {
    booking = await call(token, 'DELETE', path, 120_000);
  } catch {
    // Timeout or network drop: the outcome is unknown. Read stored state instead of cancelling again.
    booking = await call(token, 'GET', path);
  }

  const cancelled = booking.status === 'CANCELED' && booking.accommodation?.status === 'CANCELED';
  if (!cancelled) return { outcome: 'needs_person' as const, booking }; // a person checks, then decides
  return { outcome: 'cancelled' as const, booking, fee: cancellationFee }; // next: refund minus the fee
}

async function call(token: string, method: string, path: string, timeoutMs = 60_000) {
  const res = await fetch(BASE + path, {
    method,
    headers: { 'auth-token': token, 'Accept-Encoding': 'gzip' },
    signal: AbortSignal.timeout(timeoutMs),
  });
  const json = await res.json();
  if (json?.auditData?.authToken) json.auditData.authToken = '[REDACTED]';
  log(method, path, res.status, json?.auditData?.traceId);
  if (!res.ok) throw new ApiError(res.status, json);
  return json;
}

{
  "auditData": {
    "authToken": "[REDACTED]",
    "traceId": "D4AE54C6-…"
  },
  "cancellationFee": { "amount": 150.0, "currency": "EUR" }
}

{
  "auditData": {
    "authToken": "[REDACTED]",
    "traceId": "…"
  },
  "bookingReference": "TST-1464",
  "externalReference": "ORDER-8812",
  "status": "CANCELED",
  "accommodation": {
    "code": "MASTER-1782232",
    "bookingReference": "TST-1464-0",
    "status": "CANCELED"
  }
}

RefreshCopy Anchor Link

Refresh (PUT on the same path) re-reads the booking from the supplier, for example to resolve RQ or to spot a cancellation made on the supplier's side.

• It returns the status the supplier reports. If nothing changed at the supplier, the booking stays as it was. Confirmed
• A supplier that doesn't support refreshing answers 406. Confirmed Don't retry: read booking detail instead.

The generic cancel endpointCopy Anchor Link

The generic Booking API can also cancel a hotel service. Spec

• serviceType is HOTEL for a hotel.
• serviceId is probably hotelservice[].id from getBookings, which holds the same value as Book's accommodation.bookingReference (TST-1464-0). Tested Whether this endpoint takes it is unverified. Unverified
• These generic endpoints belong to the Booking API. An API user enabled only for the hotel booking flow gets 401 ... not allowed to access here on them; ask your Nava account manager if you need them. Tested
• Body: cancellationType (required, PROVIDER or MANUAL), emailNotifyCancel, manualCancellationFee, relatedManualCancellationFee. Spec
• Response: status, cancellationType, cancellationDate, providerCancellationDate. Spec

The spec gives no descriptions for these values, so test both in your test account before you rely on them. The matching fee endpoint, GET /booking/{bookingReference}/{serviceType}/{serviceId}/cancellation-fee, also returns relatedService and supportedCancellationTypes. Spec

See Cancel service and Service cancellation fee.

Refunds are a separate stepCopy Anchor Link

Cancelling does not return money to the guest. The refund is its own call, and a refund does not cancel any service. Spec

The response carries bookingReference, orderNumber, amount, manualRefund, paymentRefundStatus (NONE, PARTIAL or COMPLETE) and secondPaymentRefundStatus. Spec A REFUND webhook fires when a refund succeeds. Docs

If you took the payment through your own payment provider, refund it there instead.

Playbook: the guest cancelsCopy Anchor Link

Playbook: cancelled on the platform sideCopy Anchor Link

A supplier or an agent can cancel a booking without you calling the API.

RelatedCopy Anchor Link

• Booking statuses
• Cancellation fee and Cancel
• Refund
• Webhooks
• Reading bookings