v1.012

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[].