apideck-libraries/apideck-mcp-pay-bill

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

| User intent | Tool | |---|---| | "Pay bill 6", "Settle the LinkedIn invoice", "Close out bill from RocketReach" | apideck-pay-bill ✓ | | "Record that customer paid invoice 4" | apideck-receive-customer-payment (AR mirror — different unified endpoint) | | "Create a prepayment / unallocated transfer" | accounting-payments-create directly (no allocation) | | "Show me unpaid bills" | accounting-bills-list with filter[status]=open |

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

| Arg | Required | Default | Notes | |---|---|---|---| | bill_id | yes | — | From accounting-bills-list. The numeric or UUID id Apideck returns. | | account_id | yes | — | The bank/cash account the payment is drawn from. From accounting-ledger-accounts-list filtered to type=bank. | | amount | no | bill's outstanding balance | In bill's currency. Pass smaller for a partial payment. | | transaction_date | no | today (YYYY-MM-DD) | Some connectors reject future dates. | | payment_method | no | — | QB requires capitalized: "Check" etc. Other connectors flexible. | | reference | no | — | Memo / external reference shown on the payment record. | | x-apideck-service-id | no | first accounting connection | E.g. "xero", "quickbooks". |

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

| Symptom | Cause | Fix | |---|---|---| | failingStep: validate-amount | Bill has zero outstanding balance | Either it's already paid, or pass an explicit amount to override | | QuickBooks rejects with Property Name:failed to parse json object | payment_method lower-case | Pass "Check" (capitalized) for QB | | QuickBooks rejects with CustomerRef missing | Wrong unified endpoint chosen — workflow protects against this | Should not happen via apideck-pay-bill; if it does, file a bug | | failingStep: accounting-bill-payments-create with Subscription period has ended | QB sandbox/account billing issue, not a workflow bug | Renew connector subscription | | UrlElicitationRequiredError thrown | Connection expired or never authorized | Surface the consent URL to user, retry after OAuth |

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