Receivings

Create or Update Receiving

Changed on

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.
post/v1/integrations/receiving

Request

  • Base URL: https://api.shipmonk.com
  • URL: https://api.shipmonk.com/v1/integrations/receiving
  • Auth: API key in header Api-Key

Request body

warehousestring required

Code of the warehouse where the goods will be received. Determines which facility processes the shipment.

asnstring required

Advance Shipping Notice (ASN) number, a supplier-provided identifier for the incoming shipment. Used as the natural key for upserting the receiving.

supplier_namestring required

Name of the supplier sending the goods.

estimated_deliverystring 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
handling_unit_quantityinteger nullable

Total number of handling units (as specified by handling_unit_type) in the shipment. Omit or pass null if unknown.

receiving_keystring nullable

Optional client-supplied reference (e.g. purchase order number) for this receiving. Stored as-is and returned on subsequent reads.

descriptionstring nullable

Free-text description of the shipment. Optional; use to attach human-readable context such as supplier remarks or handling notes.

bol_numberstring nullable

Bill of lading (BoL) number from the carrier's contract of carriage; optional, supply when the inbound shipment has one for cross-referencing.

mrnstring nullable

Movement Reference Number (MRN) of the customs declaration: 18 characters (2-digit year, 2-letter country code, 14 alphanumeric characters). The grouping spaces printed on customs documents are accepted and stripped, and lowercase letters are canonicalized to uppercase, so the value as printed can be sent verbatim. UK-destined receivings must have an MRN on file before receiving can start; supply it here or add it later in the app. An MRN is only accepted on receivings that require one - sending it for other receivings (e.g. non-UK destinations) is rejected. On update, null or an omitted value leaves the stored MRN unchanged - the MRN cannot be cleared through this API.

category'purchase_order_asn' | 'inventory_transfer' | 'wholesale_order_return' | 'special_projects' | 'subscription_box_receiving' | 'bonded_inventory' | 'package_forwarding'
tracking_numbersstring[] 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.

Example request

{
  "warehouse": "PA1",
  "asn": "ASN-12345",
  "supplier_name": "Acme Supplier",
  "estimated_delivery": "2025-07-24",
  "items": [
    {
      "expected_quantity": 50,
      "barcode": "0123456789012",
      "lot": {
        "lot_number": "LOT-2025-001",
        "expiration_date": "2025-07-24"
      },
      "line_key": "LINE-001"
    }
  ],
  "handling_unit_quantity": 10,
  "receiving_key": "key-123",
  "description": "Spring collection shipment",
  "bol_number": "BOL-9876",
  "mrn": "26GB54YH3HD2C3RAR0",
  "custom_data": [
    {
      "name": "po_number",
      "value": "PO-98765"
    }
  ],
  "attributes": [
    {
      "name": "attribute_name",
      "value": "true"
    }
  ]
}

Response

Success

messagestring required

Human-readable message indicating whether the receiving was created or updated.

Changes