Mark supplier shipment as received

Mark Supplier Shipment as Received

Basic Receipt

When the warehouse receives inventory, submit a receipt confirmation to mark the supplier shipment as received in Fulfil.

Receipt Example:

{
  "reference": "ASN-12345",
  "tpl_reference": "WH-RCV-98765",
  "status": "received",
  "items": [
    {
      "id": 123456,
      "sku": "PRODUCT-001",
      "quantity": 100
    },
    {
      "id": 123457,
      "sku": "PRODUCT-002",
      "quantity": 50
    }
  ]
}

Key Fields:

reference: The ASN reference from Fulfil
tpl_reference: Your internal warehouse receipt reference
status: Set to "received"
items[].id: The line item ID from the original ASN (best practice)
items[].sku: Product SKU
items[].quantity: Actual quantity received

Partial Receipts

If a shipment was received partially (the supplier short shipped), only receive the quantity that was actually received.

Receiving Strategies:

finalize_and_start_new (Default):

Receive the items on the existing Fulfil supplier shipment and mark it as 'done'
Any remaining items are split onto a new supplier shipment for future receipt
Use this when you don't expect the remaining items in the same delivery

split_and_keep_open:

The existing supplier shipment remains open for yet-to-receive items
Partially received items are split onto a new supplier shipment and marked as 'done'
Use this when you expect additional items from the same shipment

Partial Receipt Example:

{
  "reference": "ASN-12345",
  "tpl_reference": "WH-RCV-98765",
  "receiving_strategy": "finalize_and_start_new",
  "status": "received",
  "items": [
    {
      "id": 123456,
      "sku": "PRODUCT-001",
      "quantity": 75  // Expected 150, received 75
    }
  ]
}

Over Shipments

If a supplier ships more than the expected quantity, set quantity to the actual quantity received:

{
  "id": 123456,
  "sku": "PRODUCT-001",
  "quantity": 120  // Expected 100, received 120
}

Important: If an over-shipment includes completely different SKUs not part of the ASN, coordinate with the merchant to issue a new PO for those unexpected items, then receive against that new ASN.

Best Practices

Always send line IDs: Include the id field from the original ASN to help Fulfil identify the exact line being received
Receive what you get: Submit the actual quantity received, whether partial or over
Use appropriate receiving strategy: Choose the strategy that matches your workflow for partial receipts

Advanced: Lot Number Support

Some products require lot tracking for traceability and expiry management. When receiving lot-tracked products, the warehouse captures lot numbers and expiry dates and passes this information to Fulfil.

When to Use Lot Numbers

Determining Lot-Enabled Products:

Check the lot_enabled_warehouses field in the Product object from the ASN
If your warehouse ID is in this list, the product requires lot tracking
Only include lot information for lot-enabled products

Lot Number Basics

Automatic Lot Creation:

If a lot number doesn't exist in Fulfil, it will be created automatically
Each product can be received with multiple lot numbers in a single receipt
Split received quantities by lot number when submitting receipts

Lot Object Structure:

{
  "lot": {
    "number": "LOT-2025-001",        // Required
    "expiry_date": "2026-03-15"      // Optional (format: YYYY-MM-DD)
  }
}

Single Lot Receipt

Example: One product, one lot

{
  "reference": "ASN-12345",
  "tpl_reference": "WH-RCV-98765",
  "status": "received",
  "items": [
    {
      "id": 123456,
      "sku": "PRODUCT-001",
      "quantity": 100,
      "lot": {
        "number": "LOT-2025-001",
        "expiry_date": "2026-03-15"
      }
    },
    {
      "id": 123457,
      "sku": "PRODUCT-002",
      "quantity": 50
      // No lot object - this product doesn't require lot tracking
    }
  ]
}

Multiple Lots for Same Product

When receiving the same product across multiple lot numbers, submit the same line ID multiple times with different lot numbers and quantities.

Example: 150 units across 3 lots

{
  "reference": "ASN-12345",
  "tpl_reference": "WH-RCV-98765",
  "status": "received",
  "items": [
    {
      "id": 123456,
      "sku": "PRODUCT-001",
      "quantity": 60,
      "lot": {
        "number": "LOT-A-2025",
        "expiry_date": "2026-01-30"
      }
    },
    {
      "id": 123456,  // Same ID as above
      "sku": "PRODUCT-001",
      "quantity": 50,
      "lot": {
        "number": "LOT-B-2025",
        "expiry_date": "2026-02-15"
      }
    },
    {
      "id": 123456,  // Same ID as above
      "sku": "PRODUCT-001",
      "quantity": 40,
      "lot": {
        "number": "LOT-C-2025",
        "expiry_date": "2026-03-01"
      }
    }
  ]
}

Partial Receipts with Lot Numbers

Combine partial receipt strategies with lot information:

{
  "reference": "ASN-12345",
  "tpl_reference": "WH-RCV-98765",
  "receiving_strategy": "finalize_and_start_new",
  "status": "received",
  "items": [
    {
      "id": 123456,
      "sku": "PRODUCT-001",
      "quantity": 75,  // Expected 150, received 75 from one lot
      "lot": {
        "number": "LOT-2025-001",
        "expiry_date": "2026-03-15"
      }
    }
  ]
}

If you receive partial quantities across multiple lots:

{
  "reference": "ASN-12345",
  "tpl_reference": "WH-RCV-98765",
  "receiving_strategy": "split_and_keep_open",
  "status": "received",
  "items": [
    {
      "id": 123456,
      "sku": "PRODUCT-001",
      "quantity": 30,
      "lot": {
        "number": "LOT-A-2025",
        "expiry_date": "2026-01-30"
      }
    },
    {
      "id": 123456,
      "sku": "PRODUCT-001",
      "quantity": 45,
      "lot": {
        "number": "LOT-B-2025",
        "expiry_date": "2026-02-15"
      }
    }
  ]
}

Lot Tracking Best Practices

Identify lot-enabled products: Check Product.lot_enabled_warehouses from the ASN data
Consistent lot format: Use lot number formatting as agreed with the merchant
Capture expiry dates: Always include expiry dates when available
Split by lot: Always split quantities when receiving multiple lots of the same product
Validate before submission: Ensure lot information is present for lot-enabled products before submitting the receipt