--- title: "Create or Update Receiving" method: POST path: "/v1/integrations/receiving" tags: ["Receivings"] --- # Create or Update Receiving `POST /v1/integrations/receiving` ## General description - ERP push to ShipMonk - `items.[].lot` or any of its property can be null ## ASN & Receiving Key - When updating a Receiving, the identifying properties are `receiving_key` and `asn` in this order. - In case both are supplied - First, Receiving is retrieved by `receiving_key`. If found, it is updated with new ASN if current ASN is different than `asn` in the request body. - If not found, Receiving is retrieved by `asn`. If found, it is updated with new `receiving_key` in the request body. - If not found, new Receiving is created with `receiving_key` and asn being its unique identifiers. - In case only asn is supplied - First, Receiving is retrieved by `asn`. If found, `receiving_key` of the Receiving is left as-is as it cannot be deleted upon setting up. - If not found, new Receiving is created with `asn` being its unique identifier. - In case only `receiving_key` is supplied - The request is rejected, as `asn` is required field. ## LineKey - When item objects are supplied with `line_key` string field, these items are then uniquely identified and can be referenced by it, if needed to change expected quantity. - Line Key must be unique per receiving. - Null/missing values are also expected. Such lines are then grouped by product and lot if supplied multiple times in the POST request. ## Request body - ShipMonkPublicApiReceivingReceivingCreateOrUpdateCreateOrUpdateReceivingInput - `warehouse` string, required — Code of the warehouse where the goods will be received. Determines which facility processes the shipment. - `asn` string, required — Advance Shipping Notice (ASN) number, a supplier-provided identifier for the incoming shipment. Used as the natural key for upserting the receiving. - `supplier_name` string, required — Name of the supplier sending the goods. - `estimated_delivery` string, date, required — Estimated date when the shipment is expected to arrive at the warehouse, in ISO 8601 format (YYYY-MM-DD). - `handling_unit_type` 'small_boxes' | 'single_sku_pallet' | 'mixed_sku_pallet' | 'container_20_palletized' | 'container_20_non_palletized' | 'container_40_palletized' | 'container_40_non_palletized' | 'container_53_palletized' | 'container_53_non_palletized' | 'unknown', required - `items` ShipMonkPublicApiReceivingReceivingCreateOrUpdateReceivingItemInput[], required — Line items expected in this receiving, one entry per product (and lot, if tracked). - `sku` string, required — Stock Keeping Unit (SKU), the client's unique product code. - `expected_quantity` integer, required — Number of units expected on this line; must be greater than 0. - `barcode` string, nullable — Barcode used to identify the product (e.g. UPC, EAN). Required if the product cannot be resolved by other means; must match an existing product's barcode. - `lot` ShipMonkPublicApiReceivingReceivingCreateOrUpdateReceivingItemLotInput - `lot_number` string, nullable — Supplier-assigned lot/batch number. Pass null if unknown. - `expiration_date` string, date, nullable — Lot expiration date in ISO 8601 format (YYYY-MM-DD). Pass null if the product has no expiration. - `line_key` string, nullable — Optional client-supplied key uniquely identifying this line within the receiving. Required when using the packing-hierarchy fields (carton_key or loose_units_pallet_key); must be unique across items in this request. - `carton_key` string, nullable — Key referencing a carton in cartons[].carton_key, indicating these units are packed in that carton. Exactly one of carton_key or loose_units_pallet_key must be non-null when using the packing-hierarchy fields. - `loose_units_pallet_key` string, nullable — Key referencing a pallet in pallets[].pallet_key, indicating these units sit loose on that pallet (no carton). Exactly one of carton_key or loose_units_pallet_key must be non-null when using the packing-hierarchy fields. - `handling_unit_quantity` integer, nullable — Total number of handling units (as specified by handling_unit_type) in the shipment. Omit or pass null if unknown. - `receiving_key` string, nullable — Optional client-supplied reference (e.g. purchase order number) for this receiving. Stored as-is and returned on subsequent reads. - `description` string, nullable — Free-text description of the shipment. Optional; use to attach human-readable context such as supplier remarks or handling notes. - `bol_number` string, nullable — Bill of lading (BoL) number from the carrier's contract of carriage; optional, supply when the inbound shipment has one for cross-referencing. - `category` 'purchase_order_asn' | 'inventory_transfer' | 'wholesale_order_return' | 'special_projects' | 'subscription_box_receiving' | 'bonded_inventory' | 'package_forwarding' - `custom_data` ShipMonkPublicApiReceivingReceivingCreateOrUpdateReceivingCustomDataItemInput[] — Optional list of custom name/value pairs to attach arbitrary metadata to the receiving for reporting or integration use. - `name` string, required — Name (key) of the custom metadata entry; should be unique within the receiving's custom_data list. - `value` string, required — Value stored under the corresponding custom_data name. - `cartons` ShipMonkPublicApiReceivingReceivingCreateOrUpdateCartonInput[], nullable — Cartons in the packing hierarchy (equivalent to EDI 856 Pack level). Each carton has a unique carton_key and may reference a pallet. Absent, null, or [] all normalize to an empty list. - `carton_key` string, required — Client-supplied key that uniquely identifies this carton within the request; used by other entries (e.g. items) to reference it. - `pallet_key` string, nullable — Optional reference to a pallet_key in the pallets list, indicating this carton is stacked on that pallet. Omit if the carton is loose. - `identifiers` ShipMonkPublicApiReceivingReceivingCreateOrUpdateLpnInput[] — Typed identifiers (e.g. SSCC barcode) attached to this carton; at least one entry is required, at most one per type, and each value must be unique across all cartons and pallets of the receiving. - `type` 'SSCC', required - `value` string, required — Identifier value. For type=SSCC, a valid GS1 SSCC — 18 digits or 20 digits with leading "00"; stored and returned as 20 digits. - `pallets` ShipMonkPublicApiReceivingReceivingCreateOrUpdatePalletInput[], nullable — Pallets in the packing hierarchy (equivalent to EDI 856 Tare level). Each pallet has a unique pallet_key referenced by cartons. Absent, null, or [] all normalize to an empty list. - `pallet_key` string, required — Client-supplied key that uniquely identifies this pallet within the request; referenced by cartons.pallet_key. - `identifiers` ShipMonkPublicApiReceivingReceivingCreateOrUpdateLpnInput[] — Optional list of typed identifiers (e.g. SSCC barcode) attached to this pallet; at most one entry per type, and each value must be unique across all cartons and pallets of the receiving. - `type` 'SSCC', required - `value` string, required — Identifier value. For type=SSCC, a valid GS1 SSCC — 18 digits or 20 digits with leading "00"; stored and returned as 20 digits. - `tracking_numbers` string[], nullable — Tracking numbers of packets in this receiving. When omitted on update, the existing tracking numbers are left untouched. When provided as an empty list, all tracking numbers are removed. When provided with values, the existing tracking numbers are replaced with the new list. ## Response `200` Success - FulfillmentIntegrationsBundleCrateReceivingCreateOrUpdateOutput - `message` string, required — Human-readable message indicating whether the receiving was created or updated. --- [API](https://skmtc.net/shipmonk/apis/shipmonk-api.md) · [All operations](https://skmtc.net/shipmonk/apis/shipmonk-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipmonk/shipmonk-api/versions/59ec2621d98d/schema)