---
name: "purchasing_set_planned_date"
area: "purchasing"
title: "Plan when to pay a bill"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/purchasing_set_planned_date"
mcp_server: "https://api.conecto.chat/mcp/purchasing"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/purchasing/purchasing_set_planned_date"
---

# Plan when to pay a bill (`purchasing_set_planned_date`)

Plans the day the business will pay a bill, so the cash flow forecast takes the money out then rather than on the due date.

The day the business means to pay a bill that is not paid yet, like Xero's planned date: the cash flow forecast (books_report cash_forecast) counts the payment on that day, even for a bill already overdue, which it otherwise leaves out. null clears it.

Price: Free. A call that fails costs nothing.

## Use it when

The business pays a bill early or late on purpose, or waits for money to come in before paying.

- For paying it now, use [purchasing_pay_bill](https://conecto.chat/tools/purchasing/purchasing_pay_bill.md).
- For a new due date the supplier agreed, use [purchasing_update_bill](https://conecto.chat/tools/purchasing/purchasing_update_bill.md).

## Say this to your agent

> We will pay the Nordstahl bill on November 10th, after the hotel pays us. Plan it for then.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `bill_id` | string | yes | The bill_id purchasing_create_bill returned. Exactly 36 characters. |  |  |
| `date` | string or null | yes | YYYY-MM-DD, or null. Matches ^\\d{4}-\\d{2}-\\d{2}$. |  |  |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `purchasing_set_planned_date` on the MCP server `https://api.conecto.chat/mcp/purchasing` with these arguments:

```json
{
  "bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b",
  "date": "2026-11-10"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/purchasing_set_planned_date \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b", "date": "2026-11-10"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "purchasing_set_planned_date",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "bill": {
      "bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b",
      "supplier": {
        "supplier_id": 4101,
        "name": "Nordstahl Küchentechnik GmbH"
      },
      "reference": "NS-2026-1188",
      "status": "open",
      "overdue": false,
      "days_overdue": 0,
      "currency": "EUR",
      "issue_date": "2026-10-13",
      "due_date": "2026-11-12",
      "planned_date": "2026-11-10",
      "total": "462.50",
      "amount_paid": "0.00",
      "balance": "462.50",
      "order": "PO-0001",
      "lines": [
        {
          "description": "GN 1/1 pan, steel, 65 mm",
          "sku": "GN-PAN-11",
          "account": null,
          "quantity": "25",
          "unit_cost": "18.5",
          "tax_rate": "0",
          "amount": "462.50",
          "tax": "0.00",
          "order_line": 1
        }
      ],
      "subtotal": "462.50",
      "tax": "0.00",
      "tax_treatment": null,
      "order_id": "56f129f3-2149-40f4-bb47-b34e1ded9fd5",
      "payments": [],
      "file": {
        "file_id": "5846d0cf-deef-444d-aeb3-ab3aea5e9909",
        "name": "NS-2026-1188.pdf",
        "content_type": "application/pdf",
        "size": "1.1 KB",
        "size_bytes": 1147,
        "sha256": "24cfafaca922f96f27862a78624077499c6933a1caf04ba986e83cc228a836c3",
        "created_at": "2026-10-14T08:00:00+00:00",
        "download_url": "https://cncto.co/d/5846d0cf-deef-444d-aeb3-ab3aea5e9909?t=eyJmIjoiNTg0NmQwY2YtZGVlZi00NDRkLWFlYjMtYWIzYWVhNWU5OTA5IiwiZXhwIjoxNzkyNjkyMjY0fQ:1xJafo:ir2_frnIrzQtRXkB1zlew4JDFCZ1ZaiB4t2Kw-yydok",
        "link_expires_in_hours": 24
      },
      "notes": null,
      "books_entry": 1,
      "void_reason": null,
      "history": [
        {
          "at": "2026-10-14T08:00:00+00:00",
          "event": "recorded",
          "detail": "Pip",
          "by": "key 4101 (Pip)"
        }
      ]
    }
  }
}
```

`result`: bill: the bill with its planned_date (null when cleared).

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `not_found` | 404 | No bill of the business has that bill_id. | Find it with purchasing_list_bills. |
| `not_owed` | 409 | The bill is paid or void. | Give the date to a bill not paid yet. |
| `invalid_input` | 400 | The date is not valid. | Send it like 2026-11-10, or null to clear it. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [purchasing_save_supplier](https://conecto.chat/tools/purchasing/purchasing_save_supplier.md): Adds a supplier or changes one: contact, email for orders, address, currency, payment terms and the book account their bills go to. $0.01 a call.
- [purchasing_list_suppliers](https://conecto.chat/tools/purchasing/purchasing_list_suppliers.md): Suppliers by name, each with what is owed to them on open bills and how many orders are open. Free up to 1,000,000 reads a month.
- [purchasing_save_supplier_items](https://conecto.chat/tools/purchasing/purchasing_save_supplier_items.md): Says which Inventory items a supplier sells: their code, cost, pack size, minimum order, lead time and a fixed reorder quantity. $0.005 per item saved.
- [purchasing_list_supplier_items](https://conecto.chat/tools/purchasing/purchasing_list_supplier_items.md): What suppliers sell: codes, costs, packs, minimums, lead times and the preferred supplier, for one supplier or one SKU. Free up to 1,000,000 reads a month.
- [purchasing_draft_reorders](https://conecto.chat/tools/purchasing/purchasing_draft_reorders.md): Drafts one purchase order per supplier for every item at or below its reorder point, counting what is already on order. $0.01 per draft order.
- [purchasing_create_order](https://conecto.chat/tools/purchasing/purchasing_create_order.md): Drafts a purchase order to a supplier: lines (with Inventory SKUs if you like), currency, delivery date and stock location. $0.01 a call.
- [purchasing_update_order](https://conecto.chat/tools/purchasing/purchasing_update_order.md): Changes a draft order, or records it as sent without emailing it. $0.01 a call.
- [purchasing_send_order](https://conecto.chat/tools/purchasing/purchasing_send_order.md): Emails an order to the supplier with a link to its PDF; a draft takes the next number first. $0.10 a call.
- [purchasing_receive](https://conecto.chat/tools/purchasing/purchasing_receive.md): Records what arrived on a sent order; lines with a SKU come into Inventory at the ordered cost. $0.01 a call.
- [purchasing_close_order](https://conecto.chat/tools/purchasing/purchasing_close_order.md): Closes a sent order (stop waiting for the rest) or cancels one that received nothing. $0.01 a call.
- [purchasing_list_orders](https://conecto.chat/tools/purchasing/purchasing_list_orders.md): Purchase orders, newest first, by status, supplier or date; or one order in full. Free up to 1,000,000 reads a month.
- [purchasing_create_bill](https://conecto.chat/tools/purchasing/purchasing_create_bill.md): Records a bill a supplier sent, from its own lines or from an order, with its PDF; it is posted to the books. $0.01 a call.
- [purchasing_update_bill](https://conecto.chat/tools/purchasing/purchasing_update_bill.md): Adds a recorded bill's PDF if it has none, or changes its notes or due date; amounts and the PDF it has never change. $0.01 a call.
- [purchasing_pay_bill](https://conecto.chat/tools/purchasing/purchasing_pay_bill.md): Records money paid on a bill, or money back from the supplier; it is posted to the books. $0.01 a call.
- [purchasing_pay_bills](https://conecto.chat/tools/purchasing/purchasing_pay_bills.md): Pays several bills at once from one bank account, like Xero's batch payments, with the SEPA file to upload to the bank. $0.01 per bill paid.
- [purchasing_record_prepayment](https://conecto.chat/tools/purchasing/purchasing_record_prepayment.md): Records a deposit the business paid a supplier before their bill, like Xero's prepayments; it waits as a credit with them. $0.01 a call.
- [purchasing_use_credit](https://conecto.chat/tools/purchasing/purchasing_use_credit.md): Puts a credit with a supplier on their bill, like Xero's allocate credit, or records it coming back. $0.01 a call.
- [purchasing_list_credits](https://conecto.chat/tools/purchasing/purchasing_list_credits.md): Lists credits with suppliers, deposits and overpayments, with what is left on each. Free up to 1,000,000 reads a month.
- [purchasing_save_repeating_bill](https://conecto.chat/tools/purchasing/purchasing_save_repeating_bill.md): Records a supplier's bill again every so many weeks, months or years, with [Month] and [Year] filled in, like Xero's repeating bills. $0.01 a call.
- [purchasing_list_repeating_bills](https://conecto.chat/tools/purchasing/purchasing_list_repeating_bills.md): Lists the repeating bills: whose each is, how often, the next dates, and what each recorded. Free up to 1,000,000 reads a month.
- [purchasing_delete_repeating_bill](https://conecto.chat/tools/purchasing/purchasing_delete_repeating_bill.md): Stops a repeating bill for good; the bills it recorded stay. Free.
- [purchasing_void_bill](https://conecto.chat/tools/purchasing/purchasing_void_bill.md): Voids a bill entered by mistake; the books reverse it and its order can be billed again. $0.01 a call.
- [purchasing_list_bills](https://conecto.chat/tools/purchasing/purchasing_list_bills.md): Supplier bills by due date, filtered by status, supplier, order or dates; or one bill in full. Free up to 1,000,000 reads a month.
- [purchasing_report](https://conecto.chat/tools/purchasing/purchasing_report.md): Aged payables (what is owed to each supplier by how late) or spend (what each supplier billed and was paid). Free up to 1,000,000 reads a month.