Set a company item's mapping

PUT/v1/catalog/items/mapping

Request schema: SetMappingRequest
Success schema: SetMappingResponse
Documented HTTP statuses: 200, 400, 401, 403, 404, 409, 422, 429, 503
Contract: direct-company-item-mapping-v1.openapi.json

Authorization

Current Enterprise authority for the represented Company and the direct-mapping permission are required, plus optional partner delegation where it is approved. When the request acts for a user, that user must currently hold catalog mapping administrator access. Authority is revalidated on every request; a company item ID, prior response, advertised action, or idempotency key grants none.

Request guidance

Send company_item_id (the exact current company item ID) and hph_item_code. expected_mapping_revision is optional optimistic concurrency: when supplied it must equal the current mapping_revision, and 0 means the item has never been mapped. reason is required, up to 512 characters with no leading or trailing whitespace, when the desired code replaces a different current association or a previously mapped empty state. Do not send query parameters, an item_skey, or organization, user, application, or authority fields.

Request fields

Synthetic request example

{
  "company_item_id": "COMPANY-1001",
  "hph_item_code": "012NI0044",
  "expected_mapping_revision": 3,
  "reason": "Corrected parent association"
}

Idempotency and recovery

Send exactly one Idempotency-Key header (1 to 128 visible ASCII characters) for every request; a missing or invalid key returns 400. Use a new key for each new mapping decision. After an ambiguous outcome, replay the same key with identical content: a completed replay returns the original result with reused set to true. The same key with different content returns 409 IDEMPOTENCY_CONFLICT, and 409 DIRECT_MAPPING_IN_PROGRESS means the original request is still processing.

Response guidance

transition is initial_mapping, already_current, or replaced, and mapping_status is active. A new mapping advances mapping_revision by one; already_current returns the existing revision and appends nothing. previous_mapping is present only when a different HPH Item Code was replaced and is omitted otherwise. validation.outcome is mapped or mapped_with_warnings; warnings report Manufacturer price-on-application or discontinued pricing without blocking the mapping. Follow available_actions by operation_id and relative href; restore_previous_mapping is advertised only when restoration is available. Errors: 404 COMPANY_ITEM_NOT_FOUND for an unknown, ambiguous, or concealed company item; 422 HPH_ITEM_CODE_NOT_FOUND or HPH_ITEM_INACTIVE; 409 MAPPING_REVISION_CHANGED (retrieve the current mapping and decide again) or REPLACEMENT_REASON_REQUIRED; 403 DIRECT_MAPPING_NOT_AUTHORIZED; 429 QUOTA_EXCEEDED; 503 DIRECT_MAPPING_UNAVAILABLE.

Synthetic success example: Replacement of a different current mapping

{
  "operation_reference": "directmap_1123456789abcdef0123456789abcdef",
  "item_skey": "11111111-1111-4111-8111-111111111111",
  "company_item_id": "COMPANY-1001",
  "transition": "replaced",
  "mapping_status": "active",
  "previous_mapping": {
    "mapping_revision": 3,
    "hph_item_code": "012NI0032"
  },
  "mapping_revision": 4,
  "hph_item_code": "012NI0044",
  "reused": false,
  "validation": {
    "outcome": "mapped",
    "warnings": []
  },
  "available_actions": [
    {
      "action": "get_current_mapping",
      "title": "Get current mapping",
      "description": "Retrieve the current mapping under the caller's present authority.",
      "operation_id": "GetCompanyItemCurrentMapping",
      "method": "GET",
      "href": "/v1/catalog/items/mapping?company_item_id=COMPANY-1001",
      "request_body_required": false,
      "idempotency_key_required": false,
      "confirmation_required": false
    },
    {
      "action": "set_mapping",
      "title": "Set mapping",
      "description": "Set the desired HPH Item Code for this company item.",
      "operation_id": "SetCompanyItemMapping",
      "method": "PUT",
      "href": "/v1/catalog/items/mapping",
      "request_body_required": true,
      "idempotency_key_required": true,
      "confirmation_required": true
    },
    {
      "action": "restore_previous_mapping",
      "title": "Restore previous mapping",
      "description": "Restore the immediately previous complete mapping snapshot by appending a new revision.",
      "operation_id": "RestorePreviousCompanyItemMapping",
      "method": "POST",
      "href": "/v1/catalog/items/mapping/restorations",
      "request_body_required": true,
      "idempotency_key_required": true,
      "confirmation_required": true
    },
    {
      "action": "get_mapping_history",
      "title": "Get mapping history",
      "description": "Retrieve immutable mapping revisions under the caller's present authority.",
      "operation_id": "ListCompanyItemMappingHistory",
      "method": "GET",
      "href": "/v1/catalog/items/mapping/history?company_item_id=COMPANY-1001",
      "request_body_required": false,
      "idempotency_key_required": false,
      "confirmation_required": false
    }
  ]
}

Additional response examples

Initial mapping with a Manufacturer pricing warning

{
  "operation_reference": "directmap_0123456789abcdef0123456789abcdef",
  "item_skey": "11111111-1111-4111-8111-111111111111",
  "company_item_id": "COMPANY-1001",
  "transition": "initial_mapping",
  "mapping_status": "active",
  "mapping_revision": 1,
  "hph_item_code": "012NI0044",
  "reused": false,
  "validation": {
    "outcome": "mapped_with_warnings",
    "warnings": [
      {
        "code": "HPH_ITEM_MANUFACTURER_PRICE_ON_APPLICATION",
        "title": "Manufacturer list price is not published",
        "description": "The mapping is active, but the manufacturer lists this item as price on application."
      }
    ]
  },
  "available_actions": [
    {
      "action": "get_current_mapping",
      "title": "Get current mapping",
      "description": "Retrieve the current mapping under the caller's present authority.",
      "operation_id": "GetCompanyItemCurrentMapping",
      "method": "GET",
      "href": "/v1/catalog/items/mapping?company_item_id=COMPANY-1001",
      "request_body_required": false,
      "idempotency_key_required": false,
      "confirmation_required": false
    },
    {
      "action": "set_mapping",
      "title": "Set mapping",
      "description": "Set the desired HPH Item Code for this company item.",
      "operation_id": "SetCompanyItemMapping",
      "method": "PUT",
      "href": "/v1/catalog/items/mapping",
      "request_body_required": true,
      "idempotency_key_required": true,
      "confirmation_required": true
    },
    {
      "action": "get_mapping_history",
      "title": "Get mapping history",
      "description": "Retrieve immutable mapping revisions under the caller's present authority.",
      "operation_id": "ListCompanyItemMappingHistory",
      "method": "GET",
      "href": "/v1/catalog/items/mapping/history?company_item_id=COMPANY-1001",
      "request_body_required": false,
      "idempotency_key_required": false,
      "confirmation_required": false
    }
  ]
}