Pay a vendor bill (Apideck MCP)

When the user wants to pay a known vendor bill, prefer apideck-pay-bill over stitching accounting-bills-get + accounting-bill-payments-create manually. The workflow tool fetches the bill, reads its outstanding balance, builds the right allocation, picks the correct AP endpoint, and surfaces structured errors with failingStep so you know which leg broke.

When this is the right tool

IMPORTANT RULES

• CONFIRM before calling. Pay-bill is mutating and not idempotent — calling twice creates two payments on the connected service. Always show the user the bill total, currency, payment account, and supplier, and wait for explicit confirmation before invoking the tool.
• PASS payment_method as a capitalized value when targeting QuickBooks: "Check", "CreditCard", "Cash". Lower-case "check" triggers a generic JSON-parse rejection from QuickBooks before any meaningful validation runs. Other connectors accept lower-case ("check", "ach", "wire", "credit_card").
• DON'T pass amount to pay the full balance — omit it and the workflow defaults to the bill's outstanding balance (which is the correct amount even on partially-settled bills). Only pass amount when the user explicitly wants a partial payment.
• SET x-apideck-service-id when the consumer has multiple accounting connections (e.g. both Xero and QuickBooks). Otherwise the call routes to whichever connection Apideck picks first.
• DON'T confuse with apideck-receive-customer-payment. Bills are accounts payable (you owe money). Invoices are accounts receivable (someone owes you). They route to different unified endpoints under the hood.

Argument map

Result shape

Success

{
  "bill_id": "4",
  "payment_id": "pay-77",
  "amount": 742.45,
  "currency": "USD",
  "transaction_date": "2026-04-26",
  "bill_total": 742.45,
  "partial": false,
  "service_id": "quickbooks"
}

partial: true means the agent paid less than the bill's outstanding balance. Use this to confirm with the user that a follow-up payment will be needed.

Failure (with isError: true)

{
  "bill_id": "4",
  "amount": 1,
  "currency": "USD",
  "error": "accounting-bill-payments-create failed: ...",
  "failingStep": "accounting-bill-payments-create",
  "upstream": { "status_code": 400, "type_name": "ConnectorExecutionError", ... }
}

failingStep tells you which leg failed:

• accounting-bills-get — the bill ID is wrong or the connector lost the record
• validate-amount — the bill has no positive outstanding balance (already paid, or zero-total)
• accounting-bill-payments-create — the payment write itself failed; inspect upstream for connector-specific reason

Worked example

User: "Pay the bill from LinkedIn for $742.45 from Business Checking."

1. accounting-bills-list with filter: { supplier_id: ... } to find the bill ID — say "4".
2. accounting-ledger-accounts-list with filter: { type: "bank" } to find Business Checking — say "8".
3. Confirm with the user: "Paying bill 4 (LinkedIn, $742.45 USD) from Business Checking via QuickBooks. Confirm?"
4. On confirmation, call:

   {
     "name": "apideck-pay-bill",
     "arguments": {
       "bill_id": "4",
       "account_id": "8",
       "payment_method": "Check",
       "x-apideck-service-id": "quickbooks"
     }
   }

5. Surface the resulting payment_id to the user.

Common failure modes

Related

• apideck-mcp — front-door skill for the MCP server itself
• apideck-mcp-receive-payment — AR mirror (customer paying you)
• Workflow source: src/gen/workflows/payBill.ts