Case Items
Attach and detach the items involved in a case.
Attach an item to a Theft Case
Stores the item as the incident reported it: sku, quantity and any other reported detail are written to the case item itself, and no canonical Item is ever created. sku and itemId are optional but encouraged, and a case item needs at least one reported detail (sku, itemId, notes, quantity, valueAtIncident, category, upc, serialNumber, unitType, condition, itemName, merchandiseCategory, merchandiseType, brand, department, stockNumber or unitCost), so cash can be attached with neither. A body with no reported detail returns 400 INVARIANT_VIOLATION. A sku matches exactly after trimming and ignoring case, on SKU only and not UPC, and links the Item only when it matches exactly one. A SKU that matches no Item, or more than one, is stored unlinked and the request still returns 201. An id in the body is ignored: the request always adds a new case item. An itemId that names no Item returns 422 NATURAL_KEY_NOT_FOUND with the field and value that failed, and an itemId and a sku that name different Items return 400 INVARIANT_VIOLATION. involvementId is the caller-minted identifier of the involvement, and the attach is idempotent on it: repeating an attach whose involvementId is already stored on this case writes nothing and returns 200 with the stored involvement and replayed: true, and the rest of the repeated body is ignored. An involvementId already stored on another case returns 409 DUPLICATE_INVOLVEMENT_ID, and an uuid carried by more than one case returns 409 AMBIGUOUS_UUID. The change is written all or nothing; if any write fails, every row written so far is rolled back. The response body is read back after the write commits; if that read fails the request returns 500 although the attach was written, and repeating the attach returns the stored involvement.
path Parameters
caseIdSalesforce Investigation record Id of the parent theft case, or the uuid of the Incident it was reported from. An Incident uuid names the Theft Case that Incident is in. A value that is neither returns 400 BAD_REQUEST, and one that names no case returns 404 NOT_FOUND. An uuid carried by more than one case returns 409 AMBIGUOUS_UUID, and an org whose active mapping carries no uuid column returns 400 INVARIANT_VIOLATION for an uuid.
Attach an item to a Theft Case › Request Body
skuStock-keeping unit identifier as reported. Optional but encouraged.
quantityQuantity of items involved in the incident.
itemIdExisting canonical Item to link. Must name the same Item the SKU matches, when it matches one.
involvementIdCaller-minted identifier of this involvement, reused unchanged on retry. At most 36 characters for a new value. Immutable after create.
conditionRecovery Status of the item: recovered, damaged or not recovered. The org stores the value its value mapping gives each; a value no row maps is stored and read back as sent.
valueAtIncidentAssessed value of the item at the time of the incident.
categoryItem category.
upcUniversal Product Code for the involved item.
serialNumberSerial number of the involved item.
unitTypeUnit type of the involved item.
itemNameName of the item as the incident reported it. Stored on the case item as sent.
merchandiseCategoryMerchandise category as reported. Any text is accepted, subject to any restriction the org places on the picklist.
merchandiseTypeMerchandise type as reported. Any text is accepted, subject to any restriction the org places on the picklist.
brandBrand as reported, free text.
departmentDepartment the item belongs to. Open-set: not enumerated.
stockNumberStock number the retailer assigns the item.
unitCostCost of one unit to the retailer.
attributedToSalesforce id of a saved involved person on this case that the item is attributed to. To name a person reported in the same request, send attributedToInvolvementId instead. An id that is not an involved person on this case is refused with 400 INVARIANT_VIOLATION. Removing the attributed person from the case, by detaching it or by a PUT that leaves it out and omits caseItems, clears the attribution. To change or clear an attribution, change or clear both attributedTo and attributedToInvolvementId: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution.
attributedToInvolvementIdThe involvementId of the involved person the item is attributed to, whether that person is in the same request or already on the case. It is resolved to attributedTo when the case is saved, in the same all-or-nothing save as the persons. A value that no involved person on this case holds is refused with 400 INVARIANT_VIOLATION. When attributedTo is also sent, both must name the same person or the request is refused with 400 INVARIANT_VIOLATION. A loaded case returns both attributedTo and attributedToInvolvementId for an attributed item. To change or clear an attribution, change or clear both fields: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution, and repointing attributedTo while sending the old attributedToInvolvementId is refused.
notesCase-side context notes for the new junction.
Attach an item to a Theft Case › Responses
OK — the involvementId was already stored on this case. The stored involvement is returned with replayed: true and nothing was written.
replayedAlways true: the attach was a repeat and wrote nothing.
idSalesforce record id of the Case_Item__c junction row, assigned by Salesforce on insert. Null on POST cascade entry (new junction). Differs from involvementId, which the caller mints.
involvementIdCaller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. At most 36 characters for a new or changed value; a value already stored on the case item is accepted unchanged whatever its length, and returned on every read. Immutable after create: an update that sends a different value for a stored involvement returns 400 IMMUTABLE_FIELD; a value that differs only in case is the same value, and the stored spelling is kept. A value already held by another involvement, on this case or any other, or repeated inside one request, returns 409 DUPLICATE_INVOLVEMENT_ID; the comparison ignores case.
itemIdCanonical Item id. Optional: on a new case item a sku that matches exactly one Item sets it for you; a stored case item is never linked by SKU. An id that names no Item returns 422 NATURAL_KEY_NOT_FOUND, and on a new case item an id and a sku that name different Items return 400 INVARIANT_VIOLATION. Immutable after create.
skuSKU as the incident reported it, stored as sent. Optional but encouraged. Matched against the Item catalog exactly after trimming and ignoring case, on SKU only and not UPC; on a new case item one match links that Item, no match or several leave the row unlinked, and a stored case item is never matched.
quantityQuantity of items involved in the incident.
conditionRecovery Status of the item: recovered, damaged or not recovered. Open-set: the org stores the value its value mapping gives each, and a value no row maps is stored and read back as sent.
valueAtIncidentAssessed value of the item at the time of the incident.
categoryItem category (e.g. Electronics, Apparel, Grocery). Open-set — not enumerated.
notesCase-side mutable context for the junction.
upcUniversal Product Code for the involved item.
serialNumberSerial number of the involved item.
unitTypeUnit type of the involved item (e.g. Each, Pair, Case).
itemNameName of the item as the incident reported it. Stored on the case item as sent.
merchandiseCategoryMerchandise category as reported. Any text is accepted, subject to any restriction the org places on the picklist.
merchandiseTypeMerchandise type as reported. Any text is accepted, subject to any restriction the org places on the picklist.
brandBrand as reported, free text.
departmentDepartment the item belongs to, as stored. Open-set: not enumerated.
stockNumberStock number the retailer assigns the item, stored as sent.
unitCostCost of one unit to the retailer.
totalPriceTotal price of the line, calculated by the platform. Returned on a load and ignored on writes.
totalCostTotal cost of the line, calculated by the platform. Returned on a load and ignored on writes.
attributedToSalesforce id of a saved involved person on this case that the item is attributed to. To name a person reported in the same request, send attributedToInvolvementId instead. An id that is not an involved person on this case is refused with 400 INVARIANT_VIOLATION. Removing the attributed person from the case, by detaching it or by a PUT that leaves it out and omits caseItems, clears the attribution. To change or clear an attribution, change or clear both attributedTo and attributedToInvolvementId: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution.
attributedToInvolvementIdThe involvementId of the involved person the item is attributed to, whether that person is in the same request or already on the case. It is resolved to attributedTo when the case is saved, in the same all-or-nothing save as the persons. A value that no involved person on this case holds is refused with 400 INVARIANT_VIOLATION. When attributedTo is also sent, both must name the same person or the request is refused with 400 INVARIANT_VIOLATION. A loaded case returns both attributedTo and attributedToInvolvementId for an attributed item. To change or clear an attribution, change or clear both fields: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution, and repointing attributedTo while sending the old attributedToInvolvementId is refused.
Read-only preview of the referenced Item. Returned as null when the underlying Item is deleted, archived, or FLS-stripped.
Detach case items from a Theft Case
Detaches the case items named by involvementIds, the caller-minted ids, or by ids, the involvement row ids, without deleting the canonical Item records. Sending both, or neither, returns 400 BAD_REQUEST. An id that does not belong to the case surfaces as 404 NOT_FOUND. The change is written all or nothing; if any write fails, every row written so far is rolled back. The case is loaded first, so the caller needs read access to it, and a failure reading it or a record it links to returns that error before anything is removed.
path Parameters
caseIdSalesforce Investigation record Id of the parent theft case, or the uuid of the Incident it was reported from. An Incident uuid names the Theft Case that Incident is in. A value that is neither returns 400 BAD_REQUEST, and one that names no case returns 404 NOT_FOUND. An uuid carried by more than one case returns 409 AMBIGUOUS_UUID, and an org whose active mapping carries no uuid column returns 400 INVARIANT_VIOLATION for an uuid.
query Parameters
involvementIdsComma-separated caller-minted involvementId values of the involvements to detach, compared without regard to case. Send either involvementIds or ids, not both. An id that is not on the case returns 404 NOT_FOUND and nothing is removed.
idsComma-separated CaseItemId values. Send either ids or involvementIds, not both.
Detach case items from a Theft Case › Responses
No Content — junctions detached.
Link a case item to a canonical Item
Links a stored case item to an existing canonical Item, named by itemId or by sku, and returns the updated case item. caseId in the path is a Salesforce id or an Incident uuid. Linking never creates a canonical record and never changes one, and the reported details on the case item are kept as they are. Linking a case item to the record it already names writes nothing. A key that names no record returns 422 NATURAL_KEY_NOT_FOUND with the field and value that failed. A sku that matches several Items is reported by Foundation's lookup as matching none, so it too returns 422 NATURAL_KEY_NOT_FOUND, never NATURAL_KEY_AMBIGUOUS; the packaged SKU field is unique, so this arises only in a Mapped org. Send no key, or both itemId and sku, and the request returns 400 INVARIANT_VIOLATION. A caseId that names nothing, or an involvementId the case does not hold, returns 404 NOT_FOUND. The change is written all or nothing.
path Parameters
caseIdSalesforce Investigation record Id of the parent theft case, or the uuid of the Incident it was reported from. An Incident uuid names the Theft Case that Incident is in. A value that is neither returns 400 BAD_REQUEST, and one that names no case returns 404 NOT_FOUND. An uuid carried by more than one case returns 409 AMBIGUOUS_UUID, and an org whose active mapping carries no uuid column returns 400 INVARIANT_VIOLATION for an uuid.
Link a case item to a canonical Item › Request Body
involvementIdThe caller-minted identifier of the stored case item on this case, compared without regard to case. It names the case item to link; a value the case does not hold returns 404 NOT_FOUND.
itemIdSalesforce id of the canonical Item to link.
skuSKU of the canonical Item to link, matched ignoring case and surrounding spaces. Foundation's SKU lookup reports a SKU that matches several Items as matching none, so an ambiguous SKU returns 422 NATURAL_KEY_NOT_FOUND, never NATURAL_KEY_AMBIGUOUS. The packaged SKU field is unique, so this arises only in a Mapped org.
replaceSet true to replace a different record the case item already names. Without it, a case item already linked to a different record returns 409 ALREADY_LINKED.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: itemId | |
| type = object · requires: sku |
itemIdSalesforce id of the canonical Item to link.
involvementIdThe caller-minted identifier of the stored case item on this case, compared without regard to case. It names the case item to link; a value the case does not hold returns 404 NOT_FOUND.
skuSKU of the canonical Item to link, matched ignoring case and surrounding spaces. Foundation's SKU lookup reports a SKU that matches several Items as matching none, so an ambiguous SKU returns 422 NATURAL_KEY_NOT_FOUND, never NATURAL_KEY_AMBIGUOUS. The packaged SKU field is unique, so this arises only in a Mapped org.
replaceSet true to replace a different record the case item already names. Without it, a case item already linked to a different record returns 409 ALREADY_LINKED.
Link a case item to a canonical Item › Responses
OK — the updated case item. Linking to the record the case item already names returns 200 and changes nothing.
idSalesforce record id of the Case_Item__c junction row, assigned by Salesforce on insert. Null on POST cascade entry (new junction). Differs from involvementId, which the caller mints.
involvementIdCaller-minted identifier of this involvement (for example a UUID v4), reused unchanged on retry. At most 36 characters for a new or changed value; a value already stored on the case item is accepted unchanged whatever its length, and returned on every read. Immutable after create: an update that sends a different value for a stored involvement returns 400 IMMUTABLE_FIELD; a value that differs only in case is the same value, and the stored spelling is kept. A value already held by another involvement, on this case or any other, or repeated inside one request, returns 409 DUPLICATE_INVOLVEMENT_ID; the comparison ignores case.
itemIdCanonical Item id. Optional: on a new case item a sku that matches exactly one Item sets it for you; a stored case item is never linked by SKU. An id that names no Item returns 422 NATURAL_KEY_NOT_FOUND, and on a new case item an id and a sku that name different Items return 400 INVARIANT_VIOLATION. Immutable after create.
skuSKU as the incident reported it, stored as sent. Optional but encouraged. Matched against the Item catalog exactly after trimming and ignoring case, on SKU only and not UPC; on a new case item one match links that Item, no match or several leave the row unlinked, and a stored case item is never matched.
quantityQuantity of items involved in the incident.
conditionRecovery Status of the item: recovered, damaged or not recovered. Open-set: the org stores the value its value mapping gives each, and a value no row maps is stored and read back as sent.
valueAtIncidentAssessed value of the item at the time of the incident.
categoryItem category (e.g. Electronics, Apparel, Grocery). Open-set — not enumerated.
notesCase-side mutable context for the junction.
upcUniversal Product Code for the involved item.
serialNumberSerial number of the involved item.
unitTypeUnit type of the involved item (e.g. Each, Pair, Case).
itemNameName of the item as the incident reported it. Stored on the case item as sent.
merchandiseCategoryMerchandise category as reported. Any text is accepted, subject to any restriction the org places on the picklist.
merchandiseTypeMerchandise type as reported. Any text is accepted, subject to any restriction the org places on the picklist.
brandBrand as reported, free text.
departmentDepartment the item belongs to, as stored. Open-set: not enumerated.
stockNumberStock number the retailer assigns the item, stored as sent.
unitCostCost of one unit to the retailer.
totalPriceTotal price of the line, calculated by the platform. Returned on a load and ignored on writes.
totalCostTotal cost of the line, calculated by the platform. Returned on a load and ignored on writes.
attributedToSalesforce id of a saved involved person on this case that the item is attributed to. To name a person reported in the same request, send attributedToInvolvementId instead. An id that is not an involved person on this case is refused with 400 INVARIANT_VIOLATION. Removing the attributed person from the case, by detaching it or by a PUT that leaves it out and omits caseItems, clears the attribution. To change or clear an attribution, change or clear both attributedTo and attributedToInvolvementId: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution.
attributedToInvolvementIdThe involvementId of the involved person the item is attributed to, whether that person is in the same request or already on the case. It is resolved to attributedTo when the case is saved, in the same all-or-nothing save as the persons. A value that no involved person on this case holds is refused with 400 INVARIANT_VIOLATION. When attributedTo is also sent, both must name the same person or the request is refused with 400 INVARIANT_VIOLATION. A loaded case returns both attributedTo and attributedToInvolvementId for an attributed item. To change or clear an attribution, change or clear both fields: clearing only attributedTo while sending the loaded attributedToInvolvementId keeps the attribution, and repointing attributedTo while sending the old attributedToInvolvementId is refused.
Read-only preview of the referenced Item. Returned as null when the underlying Item is deleted, archived, or FLS-stripped.