Bookings

Confirm and service every Brek booking

After payment authorization, one confirm call performs the supplier booking and returns the reference your agent may present as booked.

Confirm the reservation

Present the checkout's current approvalReceipt after payment authorization. Only then record fresh human approval and bind Confirm to its exact fingerprint. Brek verifies the typed attestation, attempts the supplier booking, captures only after supplier success, and attempts to void authorization when booking fails. Keep one Idempotency-Key for this logical confirmation.

curl -X POST https://api.brek.com/api/v1/agent-commerce/checkout-sessions/acs_.../confirm \
  -H "Authorization: Bearer $BREK_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: confirm-order-8472" \
  -d '{
    "approval": {
      "actorType": "human",
      "approvedAt": "<current ISO 8601 approval time>",
      "source": "agent_ui",
      "approvalRef": "trip-8472-confirm-001",
      "receiptFingerprint": "<approvalReceipt.fingerprint>"
    }
  }'

GET /bookings/:ref

Retrieve

Read the hotel, stay, named guests, available property details, status, amount, confirmation email target, booking-time cancellation-policy snapshot, approval evidence, and cancellation result through the same application boundary.

GET /bookings/:ref/cancellation-preview

Preview

Calculate the current refundable amount and penalty without changing the booking. A cancellable Live preview returns the five-minute token and preview fingerprint used to bind the required human approval attestation at Cancel.

POST /bookings/:ref/cancel

Cancel

Apply the booking policy, cancel with the supplier, report the payment refund as a separate status, and reverse partner commission. Do not say refunded until cancellation.refund.status is succeeded.

Preview, approve, then cancel exactly once

Retrieve the booking, then call cancellation-preview. Present reason, price.originalTotal, price.refundableAmount, and price.cancellationPenalty exactly as returned. Obtain explicit human approval of those consequences. Test is simulated, returns approval.required=false, and has no token. A cancellable Live preview returns a sensitive token that expires after five minutes plus a non-secret preview fingerprint. Trusted server code passes the token unchanged and binds a fresh human approval attestation to that exact fingerprint at Cancel.

Never log, persist, display, share, or place the approval token in model context, and never give it to an untrusted model. Keep approvalRef opaque and free of names, emails, or conversation text. If Cancel reports that the preview expired or became stale, discard the token and fingerprint, create a new preview, present the new consequences, and obtain approval again.

Read the cancellation preview contract

Poll; never submit a second cancellation

When booking status is cancellation_in_progress, call GET on that booking until it changes and follow cancellation.nextAction. Never POST Cancel again. If status becomes cancellation_requires_attention, the outcome is unknown, or an in-progress state does not change, stop cancellation writes and open the authenticated Partner Console support page with only the request ID and minimum redacted booking evidence. Never send an API key, Authorization header, payment secret, raw card data, full response, or unnecessary traveler PII.

A completed cancellation reports outcome=succeeded and preserves its durable phase, approvedPreview, and supplier journal. In Test, approvalAttestation is null because no approval token is required.

Commission after confirmation

An eligible Brek booking creates a pending commission entry. Standard applications earn 10% of realized Brek profit—not 10% of traveler spend. The entry becomes available after 21 complete calendar days following the hotel stay check-out date if the booking remains eligible; cancellation or refund reverses it.

Understand commission states and timing

Confirmation email

Live Brek bookings send the traveler confirmation through Brek's customer email service. The booking response reports the exact delivery state as pending, sent, or failed. Test bookings never send email and return suppressed_in_test.

Email delivery does not change booking state

A confirmed booking stays confirmed even if its email cannot be delivered. Your agent should always show the booking reference and must not claim the email was sent when delivery is failed. There is no email-retry endpoint in v1; the partner should open the authenticated Partner Console support page with only the request ID and minimum redacted Brek booking evidence—never card data, API keys, Authorization headers, payment or checkout secrets, full responses, or unnecessary traveler PII.

See the traveler email and exact Brek Hotel API field map

A redirect is not a Brek booking

Expedia.com and Booking.com public comparisons may be returned, but neither is guaranteed. A public rate leaves Brek for checkout: retrieve and cancel that reservation with the external provider, not with the Brek booking endpoints. Public redirects earn no Agent Commerce rev share in v1.