API Reference
Retrieve a booking
Fetch the current Brek booking, confirmation delivery, stay, and cancellation state by reference.
/api/v1/agent-commerce/bookings/:bookingReferenceHeaders
Authorizationstring · required
Bearer $BREK_AGENT_API_KEY. Keep the key server-side.
Parameters
bookingReferencepath string · required
Brek bookingReference returned by confirm.
cURL
Replace every placeholder and run this from a trusted server-side environment. Never expose the API key in browser code.
curl --request GET "https://api.brek.com/api/v1/agent-commerce/bookings/${BOOKING_REFERENCE}" \
--header "Authorization: Bearer $BREK_AGENT_API_KEY"Response
{
"object": "agent_commerce.booking",
"bookingReference": "BREK-123",
"hotelConfirmationNumber": "HOTEL-456",
"status": "confirmed",
"environment": "live",
"isSimulation": false,
"price": {
"amount": 281.42,
"currency": "USD",
"payNow": {
"amount": 281.42,
"currency": "USD"
},
"payAtProperty": {
"amount": 5,
"currency": "USD"
},
"travelerTotal": {
"amount": 286.42,
"currency": "USD"
}
},
"accommodation": {
"accommodationName": "Example Hotel"
},
"stay": {
"checkIn": "<future check-in: YYYY-MM-DD>",
"checkOut": "<future check-out: YYYY-MM-DD>",
"rooms": [
{
"occupancyRefId": 1,
"code": "KING",
"description": "King Room",
"displayName": "King Room"
}
],
"roomNames": [
"King Room"
],
"cancelPolicy": {
"refundable": true,
"currency": "USD",
"deadlineTimezone": "UTC",
"cancelPenalties": [],
"summary": "Refundable with no monetary cancellation penalty currently listed."
}
},
"guests": {
"holder": {
"name": "Ada",
"surName": "Lovelace",
"ageCategory": "adult"
},
"occupancies": []
},
"propertyDetails": {
"available": false,
"address": null,
"checkInInstructions": null,
"notices": null,
"deposit": null
},
"customer": {
"email": "ada@example.com"
},
"approvalReceipt": {
"object": "agent_commerce.approval_receipt",
"version": 1,
"quoteId": "quote_123",
"issuedAt": "<receipt issue time: ISO 8601>",
"validUntil": "<quote expiry: ISO 8601>",
"hotel": {
"propertyId": "hotel_123",
"name": "Example Hotel",
"type": "Hotel"
},
"stay": {
"checkIn": "<future check-in: YYYY-MM-DD>",
"checkOut": "<future check-out: YYYY-MM-DD>",
"roomCodes": [
"KING"
],
"roomNames": [
"King Room"
]
},
"price": {
"payNow": {
"amount": 281.42,
"currency": "USD"
},
"payAtProperty": {
"amount": 5,
"currency": "USD"
},
"travelerTotal": {
"amount": 286.42,
"currency": "USD"
}
},
"cancellationPolicy": {
"refundable": true,
"currency": "USD",
"deadlineTimezone": "UTC",
"cancelPenalties": [],
"summary": "Refundable with no monetary cancellation penalty currently listed."
},
"travelerSafe": true,
"partnerEconomicsIncluded": false,
"sourceQuoteFingerprint": "quote_snapshot_123",
"fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"approvalAttestation": {
"object": "agent_commerce.approval_attestation",
"version": 1,
"checkoutSessionId": "acs_123",
"quoteId": "quote_123",
"receiptFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"actorType": "human",
"approvedAt": "<fresh human approval time: ISO 8601>",
"source": "agent_ui",
"approvalRef": "trip-123-confirm-1",
"recordedAt": "<server record time: ISO 8601>",
"containsPii": false
},
"confirmation": {
"email": "ada@example.com",
"deliveryStatus": "sent"
},
"commission": {
"ledgerId": "acl_123",
"status": "pending",
"environment": "live",
"isSimulation": false,
"basis": "realized_brek_profit",
"realizedProfit": 20,
"shareRate": 0.1,
"commissionAmount": 2,
"currency": "USD",
"checkOut": "<future check-out: YYYY-MM-DD>",
"holdDays": 21,
"eligibleAt": "<post-stay eligibility: ISO 8601>",
"pendingReason": "stay_completion_hold",
"profitSource": "booking_pnl"
}
}Retrieved Test booking
A Test booking remains simulated when retrieved: no supplier reservation or traveler email exists. Its pending commission uses test_simulation_only; cancellation reverses it and clears pendingReason.
{
"object": "agent_commerce.booking",
"bookingReference": "BREK-TEST-123",
"hotelConfirmationNumber": "DEV-TEST-456",
"status": "confirmed",
"environment": "test",
"isSimulation": true,
"price": {
"amount": 281.42,
"currency": "USD",
"payNow": {
"amount": 281.42,
"currency": "USD"
},
"payAtProperty": {
"amount": 5,
"currency": "USD"
},
"travelerTotal": {
"amount": 286.42,
"currency": "USD"
}
},
"accommodation": {
"accommodationName": "Example Hotel"
},
"stay": {
"checkIn": "<future check-in: YYYY-MM-DD>",
"checkOut": "<future check-out: YYYY-MM-DD>",
"rooms": [
{
"occupancyRefId": 1,
"code": "KING",
"description": "King Room",
"displayName": "King Room"
}
],
"roomNames": [
"King Room"
],
"cancelPolicy": {
"refundable": true,
"currency": "USD",
"deadlineTimezone": "UTC",
"cancelPenalties": [],
"summary": "Refundable with no monetary cancellation penalty currently listed."
}
},
"guests": {
"holder": {
"name": "Ada",
"surName": "Lovelace",
"ageCategory": "adult"
},
"occupancies": []
},
"propertyDetails": {
"available": false,
"address": null,
"checkInInstructions": null,
"notices": null,
"deposit": null
},
"customer": {
"email": "ada@example.com"
},
"approvalReceipt": {
"object": "agent_commerce.approval_receipt",
"version": 1,
"quoteId": "quote_test_123",
"issuedAt": "<receipt issue time: ISO 8601>",
"validUntil": "<quote expiry: ISO 8601>",
"hotel": {
"propertyId": "hotel_123",
"name": "Example Hotel",
"type": "Hotel"
},
"stay": {
"checkIn": "<future check-in: YYYY-MM-DD>",
"checkOut": "<future check-out: YYYY-MM-DD>",
"roomCodes": [
"KING"
],
"roomNames": [
"King Room"
]
},
"price": {
"payNow": {
"amount": 281.42,
"currency": "USD"
},
"payAtProperty": {
"amount": 5,
"currency": "USD"
},
"travelerTotal": {
"amount": 286.42,
"currency": "USD"
}
},
"cancellationPolicy": {
"refundable": true,
"currency": "USD",
"deadlineTimezone": "UTC",
"cancelPenalties": [],
"summary": "Refundable with no monetary cancellation penalty currently listed."
},
"travelerSafe": true,
"partnerEconomicsIncluded": false,
"sourceQuoteFingerprint": "quote_snapshot_test_123",
"fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"approvalAttestation": {
"object": "agent_commerce.approval_attestation",
"version": 1,
"checkoutSessionId": "acs_test_123",
"quoteId": "quote_test_123",
"receiptFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"actorType": "human",
"approvedAt": "<fresh human approval time: ISO 8601>",
"source": "developer_console",
"approvalRef": "test-confirm-123",
"recordedAt": "<server record time: ISO 8601>",
"containsPii": false
},
"confirmation": {
"email": "ada@example.com",
"deliveryStatus": "suppressed_in_test"
},
"commission": {
"ledgerId": "acl_test_pending",
"status": "pending",
"environment": "test",
"isSimulation": true,
"basis": "realized_brek_profit",
"realizedProfit": 20,
"shareRate": 0.1,
"commissionAmount": 2,
"currency": "USD",
"checkOut": "<future check-out: YYYY-MM-DD>",
"holdDays": 21,
"eligibleAt": "<post-stay eligibility: ISO 8601>",
"pendingReason": "test_simulation_only",
"profitSource": "test_simulation"
}
}Response fields
statusconfirmed | cancellation_in_progress | cancellation_requires_attention | cancelled | failed
Current Brek booking state. Neither cancellation_* state proves that cancellation completed; follow cancellation.nextAction and do not submit another cancellation.
priceBookingPrice
The complete post-booking price summary. Prefer price.payNow, price.payAtProperty, and price.travelerTotal. Legacy price.amount and price.currency mirror price.payNow.
stay.cancelPolicyobject
Cancellation terms copied from the accepted Quote when the booking was created. Keep this booking-time snapshot for the trip record; use cancellation-preview for the current refundable amount, penalty, and Live approval token.
stay.rooms[]array
Traveler-safe room identity and display fields only: occupancyRefId, code, description, and displayName when available. Room-level rate, base-rate, markup, exchange, supplier, and raw pricing metadata are never returned; read totals only from booking.price.
guestsobject
Named holder and occupancy guest snapshot used for the reservation. Do not substitute confirmation.email for the holder.
propertyDetailsobject
Upstream address, check-in instructions, notices, and deposit snapshot. Each value may be null; available=false means upstream property details were not preserved. Never infer a null value from the email.
approvalReceipt / approvalAttestationApprovalReceipt / ApprovalAttestation
Traveler-safe approved terms and the persisted non-PII human-approval evidence bound to their fingerprint.
confirmationobject
Traveler email and handoff status. sent means the email provider accepted the message for delivery, not inbox delivery.
hotelConfirmationNumberstring | undefined
Hotel confirmation number when available from the supplier.
cancellationobject | null
Cancellation progress or outcome. It is null before cancellation starts.
cancellation.statusin_progress | requires_attention | cancelled
Supplier cancellation state. Poll this GET endpoint while in_progress; do not submit another cancellation.
cancellation.outcomepending | unknown | succeeded | undefined
pending while the first cancellation call owns the supplier side effect; unknown when the supplier result cannot be established; succeeded when supplier cancellation completed.
cancellation.phasesupplier_started | supplier_outcome_unknown | refund_started | refund_pending | reconciled | undefined
Durable execution checkpoint. A terminal cancellation with a settled refund reports reconciled.
cancellation.approvedPreview / cancellation.approvalAttestationobject / object | null
The durable consequence snapshot and its Live human-approval evidence. Test keeps the snapshot but returns approvalAttestation=null because no approval token is required.
cancellation.supplierobject | undefined
Traveler-safe supplier execution status only. Raw supplier responses, identifiers, and error payloads remain internal.
cancellation.startedAt / cancellation.updatedAt / cancellation.completedAtISO 8601 | undefined
startedAt records the first cancellation claim, updatedAt the latest journal change, and completedAt the supplier cancellation time.
cancellation.retryablefalse | undefined
False for the durable cancellation operation, including the terminal journal. Never automatically resubmit Cancel.
cancellation.nextAction{ type: poll_booking | contact_support; message: string } | undefined
Machine-readable recovery. GET-poll for poll_booking. For contact_support, stop cancellation writes and contact support with a redacted booking reference.
commissionobject | undefined
Current private commission ledger. Poll this booking to observe pending, available, paid, or reversed without using Partner Console.
commission.pendingReasonstring | undefined
A pending Test ledger reports test_simulation_only. Reversal clears pendingReason, while profitSource=test_simulation preserves its Test provenance.
commission.profitSourcetest_simulation | booking_pricing_snapshot | booking_pnl
test_simulation identifies a Test-only ledger. Live may expose a provisional booking_pricing_snapshot while pending and changes to booking_pnl when authoritative P&L is ready.
Application-scoped access