Skip to content

apideck-libraries/api-skills / providers/claude/plugin/skills/apideck-mcp-pay-bill

apideck-mcp-pay-bill

Verified

Task playbook for paying a vendor bill via the Apideck MCP server's `apideck-pay-bill` workflow tool. Use when the user asks to settle, pay, or close a known accounts-payable bill in QuickBooks, Xero, NetSuite, or any other connected accounting service. Covers confirmation prompts, partial payments, payment-method capitalization quirks, and the AP-vs-AR routing decision agents routinely get wrong.

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 intentTool
"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

ArgRequiredDefaultNotes
bill_idyes—From accounting-bills-list. The numeric or UUID id Apideck returns.
account_idyes—The bank/cash account the payment is drawn from. From accounting-ledger-accounts-list filtered to type=bank.
amountnobill's outstanding balanceIn bill's currency. Pass smaller for a partial payment.
transaction_datenotoday (YYYY-MM-DD)Some connectors reject future dates.
payment_methodno—QB requires capitalized: "Check" etc. Other connectors flexible.
referenceno—Memo / external reference shown on the payment record.
x-apideck-service-idnofirst accounting connectionE.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

SymptomCauseFix
failingStep: validate-amountBill has zero outstanding balanceEither it's already paid, or pass an explicit amount to override
QuickBooks rejects with Property Name:failed to parse json objectpayment_method lower-casePass "Check" (capitalized) for QB
QuickBooks rejects with CustomerRef missingWrong unified endpoint chosen — workflow protects against thisShould not happen via apideck-pay-bill; if it does, file a bug
failingStep: accounting-bill-payments-create with Subscription period has endedQB sandbox/account billing issue, not a workflow bugRenew connector subscription
UrlElicitationRequiredError thrownConnection expired or never authorizedSurface the consent URL to user, retry after OAuth

Related

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall