manage-bills

Manage Bills

Search, inspect, and review vendor bills — submitted, draft, and pending approval — using the ramp CLI.

Non-Negotiables

• Deep links: If the response contains a bill_url field, always include it when presenting bill details — it lets the user click through to the Ramp web app. If the field is absent, direct the user to the Ramp bills page instead. Use the URL matching the active CLI environment: https://app.ramp.com/bills for production or https://demo.ramp.com/bills for sandbox. Run ramp env to check the current environment if unsure.
• Bill amounts are in cents. Divide by 100 for display (e.g., 350000 → $3,500.00).
• Bill IDs are UUIDs. Always confirm the correct bill before acting on it.
• Use --agent for machine-readable JSON output when parsing results programmatically.
• These are read-only commands. For approvals, use approval-dashboard. For write operations on drafts, use draft bill commands when available.
• When the agent cannot complete an action (e.g., editing complex bill fields, approving a bill), hand off to the user via the bill_url deep link (if present) or the Ramp bills page.

Workflow

Step 1: Find bills

Start by searching or listing bills to locate the ones the user needs.

# Search by vendor name, invoice number, or payment ID
ramp bills search --query "Acme Corp" --agent

# List all bills (no query required)
ramp bills list --agent --limit 20

# Paid bills are included by default; pass --no-include_paid to exclude them
ramp bills search --query "UPS" --agent

# Paginate through results
ramp bills search --query "Acme" --page_cursor "{cursor_from_previous_response}" --agent

If the response includes a bill_url field on each bill, present it alongside the bill summary.

Step 2: Get bill details

Once you have a bill ID, pull comprehensive details:

# Full bill details (submitted bills only)
ramp bills get --bill_id "{bill_id}" --agent

# Draft bill details (not yet submitted)
ramp bills draft --bill_id "{bill_id}" --agent