Select an HPH Catalog Item alternative
Confirm one current opaque alternative option for the represented direct Company's catalog.
POST/v1/catalog/items/alternative-selections
Request schema: SelectHphItemAlternativeRequestV1
Success schema: SelectHphItemAlternativeResponseV1
Documented HTTP statuses: 200, 400, 401, 403, 404, 409, 422, 429, 503
Contract: hph-item-alternatives-v1.openapi.json
Authorization
Current direct-Company Enterprise authority and current catalog administration authority are required; when the request acts for a user, that user must hold catalog mapping administrator access. The operation is reauthorized after confirmation; an option reference, prior comparison, or idempotency key grants no authority.
Request guidance
Send the current option_reference returned by an alternatives operation, a bounded reason, confirmed set to true, and optional Company-owned item identifiers and description. Do not send an HPH Item Code, organization, user, application, revision, or authority field.
Parameters
| Name | In | Type | Presence | Constraints | Description |
|---|---|---|---|---|---|
Idempotency-Key | header | string | Required | minLength 1; maxLength 200 |
Request fields
| Field | Type | Presence | Constraints |
|---|---|---|---|
option_reference | string | Required | maximum 4096 characters |
company_item_id | string | Optional | maximum 512 characters |
alternate_company_item_id | string | Optional | maximum 512 characters |
company_description | string | Optional | maximum 1024 characters |
reason | string | Required | maximum 512 characters |
confirmed | boolean | Required | See the versioned schema |
Synthetic request example
{
"option_reference": "opaque-short-lived-option-reference",
"company_item_id": "SYNTHETIC-ITEM-100",
"alternate_company_item_id": null,
"company_description": "Synthetic selected alternative",
"reason": "Selected for the represented company catalog.",
"confirmed": true
}Idempotency and recovery
Send exactly one Idempotency-Key header (1 to 128 visible ASCII characters); a missing or invalid key returns 400. An exact completed replay returns the original result without another quota charge. Reusing a key with changed input is rejected with 409.
Response guidance
The response contains only the Company-owned item_skey, optional company_item_id, catalog revision, operation reference, and replay indicator. It never returns the selected HPH Item Code or the source item identity.
Synthetic success example: Confirmed Company-owned selection result
{
"contract_version": "v1",
"operation_reference": "alternative_select_0123456789abcdef0123456789abcdef",
"outcome": "selected",
"item_skey": "11111111-1111-4111-8111-111111111111",
"company_item_id": "SYNTHETIC-ITEM-100",
"catalog_revision": 2,
"reused": false
}