Block requests

Group requests from tour operators, agencies and MICE organisers. A request is drafted, priced, submitted, decided and accepted, which creates the group agreement.

Operation	Endpoint
List block requests	GET /group-sales/group-requests
Create a block request	POST /group-sales/group-requests
Read a block request	GET /group-sales/group-requests/{id}
Accept the offer	POST /group-sales/group-requests/{id}/accept
Approve, counter-offer or refuse a request	POST /group-sales/group-requests/{id}/decision
Author the group fare	PUT /group-sales/group-requests/{id}/fare
Change the fare of an offered request	POST /group-sales/group-requests/{id}/fare-change
Suggest a group fare	POST /group-sales/group-requests/{id}/fare-suggestion
Create a quote linked to the request	POST /group-sales/group-requests/{id}/linked-quotes
Submit a request for approval	POST /group-sales/group-requests/{id}/submit
List cabins held by open requests on a departure	GET /group-sales/group-requests/cabin-holds
Confirm a linked quote	POST /group-sales/linked-quotes/{id}/confirm

List block requests

GET/group-sales/group-requests

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Create a block request

POST/group-sales/group-requests

Counts per cabin category, with optional cabinNumbers when specific cabins are picked from the deck plan.

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object	yes
actor.channel	string		max 60 chars
actor.id	string	yes	1–200 chars
actor.name	string		max 200 chars
actor.role	string	yes	1–100 chars
agreementType	string	yes	1–60 chars
attributes	map of string
categories	array of object	yes	at least 1
categories[].cabinNumbers	array of string		at most 200
categories[].categoryRef	string	yes	1–200 chars
categories[].label	string		max 200 chars
categories[].units	integer	yes	> 0
currency	string	yes	pattern ^[A-Z]{3}$
departure	object	yes
departure.departureDate	string	yes	pattern ^\d{4}-\d{2}-\d{2}$
departure.label	string		max 200 chars
departure.ref	string	yes	1–200 chars
departure.returnDate	string		pattern ^\d{4}-\d{2}-\d{2}$
holder	object	yes
holder.contact	string		max 320 chars
holder.kind	string		1–60 chars
holder.name	string		max 200 chars
holder.ref	string	yes	1–200 chars
itemAttributes	map of string
leader	object
leader.contact	string		max 320 chars
leader.kind	string		1–60 chars
leader.name	string		max 200 chars
leader.ref	string	yes	1–200 chars
name	string	yes	1–200 chars
note	string		max 2000 chars
organiser	object	yes
organiser.contact	string		max 320 chars
organiser.kind	string		1–60 chars
organiser.name	string		max 200 chars
organiser.ref	string	yes	1–200 chars
product	object	yes
product.attributes	map of string
product.departureRef	string		1–200 chars
product.label	string		max 200 chars
product.nights	integer	yes	> 0
product.productId	string	yes	1–200 chars
terms	object	yes
terms.commission	map of object	yes
terms.depositStages	array of object
terms.freePlaces	map of object
terms.minimumUnits	integer		> 0
terms.release	map of object
terms.valueAdds	array of string

Schema: apps/journeys/src/group-sales/contracts.ts (GroupRequestInputSchema)

Response 201

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	cabin_already_held	The cabin is already held by another request.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Read a block request

GET/group-sales/group-requests/{id}

Parameters

Name	In	Required	Notes
id	path	yes

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Accept the offer

POST/group-sales/group-requests/{id}/accept

The agreement becomes contracted.

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object	yes
actor.channel	string		max 60 chars
actor.id	string	yes	1–200 chars
actor.name	string		max 200 chars
actor.role	string	yes	1–100 chars
reason	string		max 2000 chars

Schema: apps/journeys/src/group-sales/contracts.ts (AcceptSchema)

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	not_offered	The request or offer is not in the offered state.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Approve, counter-offer or refuse a request

POST/group-sales/group-requests/{id}/decision

The decider is bound to the token or session, must hold a decider role, and must differ from the author and submitter (four-eyes).

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object
actor.channel	string		max 60 chars
actor.id	string		1–200 chars
actor.name	string		1–200 chars
actor.role	string		1–100 chars
counterOffer	object
counterOffer.categories	array of object	yes	at least 1
counterOffer.categories[].categoryRef	string	yes	1–200 chars
counterOffer.categories[].groupFareMinor	integer	yes	> 0
counterOffer.summary	string	yes	1–1000 chars
decision	enum: approve, counter_offer, refuse	yes
reason	string		max 1000 chars

Schema: apps/journeys/src/group-sales/contracts.ts (DecisionSchema)

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	not_pending_approval	The agreement or request is not pending approval.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Author the group fare

PUT/group-sales/group-requests/{id}/fare

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object	yes
actor.channel	string		max 60 chars
actor.id	string	yes	1–200 chars
actor.name	string		max 200 chars
actor.role	string	yes	1–100 chars
categories	array of object	yes	at least 1
categories[].categoryRef	string	yes	1–200 chars
categories[].groupFareMinor	integer	yes	> 0
chargesLabel	string		max 100 chars
chargesPerGuestMinor	integer		≥ 0; default 0
expectedVersion	integer		> 0
priceValidUntil	string		pattern ^\d{4}-\d{2}-\d{2}$
source	enum: agent, assistant		default "agent"

Schema: apps/journeys/src/group-sales/contracts.ts (AuthorFareSchema)

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Change the fare of an offered request

POST/group-sales/group-requests/{id}/fare-change

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object	yes
actor.channel	string		max 60 chars
actor.id	string	yes	1–200 chars
actor.name	string		max 200 chars
actor.role	string	yes	1–100 chars
categories	array of object	yes	at least 1
categories[].categoryRef	string	yes	1–200 chars
categories[].groupFareMinor	integer	yes	> 0
expectedAgreementVersion	integer	yes	> 0
reason	string	yes	1–2000 chars

Schema: apps/journeys/src/group-sales/contracts.ts (FareChangeSchema)

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Suggest a group fare

POST/group-sales/group-requests/{id}/fare-suggestion

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Create a quote linked to the request

POST/group-sales/group-requests/{id}/linked-quotes

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object	yes
actor.channel	string		max 60 chars
actor.id	string	yes	1–200 chars
actor.name	string		max 200 chars
actor.role	string	yes	1–100 chars
leadContact	object
leadContact.contact	string		max 320 chars
leadContact.name	string		max 200 chars
leadContact.ref	string	yes	1–200 chars
unit	object	yes
unit.category	string	yes	1–60 chars
unit.guests	array of object	yes	at least 1
unit.guests[].ageBand	string	yes	1–40 chars
unit.guests[].id	string	yes	1–200 chars
unit.guests[].name	string	yes	1–200 chars
unit.label	string		max 200 chars
unit.unitId	string	yes	1–200 chars

Schema: apps/journeys/src/group-sales/contracts.ts (LinkedQuoteInputSchema)

Response 201

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Submit a request for approval

POST/group-sales/group-requests/{id}/submit

Creates the group agreement in pending_approval.

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object	yes
actor.channel	string		max 60 chars
actor.id	string	yes	1–200 chars
actor.name	string		max 200 chars
actor.role	string	yes	1–100 chars
deadline	string (date-time)

Schema: apps/journeys/src/group-sales/contracts.ts (SubmitRequestSchema)

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

List cabins held by open requests on a departure

GET/group-sales/group-requests/cabin-holds

Parameters

Name	In	Required	Notes
departureRef	query	yes

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Confirm a linked quote

POST/group-sales/linked-quotes/{id}/confirm

Parameters

Name	In	Required	Notes
id	path	yes

Headers: Idempotency-Key, plus X-Request-Id.

Request body

Field	Type	Required	Notes
actor	object	yes
actor.channel	string		max 60 chars
actor.id	string	yes	1–200 chars
actor.name	string		max 200 chars
actor.role	string	yes	1–100 chars

Schema: apps/journeys/src/group-sales/contracts.ts (ConfirmLinkedQuoteSchema)

Response 200

Errors

Status	Code	Meaning
400	invalid_request	The request failed validation. The message names the first failing field; oms-ops and group surfaces also return every issue in details.
401	unauthenticated	The bearer token is missing, invalid, expired or minted for another purpose.
403	scope_forbidden	The token is scoped to an agency or an access scope; this surface requires an unscoped tenant token.
404	group_sales_not_enabled	Group sales are not enabled for the tenant.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.