Introduces an explicit Pallet → Carton → Item packing hierarchy on POST and GET /v1/integrations/receiving, aligned with EDI 856 (Tare → Pack → Item). The legacy items[].sscc field is deprecated and scheduled for removal on 2026-06-30.

🚀 New Endpoints

None

🛠 Schema & Property Updates

Create Or Update Receiving Input — added two top-level optional arrays describing the packing hierarchy:
- cartons (array|null) — cartons in EDI 856 Pack level. Accepts absent, null, or []; all three normalize to an empty list.
- pallets (array|null) — pallets in EDI 856 Tare level. Same null/absent/[] semantics.
Receiving Item Input — added two optional placement fields linking an item to its carton or pallet within the same payload. Exactly one is non-null when the new packing-hierarchy shape is used.
- carton_key (string|null, max 255) — references cartons[].carton_key.
- loose_units_pallet_key (string|null, max 255) — references pallets[].pallet_key for loose units that have no carton.
Receiving Output — added two top-level arrays surfacing the persisted packing hierarchy:
- cartons (array of Carton Output) — required.
- pallets (array of Pallet Output) — required.
Receiving Line Output — added two required placement fields mirroring the input:
- carton_key (string|null)
- loose_units_pallet_key (string|null)

📦 New Support Schemas

Carton Input — carton_key (string, required, max 255), pallet_key (string|null, max 255, references parent pallet), identifiers (array of Receiving Packaging Identifier Input, default [], at most one per type).
Pallet Input — pallet_key (string, required, max 255), identifiers (array of Receiving Packaging Identifier Input, default [], at most one per type).
Receiving Packaging Identifier Input — type (Receiving Packaging Identifier Type, required), value (string, required, max 255). For type=SSCC, value must be a valid 18-digit GS1 SSCC.
Carton Output — carton_key (string), pallet_key (string|null), identifiers (array of Receiving Packaging Identifier Output).
Pallet Output — pallet_key (string), identifiers (array of Receiving Packaging Identifier Output).
Receiving Packaging Identifier Output — type (Receiving Packaging Identifier Type), value (string).
Receiving Packaging Identifier Type (enum) — currently a single value: SSCC. The schema is forward-compatible: future identifier types (e.g. GTIN, internal labels, carrier tracking numbers) can be added without further breaking changes.

📖 Documentation & Constraints Changes

The cartons[] / pallets[] arrays accept three equivalent wire forms — absent, null, [] — all normalize to an empty list. Validation rules apply only when the payload uses the new shape (any item carries carton_key / loose_units_pallet_key, or cartons[] / pallets[] is non-empty).
When the new shape is in use, the API enforces several payload-level consistency rules (returned as 400 with field-specific paths):
- Each item must reference exactly one of carton_key or loose_units_pallet_key (never both, never neither).
- Every items[].carton_key must match an entry in cartons[]; every items[].loose_units_pallet_key must match an entry in pallets[]; every cartons[].pallet_key (when set) must match an entry in pallets[].
- Every entry in cartons[] must be referenced by at least one item; every entry in pallets[] must be referenced by at least one item or carton (no orphan packing rows).
- SSCCs are all-or-none across cartons[] ∪ pallets[] and must be unique within the payload.
A carton/pallet may carry multiple typed identifiers, but at most one identifier per type (e.g. only one SSCC).

⚠️ Deprecated

Receiving Item Input — items[].sscc is now marked deprecated and will be removed on 2026-06-30. The field is silently ignored when carton_key or loose_units_pallet_key is set on the same item. Migration: send the SSCC on the item's carton or pallet via cartons[].identifiers / pallets[].identifiers with type=SSCC instead.
Receiving Line Output — receiving_lines[].sscc description updated to reflect the same deprecation. For items placed on a carton, the field mirrors the carton's SSCC; for loose items on a pallet, it mirrors the pallet's SSCC. Consumers should migrate to reading cartons[].identifiers / pallets[].identifiers plus the new carton_key / loose_units_pallet_key placement on receiving_lines[].