Groups

The order engine group umbrella that links individual trips, carries the negotiated conditions and enforces inherited constraints.

Operation	Endpoint
Create a group	POST /oms-ops/groups
Read a group	GET /oms-ops/groups/{groupId}
Update a group	PATCH /oms-ops/groups/{groupId}
Read the group's aggregate status	GET /oms-ops/groups/{groupId}/aggregate
Link a trip to a group	POST /oms-ops/groups/{groupId}/trips
Record a member trip's status	POST /oms-ops/groups/{groupId}/trips/{tripId}/status
Check a proposed trip change against group constraints	POST /oms-ops/trips/{tripId}/group-check

Create a group

POST/oms-ops/groups

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
agreement	object	yes
agreement.agreementRef	string	yes	1–200 chars
agreement.constraints	object
agreement.constraints.allowedAdditionKinds	array of string
agreement.constraints.allowedValues	map of array
agreement.constraints.constrainedProductKinds	array of string
agreement.constraints.inherited	map of string
agreement.constraints.maxAdditionsPerTrip	integer		≥ 0
agreement.constraints.maxParticipants	integer		> 0
agreement.constraints.minParticipants	integer		≥ 0
agreement.constraints.promotionsOnTop	boolean
agreement.constraints.ruleReasons	map of string
agreement.contractRef	string		1–200 chars
agreement.negotiatedConditions	object		default {"terms":[]}
agreement.negotiatedConditions.currency	string		pattern ^[A-Z]{3}$
agreement.negotiatedConditions.discountPercent	number		≥ 0; ≤ 100
agreement.negotiatedConditions.fixedPricesMinor	map of integer
agreement.negotiatedConditions.priceListRef	string		1–200 chars
agreement.negotiatedConditions.terms	array of string
agreement.paymentLogic	object	yes
agreement.paymentLogic.anchor	enum: group, trip, purchase_order	yes
agreement.paymentLogic.depositPercent	number		≥ 0; ≤ 100
agreement.paymentLogic.instalments	array of object
agreement.paymentLogic.pattern	enum: agency_bulk, per_booking, instalments, deferred	yes
agreement.paymentLogic.scenario	string	yes	1–60 chars
groupId	string		1–200 chars
groupType	string	yes	1–60 chars
name	string	yes	1–200 chars
organiser	object
organiser.contact	string		max 320 chars
organiser.name	string		max 200 chars
organiser.ref	string	yes	1–200 chars
status	enum: quoted, option, confirmed, closed, cancelled		default "quoted"

Schema: apps/journeys/src/oms-ops/contracts.ts (CreateGroupSchema)

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	oms_ops_not_enabled	Order operations are not enabled for the tenant.
409	group_version_conflict	The group's expectedVersion does not match.
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 group

GET/oms-ops/groups/{groupId}

Parameters

Name	In	Required	Notes
groupId	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_not_found	The group does not exist.
404	oms_ops_not_enabled	Order operations are not enabled for the tenant.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Update a group

PATCH/oms-ops/groups/{groupId}

Parameters

Name	In	Required	Notes
groupId	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
agreement	object
agreement.agreementRef	string	yes	1–200 chars
agreement.constraints	object
agreement.constraints.allowedAdditionKinds	array of string
agreement.constraints.allowedValues	map of array
agreement.constraints.constrainedProductKinds	array of string
agreement.constraints.inherited	map of string
agreement.constraints.maxAdditionsPerTrip	integer		≥ 0
agreement.constraints.maxParticipants	integer		> 0
agreement.constraints.minParticipants	integer		≥ 0
agreement.constraints.promotionsOnTop	boolean
agreement.constraints.ruleReasons	map of string
agreement.contractRef	string		1–200 chars
agreement.negotiatedConditions	object		default {"terms":[]}
agreement.negotiatedConditions.currency	string		pattern ^[A-Z]{3}$
agreement.negotiatedConditions.discountPercent	number		≥ 0; ≤ 100
agreement.negotiatedConditions.fixedPricesMinor	map of integer
agreement.negotiatedConditions.priceListRef	string		1–200 chars
agreement.negotiatedConditions.terms	array of string
agreement.paymentLogic	object	yes
agreement.paymentLogic.anchor	enum: group, trip, purchase_order	yes
agreement.paymentLogic.depositPercent	number		≥ 0; ≤ 100
agreement.paymentLogic.instalments	array of object
agreement.paymentLogic.pattern	enum: agency_bulk, per_booking, instalments, deferred	yes
agreement.paymentLogic.scenario	string	yes	1–60 chars
expectedVersion	integer	yes	> 0
reason	string		max 2000 chars
status	enum: quoted, option, confirmed, closed, cancelled

Schema: apps/journeys/src/oms-ops/contracts.ts (UpdateGroupSchema)

Response 200

{ group, violations }.

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_not_found	The group does not exist.
404	oms_ops_not_enabled	Order operations are not enabled for the tenant.
409	group_version_conflict	The group's expectedVersion does not match.
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 the group's aggregate status

GET/oms-ops/groups/{groupId}/aggregate

Parameters

Name	In	Required	Notes
groupId	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_not_found	The group does not exist.
404	oms_ops_not_enabled	Order operations are not enabled for the tenant.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Link a trip to a group

POST/oms-ops/groups/{groupId}/trips

Parameters

Name	In	Required	Notes
groupId	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
status	string		1–60 chars; default "quoted"
tripId	string	yes	1–200 chars

Schema: apps/journeys/src/oms-ops/contracts.ts (LinkTripSchema)

Response 201

{ member, violations }.

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	oms_ops_not_enabled	Order operations are not enabled for the tenant.
409	group_closed	The group is closed.
409	group_full	The group has reached its maximum participants.
409	trip_already_grouped	The trip already belongs to a group.
409	idempotency_in_progress	A request with this Idempotency-Key is still running. Retry after the Retry-After interval.
422	group_constraint_violation	The trip breaks a constraint the group imposes.
422	idempotency_key_reused	The Idempotency-Key was used for a different request.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Record a member trip's status

POST/oms-ops/groups/{groupId}/trips/{tripId}/status

Parameters

Name	In	Required	Notes
groupId	path	yes
tripId	path	yes

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

Request body

Field	Type	Required	Notes
expectedVersion	integer		> 0
source	string		1–100 chars; default "order_store"
status	string	yes	1–60 chars

Schema: apps/journeys/src/oms-ops/contracts.ts (MemberStatusSchema)

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	oms_ops_not_enabled	Order operations 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.

Check a proposed trip change against group constraints

POST/oms-ops/trips/{tripId}/group-check

Parameters

Name	In	Required	Notes
tripId	path	yes

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

Request body

Field	Type	Required	Notes
attribute	string		min 1 chars
kind	enum: add_line, change_attribute, apply_promotion	yes
lineId	string		1–200 chars
productKind	string		min 1 chars
promotionRef	string		1–200 chars
value	string

Schema: apps/journeys/src/oms-ops/contracts.ts (ProposedTripChangeSchema)

Response 200

{ groupId, allowed, violations, inherited }.

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	oms_ops_not_enabled	Order operations 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.