conecto. Get started
Purchasing

Use a supplier credit

purchasing_use_credit · Changes data · Markdown

Puts a credit with a supplier on their bill, like Xero's allocate credit, or records it coming back.

$0.01 a call

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

An example

Use our deposit with Nordstahl on their bill NS-2026-1188.

Your agent callspurchasing_use_credit$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
{
  "credit": "SC-0001",
  "bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b"
}
What comes back
{
  "credit": {
    "number": "SC-0001",
    "kind": "prepayment",
    "status": "open",
    "date": "2026-10-14",
    "currency": "EUR",
    "amount": "1190.00",
    "left": "727.50",
    "tax_rate": "19",
    "tax": "190.00",
    "method": "bank_transfer",
    "reference": "Anzahlung AB-2026-311",
    "note": null,
    "entry": 1,
    "supplier": {
      "supplier_id": 4101,
      "name": "Nordstahl Küchentechnik GmbH"
    },
    "history": [
      {
        "at": "2026-10-14T08:00:00+00:00",
        "what": "received",
        "amount": "1190.00"
      },
      {
        "at": "2026-10-14T08:00:00+00:00",
        "what": "used",
        "amount": "462.50",
        "tax": "73.84",
        "payment": 1,
        "bill": "NS-2026-1188"
      }
    ]
  },
  "bill": {
    "bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b",
    "supplier": {
      "supplier_id": 4101,
      "name": "Nordstahl Küchentechnik GmbH"
    },
    "reference": "NS-2026-1188",
    "status": "paid",
    "overdue": false,
    "days_overdue": 0,
    "currency": "EUR",
    "issue_date": "2026-10-13",
    "due_date": "2026-11-12",
    "total": "462.50",
    "amount_paid": "462.50",
    "balance": "0.00",
    "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": "3b1c3c9c-09be-4d35-8e84-e33023d2fe58",
    "payments": [
      {
        "payment_id": 4101,
        "amount": "462.50",
        "date": "2026-10-14",
        "method": "credit",
        "reference": "SC-0001",
        "note": null,
        "batch": null
      }
    ],
    "file": {
      "file_id": "be282d4d-6d33-43b8-8436-8abbdfaa2c3a",
      "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/be282d4d-6d33-43b8-8436-8abbdfaa2c3a?t=eyJmIjoiYmUyODJkNGQtNmQzMy00M2I4LTg0MzYtOGFiYmRmYWEyYzNhIiwiZXhwIjoxNzkyNDgxMDUzfQ:1xIhjB:hU-AHFYl8jzr2sCio7vVnNSWZOwYjg6FTPiCoh6fXpQ",
      "link_expires_in_hours": 24
    },
    "notes": null,
    "books_entry": 2,
    "void_reason": null,
    "history": [
      {
        "at": "2026-10-14T08:00:00+00:00",
        "event": "recorded",
        "detail": "Pip",
        "by": "key 4101 (Pip)"
      },
      {
        "at": "2026-10-14T08:00:00+00:00",
        "event": "payment",
        "detail": "€462.50",
        "by": "key 4101 (Pip)"
      }
    ]
  },
  "entry": 3
}

Use it when

The bill for a deposit comes in, the supplier pays an overpayment back, or a deposit was recorded by mistake (void).

What it does

Put a credit with a supplier (a prepayment or an overpayment) on one of their open bills, like Xero's allocate credit: bill_id, and amount (default all it can: what is left on the credit or the bill, the smaller); the bill records it as a payment with method credit, and its share of the credit's VAT comes back off. Or refund: true records what is left (or amount) coming back from the supplier, with date and method; or void: true takes back a prepayment recorded by mistake while none of it is used. Same supplier and currency only.

What comes back

credit: what is left and how it was used; with a bill, the bill and the entry; with refund, the entry. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
creditRequiredstringThe credit's number, like "SC-0001" (purchasing_list_credits). 1 to 20 characters.
bill_idstringThe bill_id purchasing_create_bill returned. Exactly 36 characters.
amountnumber or stringUp to 24 characters.
refundbooleanDefault: false.
voidbooleanDefault: false.
datestringYYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
methodstringOne of: bank_transfer,card,cash,check,online,other. Default: bank_transfer.
referencestringUp to 120 characters.

The call

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

Terminal
curl -X POST https://api.conecto.chat/v1/tools/purchasing_use_credit \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credit":"SC-0001","bill_id":"3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b"}'

When it refuses

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

CodeWhenWhat to do
not_found404No bill of the business has that bill_id.Find it with purchasing_list_bills.
unbalanced400The debits and credits do not add up to the same amount.Make the lines balance.
before_start409The date is before the books start.Use a later date.
period_locked409The books are locked for that date.Use a later date, or unlock with books_lock.
no_rate409There is no exchange rate for the currency on that day.Pass rate, or set a standing rate with books_setup rates.
rates_loading503The day's exchange rates are still loading.Try again in a few minutes, or pass rate.
invalid_input400Not exactly one of bill_id, refund and void; or an amount or date that is not valid.Fix what the message names.
more_than_left409The credit has less left than the amount, or nothing.Use or record at most what is left.
more_than_balance409The bill owes less than the amount.Leave amount out to use what fits.
other_supplier409The bill is another supplier's.Use it on this supplier's bills.
currency_mismatch409The bill is in another currency.Use it on a bill in its currency.
void409The bill is void.Use it on another bill.
already_paid409The bill is paid in full.Use it on another bill, or record it coming back.
in_use409Void: some of the deposit is used or came back already.Record the rest coming back.

More Purchasing tools

All 25 tools

Give this to your agent.

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