Service recovery

Goodwill and service-recovery cases with eligibility, approval thresholds and issue of vouchers or onboard credit.

Operation	Endpoint
Open a service-recovery case	POST /oms-ops/service-recovery/cases
Read a case	GET /oms-ops/service-recovery/cases/{caseId}
Reconcile a case's approval or retry its issue	POST /oms-ops/service-recovery/cases/{caseId}/sync
List a customer's cases	GET /oms-ops/service-recovery/customers/{customerRef}/cases
Check eligibility	POST /oms-ops/service-recovery/eligibility

Open a service-recovery case

POST/oms-ops/service-recovery/cases

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

Request body

Field	Type	Required	Notes
agent	object	yes
agent.channel	string		max 60 chars
agent.id	string	yes	1–200 chars
agent.name	string		max 200 chars
agent.role	string	yes	1–100 chars
attributes	map of string
benefit	object	yes
benefit.amountMinor	integer	yes	> 0
benefit.currency	string	yes	pattern ^[A-Z]{3}$
benefit.kind	enum: voucher, onboard_credit	yes
crmCaseRef	string		max 200 chars
customerRef	string	yes	1–200 chars
idempotencyKey	string	yes	1–200 chars
interactionRef	string		max 200 chars
note	string		max 2000 chars
reasonCode	string	yes	1–60 chars
tripId	string		1–200 chars

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

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.
400	idempotency_key_mismatch	The Idempotency-Key header and the body idempotencyKey differ.
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	not_eligible	The service-recovery request is not eligible under the policy.
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 case

GET/oms-ops/service-recovery/cases/{caseId}

Parameters

Name	In	Required	Notes
caseId	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	case_not_found	The service-recovery case 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.

Reconcile a case's approval or retry its issue

POST/oms-ops/service-recovery/cases/{caseId}/sync

Parameters

Name	In	Required	Notes
caseId	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	case_not_found	The service-recovery case does not exist.
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.

List a customer's cases

GET/oms-ops/service-recovery/customers/{customerRef}/cases

Parameters

Name	In	Required	Notes
customerRef	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	oms_ops_not_enabled	Order operations are not enabled for the tenant.
500	internal	Unexpected failure. Retry with the same Idempotency-Key.

Check eligibility

POST/oms-ops/service-recovery/eligibility

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

Request body

Field	Type	Required	Notes
agent	object	yes
agent.channel	string		max 60 chars
agent.id	string	yes	1–200 chars
agent.name	string		max 200 chars
agent.role	string	yes	1–100 chars
attributes	map of string
benefit	object	yes
benefit.amountMinor	integer	yes	> 0
benefit.currency	string	yes	pattern ^[A-Z]{3}$
benefit.kind	enum: voucher, onboard_credit	yes
crmCaseRef	string		max 200 chars
customerRef	string	yes	1–200 chars
idempotencyKey	string	yes	1–200 chars
interactionRef	string		max 200 chars
note	string		max 2000 chars
reasonCode	string	yes	1–60 chars
tripId	string		1–200 chars

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

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.