conecto. Get started
Purchasing

Receive a delivery

purchasing_receive · Changes data · Markdown

Records what arrived on a sent order; lines with a SKU come into Inventory at the ordered cost.

$0.01 a call

From your agent’s balance. A call that fails costs nothing.

An example

25 of the 40 GN pans arrived today. The rest come next week.

Your agent callspurchasing_receive$0.01 a call

The example business is Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. The reply is the one the tool really gives.

With these arguments
{
  "order": "PO-0001",
  "lines": [
    {
      "line": 1,
      "quantity": 25
    }
  ]
}
What comes back
{
  "order": {
    "order_id": "f5c39725-49ad-4169-937c-7d085b7f7bc1",
    "number": "PO-0001",
    "status": "partial",
    "supplier": {
      "supplier_id": 4101,
      "name": "Nordstahl Küchentechnik GmbH"
    },
    "currency": "EUR",
    "total": "835.00",
    "issue_date": "2026-10-14",
    "expected_on": "2026-11-02",
    "created_at": "2026-10-14T08:00:00+00:00",
    "lines": [
      {
        "line": 1,
        "sku": "GN-PAN-11",
        "description": "GN 1/1 pan, steel, 65 mm",
        "quantity": "40",
        "unit_cost": "18.5",
        "tax_rate": "0",
        "amount": "740.00",
        "tax": "0.00",
        "received": "25",
        "billed": "0",
        "to_receive": "15"
      },
      {
        "line": 2,
        "sku": null,
        "description": "Delivery",
        "quantity": "1",
        "unit_cost": "95",
        "tax_rate": "0",
        "amount": "95.00",
        "tax": "0.00",
        "received": "0",
        "billed": "0",
        "to_receive": "1"
      }
    ],
    "subtotal": "835.00",
    "tax": "0.00",
    "location": "Main",
    "notes": "Please deliver to the warehouse gate, Billbrookdeich 112.",
    "pdf": {
      "file_id": "97673096-25d8-4085-b032-a9697581d0f9",
      "name": "Purchase order PO-0001.pdf",
      "content_type": "application/pdf",
      "size": "582 bytes",
      "size_bytes": 582,
      "sha256": "7a628ee1199dd863f0236a61a39b6729a977b4ea18a669e9930a57280cb2326e",
      "created_at": "2026-10-14T08:00:00+00:00",
      "download_url": "https://cncto.co/d/97673096-25d8-4085-b032-a9697581d0f9?t=eyJmIjoiOTc2NzMwOTYtMjVkOC00MDg1LWIwMzItYTk2OTc1ODFkMGY5IiwiZXhwIjoxNzkyMTYxMjE3fQ:1xHMWX:v8CeX7HXHDyLtsv0BqNt4JEiRrfMERmyFVMaMRfXlv0",
      "link_expires_in_hours": 24
    },
    "bills": [],
    "sent_at": "2026-10-14T08:00:00+00:00",
    "closed_at": null,
    "history": [
      {
        "at": "2026-10-14T08:00:00+00:00",
        "event": "created",
        "detail": "",
        "by": "key 4101 (Pip)"
      },
      {
        "at": "2026-10-14T08:00:00+00:00",
        "event": "sent",
        "detail": "PO-0001",
        "by": "key 4101 (Pip)"
      }
    ]
  },
  "received": [
    {
      "line": 1,
      "quantity": "25"
    }
  ],
  "stock_moves": [
    {
      "move_id": 4101,
      "date": "2026-10-14",
      "kind": "receive",
      "sku": "GN-PAN-11",
      "quantity": "25",
      "from": null,
      "to": "Main",
      "unit_cost": "18.5",
      "value": "462.50",
      "quantity_after": "25",
      "reference": "PO-0001",
      "note": "PO-0001 from Nordstahl Küchentechnik GmbH"
    }
  ]
}

Use it when

A delivery from a supplier arrived, in full or in part.

What it does

Record what arrived on a sent order: lines [{line, quantity}] (line numbers as the order lists them), or all: true for everything still to come. Lines with a SKU come into Inventory as receive moves at the ordered unit cost, at the order's location (or location); when the order's currency is not the item's, give that line's unit_cost in the item's currency. More than ordered is refused (take the extra in with inventory_move). All lines or none. The order becomes partial, or received when nothing is left to come.

What comes back

order: the order with what each line has received, now partial or received; received: the lines taken in; stock_moves: the Inventory moves made. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
orderRequiredstringThe order_id, or the order's number like "PO-0007". 1 to 40 characters.
linesarray of objects1 to 200 items.
lines[].lineRequiredinteger1 to 200.
lines[].quantityRequirednumber or stringUp to 24 characters.
lines[].unit_costnumber or stringOnly when the item is valued in another currency: the cost of one in that currency. Up to 24 characters.
allbooleanReceive everything still to come. Default: false.
locationstringWhere the stock goes, instead of the order's location. Up to 120 characters.
datestringWhen it arrived. Default today. Matches ^\d{4}-\d{2}-\d{2}$.

The call

Over MCP, call purchasing_receive on https://api.conecto.chat/mcp/purchasing. Over REST:

Terminal
curl -X POST https://api.conecto.chat/v1/tools/purchasing_receive \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order":"PO-0001","lines":[{"line":1,"quantity":25}]}'

When it refuses

A refused call costs nothing and says what to do next.

CodeWhenWhat to do
not_found404No purchase order has that order_id or number.Find it with purchasing_list_orders.
not_found404A line's SKU is not an Inventory item, or the location does not exist.Add the item with inventory_save_items, or leave the SKU out.
archived409The supplier, item, location or account is archived.Bring the supplier back with purchasing_save_supplier archived: false, or use another one.
order_closed409The order is closed.Draft a new order.
order_cancelled409The order is cancelled.Draft a new order.
not_sent409The order is still a draft.Send it, or mark it sent with purchasing_update_order.
already_received409Everything on the order was received.Nothing more to receive.
nothing_to_receive409Nothing is left to receive.Nothing more to receive.
more_than_ordered409A line would receive more than was ordered.Receive at most what is left, and take the extra in with inventory_move.
currency_mismatch409The order's currency differs from the item's.Give that line's unit_cost in the item's currency.
invalid_input400Neither lines nor all was given, or a quantity or date is not valid.Send lines or all: true.

More Purchasing tools

All 25 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md