Restore a company item's previous mapping

POST/v1/catalog/items/mapping/restorations

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

Authorization

The same authority as setting a mapping is required: current Enterprise authority, the direct-mapping permission, optional approved partner delegation, and, when the request acts for a user, current catalog mapping administrator access. Authority is revalidated on every request.

Request guidance

Send company_item_id, expected_mapping_revision (the current mapping_revision, at least 2), and restore_from_revision. restore_from_revision must equal expected_mapping_revision minus one; only the immediately preceding snapshot can be restored, and any other pairing is rejected with 400. Do not send query parameters, an HPH Item Code, or authority fields.

Request fields

Synthetic request example

{
  "company_item_id": "COMPANY-1001",
  "restore_from_revision": 3,
  "expected_mapping_revision": 4
}

Idempotency and recovery

Send exactly one Idempotency-Key header (1 to 128 visible ASCII characters); a missing or invalid key returns 400. Use a new key for each new restoration and replay the same key with identical content after an ambiguous outcome. A completed replay returns the original result with reused set to true; changed content with the same key returns 409 IDEMPOTENCY_CONFLICT.

Response guidance

Restoration never rewrites history: it appends a new revision whose content equals the restored snapshot. When that snapshot contained an association, transition is mapping_restored, mapping_status is active, and hph_item_code and validation are returned. When the snapshot was explicitly empty, transition is empty_mapping_restored, mapping_status is unmapped, and the response has no hph_item_code or validation. Both shapes return restored_from_revision, the new mapping_revision, reused, and available_actions. A 409 MAPPING_REVISION_CHANGED means the current revision is no longer expected_mapping_revision; retrieve the current mapping before deciding again.

Synthetic success example: Restored mapped snapshot

{
  "operation_reference": "directmap_2123456789abcdef0123456789abcdef",
  "item_skey": "11111111-1111-4111-8111-111111111111",
  "company_item_id": "COMPANY-1001",
  "transition": "mapping_restored",
  "mapping_status": "active",
  "restored_from_revision": 3,
  "mapping_revision": 5,
  "hph_item_code": "012NI0032",
  "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": "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

Restored empty snapshot

{
  "operation_reference": "directmap_3123456789abcdef0123456789abcdef",
  "item_skey": "11111111-1111-4111-8111-111111111111",
  "company_item_id": "COMPANY-1001",
  "transition": "empty_mapping_restored",
  "mapping_status": "unmapped",
  "restored_from_revision": 3,
  "mapping_revision": 5,
  "reused": false,
  "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
    }
  ]
}