Sign in

v3

latestOpenAPI 3.1.02026-08-0619186200.1 KB
Receivings

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

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.

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",
  "items": [
    {
      "expected_quantity": 50,
      "barcode": "0123456789012",
      "lot": {
        "lot_number": "LOT-2025-001"
      },
      "line_key": "LINE-001"
    }
  ],
  "handling_unit_quantity": 10,
  "receiving_key": "key-123",
  "description": "Spring collection shipment",
  "bol_number": "BOL-9876",
  "custom_data": [
    {
      "name": "po_number",
      "value": "PO-98765"
    }
  ]
}

Response

Success

messagestring required

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