title: Bill Pay source_url: /developer-api/v1/bill-pay summary: A bill is the structured accounts payable record in Ramp — the object that powers approvals, coding, and payment. content: A **bill** is the structured accounts payable record in Ramp — the object that powers approvals, coding, and payment. For product details, see the [Ramp Help Center↗](). ## How bills work A bill carries the vendor, amount, due date, line items, and the payment details that fund it. Bill payment details are nested, so creating a bill via API includes the payment shape in the same request. Payment info is returned as part of the bill object on `GET /bills`. The [Payments API (beta)]() provides dedicated payment operations and can also create vendor payments without a bill. ### Bill lifecycle The product workflow has the following stages. In API responses, `approval_status` tracks review separately from payment `status` (`OPEN` or `PAID`): 1. **Draft** → Invoice uploaded, OCR extracts details. 2. **Pending approval** → Awaiting approver sign-off in Ramp. 3. **Approved** → Ready for payment. Bills follow your customer's configured approval policy in Ramp — see [Spend Controls]() for the policy surface, or the [help center article↗]() for product-side configuration. 4. **Paid** → Payment processed. Bills created with `POST /developer/v1/bills` are automatically approved and enter the workflow at the **Approved** status. ## Draft bill endpoints The Developer API can create, update, and submit draft bills into the approval workflow. It does not expose a bill-approval endpoint. Authorized reviewers can approve bills in Ramp or through Ramp MCP. ### Payment methods A bill chooses a payment method, and each method carries its own shape on `POST /bills`. Common options include: | Method | What it is | Timing | | --- | --- | --- | | **Card** | Pay by Ramp card (existing or single-use virtual). Earns cashback. | Depends on when the vendor charges the card | | **ACH** | Bank transfer via verified vendor bank account. | Standard delivery typically 2–5 business days | | **Check** | Mailed check to vendor's address on file. | Funding time plus mailing time | | **Wire** | Domestic wire transfer. | Depends on funding, eligibility, and cutoffs | | **SWIFT** | International wire transfer. | Varies | | **Stablecoin** | Payout to a vendor's crypto wallet, settled on-chain in a stablecoin. | Depends on funding and on-chain processing | Timing varies by funding source, vendor, and processing cutoff. Check [Bill payment methods and timelines↗]() for current estimates and fees. ### Create bill request builder Use [`POST /bills`]() to create an approved bill with nested payment details. The request requires several UUIDs; fetch them from the endpoints below before building the request. | Source endpoint | Response field | Request field on `POST /bills` | | --- | --- | --- | | [`GET /entities`]() | `id` | `entity_id` | | [`GET /entities`]() | `bank_accounts[].id` where `usage_type = BILL_PAY_BANK_ACCOUNT` | `source_bank_account_id` | | [`GET /vendors`]() | `id` | `vendor_id` | | [`GET /vendors/{id}/contacts`]() | `id` | `vendor_contact_id` | | [`GET /vendors/{id}/accounts`]() | `id` for ACH, wire, SWIFT, and stablecoin payments | `vendor_account_id` | Pick a payment method below and the builder will assemble the `POST /bills` request for it. For the full implementation path, including attachments and production checks, see the [Bill Payments]() Use case. [GET /vendors]() [GET /vendors/{id}/contacts]() [GET /entities]() [GET /bank-accounts]() [GET /vendors/{id}/accounts]() ```json { "vendor_id": "", "vendor_contact_id": "", "entity_id": "", "invoice_number": "INV-001", "invoice_currency": "USD", "issued_at": "", "due_at": "", "payment_method": "ACH", "payment_details": { "payment_arrival_date": "", "source_bank_account_id": "", "vendor_account_id": "" } } ``` ### 3-way match A bill can be verified against an upstream purchase order and item receipt — matching `purchase_order_line_item_id` values identify the related lines. Compare quantities, amounts, and receipts as well before treating the bill as a verified match. See [Bill Payments]() for the procedure and [Procurement]() for the upstream of how POs come to exist. ### Vendors A **Vendor** is the bill-pay payee — the entity you pay. Vendors carry contacts (email, phone, address) and payment accounts such as bank accounts or crypto wallets. Check payments use a mailing address. Each business maintains its own vendor list. Key fields: - `vendor_contact_id` — the vendor contact selected on a bill. - `vendor_account_id` — the vendor payment account selected in a bill's payment details. - `accounting_vendor_remote_id` — links the vendor to the ERP coding value used at GL export. | Method | Endpoint | Purpose | | --- | --- | --- | | GET | `/developer/v1/vendors` | List vendors. | | GET | `/developer/v1/vendors/{id}` | Get a vendor. | | GET | `/developer/v1/vendors/{id}/contacts` | Get vendor contacts. | | GET | `/developer/v1/vendors/{id}/accounts` | Get vendor payment accounts. | | PATCH | `/developer/v1/vendors/{vendor_id}` | Update a vendor. | For how Vendors relate to the read-only Merchants on card transactions and the Accounting Vendors used for GL coding, see [Data relationships](). ### API limitations - **Approvals.** The Developer API has no bill-approval endpoint. `POST /bills` creates an approved bill; draft-bill submission enters the configured approval workflow. Ramp MCP supports bill approvals for authorized reviewers. - **Bill payments.** The Payments API (beta) supports retrieving and updating bill-associated payments, but cancellation through it is limited to payments created without a bill. Batch payments — one payment across multiple bills — aren't supported. - **Documents.** Bill and draft-bill attachment endpoints accept invoice PDFs and supported images, including PNG and JPEG. A bill can have only one `INVOICE` attachment; use `FILE` for supporting documents. - **Entity bank accounts.** Not manageable via API. Vendor bank accounts are — see [`/developer/v1/vendors/{id}/accounts`](). - **UCSV.** Bills can't be synced via API with Universal CSV — use the [dashboard export↗](). ## Use cases - [Ramp MCP]() — agents can search, read, and approve bills via MCP, subject to their Ramp permissions and connection access level. - [Bill Payments]() — create approved bills via API and pay vendors end-to-end. - [ERP Integrations]() — sync bills and payments to your accounting system. - [Procurement Integrations with the Blank Canvas API]() — receive intake requests and read POs that downstream bills match against. ## Adjacent products - [Cards]() — pay bills with a Ramp card for cashback. - [Spend Controls]() — the approval policy that gates bills before payment. - [Procurement]() — the purchase order a bill matches against. ## API endpoints - [Bills]() — create, list, fetch, update, and archive bills. Includes nested payment details. - [Payments (beta)]() — dedicated payment operations, including vendor payments without a bill. - [Vendors]() — bill-pay payees, contacts, bank accounts. - [Bank Accounts]() — verified funding sources for bill payment. - [Transfers]() — wire-transfer payment objects, including bill-related transfers. ## Conventions - [Webhooks]() — subscribe to `bills.*` events. - [Pagination]() — paginate `GET /bills`. - [Authorization]() — `bills:read` / `bills:write` scopes.