Groups, agreements and block requests
Group business uses four related resources:
| Resource | What it is |
|---|---|
| Block request | A request from a tour operator, agency or MICE organiser for cabins on a departure, priced and decided by the tenant. Accepting it creates a group agreement. |
| Group agreement | The commercial agreement with the group holder: a block of cabins (or rate-only terms), fare, deposits, releases, free places, commission and the name list. |
| Group | The order engine umbrella that links the individual trips of the group and enforces the agreement's constraints on them. |
| Travel party | Families and friends travelling together on separate trips, without group terms. |
Block requests
| Step | Call | Notes |
|---|---|---|
| Request | POST /group-sales/group-requests | Holder, organiser, departure, product, currency, cabin counts per category (categories[{ categoryRef, units }]), optional cabinNumbers per category, and terms (commission, deposit stages, releases, free places). |
| See held cabins | GET /group-sales/group-requests/cabin-holds?departureRef= and GET /supply/sailings/{sailingId}/cabin-inventory | Cabins held by open requests, and the deck's cabin inventory. |
| Price | PUT /group-sales/group-requests/{id}/fare | The group fare per category. POST …/fare-suggestion proposes one. |
| Submit | POST /group-sales/group-requests/{id}/submit | Creates the group agreement in pending_approval. |
| Decide | POST /group-sales/group-requests/{id}/decision | Approve, counter-offer or refuse. The decider must hold a decider role and must not be the author or submitter (four-eyes). |
| Accept | POST /group-sales/group-requests/{id}/accept | The agreement becomes contracted. |
Group agreements
Agreements can also be created directly (POST /group-agreements), for example for operator series. An agreement with allotments is a block; without, it is rate-only. Agreement types (affinity, incentive, series…) are tenant configuration and decide whether approval is required and its deadline.
| State | Next states |
|---|---|
requested | pending_approval, offered, refused, cancelled |
pending_approval | offered, refused, expired, cancelled |
offered | pending_approval, contracted, expired, cancelled |
contracted | names_closed, cancelled |
names_closed | closed, cancelled |
closed | settled |
settled, expired, refused, cancelled | none |
| Operation | Call |
|---|---|
| Amend (new version, constraints re-checked) | PATCH /group-agreements/{id} with expectedVersion |
| Approve, counter-offer, refuse | POST /group-agreements/{id}/approval |
| Change state | POST /group-agreements/{id}/transitions |
| Open the order engine group | POST /group-agreements/{id}/group |
| Allocate, substitute or vacate berths for trips | POST /group-agreements/{id}/berth-holds/allocate, /substitute, /vacate |
| Release units; automatic release at the name-list deadline | POST /group-agreements/{id}/releases, /releases/name-list-deadline |
| Record a deposit receipt; final settlement | POST /group-agreements/{id}/receipts, /settlement |
| Cancel a trip with a penalty; settle free places | POST /group-agreements/{id}/cancellations, /free-places/settle |
Every read takes asOf (a date or time), so the agreement can be seen as it stood on any day: the page (GET /group-agreements/{id}) and its sections allotments, name-list, schedule, statement, free-places, timeline and onboard, plus versions, ledger and berth-holds. The ledger records on-account money, allocations and reversals, retained amounts, fees, free-berth credits, commission and net remittance. Every change publishes group_agreement.changed.
Groups
The order engine group (/oms-ops/groups) links individual trips. It carries the agreement reference, the negotiated conditions, the payment logic (group-level, per booking, instalments or deferred) and constraints the member trips inherit: departure and product, the product kinds that may not change, the kinds that may be added, the number of additions per trip, and minimum and maximum participants.
| Operation | Call |
|---|---|
| Create (or open from an agreement) | POST /oms-ops/groups or POST /group-agreements/{id}/group |
| Link a trip | POST /oms-ops/groups/{groupId}/trips; refused when the group is full or closed, or when the trip breaks a constraint. |
| Check a change against the constraints | POST /oms-ops/trips/{tripId}/group-check |
| Aggregate status | GET /oms-ops/groups/{groupId}/aggregate |
| Group payments | POST /oms-ops/payments with anchor.level: group, allocated across member trips by the group scenario. |
Travel parties
A travel party (/travel-parties) links trips that travel together (a lead contact, shared requests, a default payer) without commercial terms. Party quotes (/group-sales/party-quotes) price several units for a party together and book one trip per unit; conversion-preview compares individual and group terms when a party grows.
See the group booking guide and the reference for Block requests, Group agreements, Groups, Travel parties and Party quotes.