ramp-manage-bills

Files (1)

• SKILL.md

SKILL.md (first lines)

# Manage Bills

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

## Non-Negotiables

- **Pass `--rationale` on every command** — it is a required field on these agent-tools (a non-empty string, max 1024 chars). With `--json`, supply it as a `"rationale"` key in the body. Omitting it returns `HTTP 422 (DEVELOPER_INVALID_SCHEMA)`, in both agent and human modes.
- **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 numeric **major currency units**. Format the value for display as returned; never divide it by 100 (e.g., `3500` → `$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 `ramp-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.

```bash
# Search by vendor name, invoice number, or payment ID
ramp bills search --query "Acme Corp" --agent --rationale "Search bills for the user"

# List all bills (no query required)
ramp bills list --agent --limit 20 --rationale "List bills for the user"

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

# Paginate through results
ramp bills search --query "Acme" --page_cursor "{cursor_from_previous_response}" --agent --rationale "Search bills for the user"
```

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, inspect the search row's `is_draft` field and pull comprehensive details with the matching command:

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

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

Use `ramp bills draft` when `is_draft` is `true`; otherwise use `ramp bills get`. Do not assume search results are submitted bills.
If the selected command reports that the bill is in the other lifecycle stage, retry the alternate detail command with the same bill ID. A draft keeps the same ID when it is submitted, so its lifecycle may change after search.

The `get` response includes: amount, currency, vendor info, approval status, payment status, due date, invoice number, line items, accounting field codings, and more. Use this as your primary tool for investigating a bill — it covers status, amount breakdowns, and metadata in a single call.

If the response includes a `bill_url` field, it is a direct link to the bill in the Ramp web app. The URL routes to the correct page based on bill status (drafts, approvals, or paid).

### Step 3: Retrieve bill attachments

The attachments command supports submitted bills only. Route this step from the lifecycle confirmed by the detail command that succeeded, including after a fallback: after `ramp bills get`, use the attachments command; after `ramp bills draft`, hand off through the draft's `bill_url` (or the environment-appropriate bills page when absent) so the user can inspect attachments in Ramp.

```bash
# Get invoice file attachments for a submitted bill
ramp bills attachments --bill_id "{bill_id}" --agent --rationale "Fetch bill attachments"
```

### Step 4: Pending approvals

```bash
# Bills waiting for the current user's approval
ramp bills pending --agent --limit 20 --rationale "Review bills pending approval"

# Paginate through pending bills
ramp bills pending --page_cursor "{cursor}" --agent --rationale "Review bills pending approval"
```

## How to Present Results

### Bill search results

Include the deep link on each row when present:

```
Found 3 bills matching "Acme Corp":

  $3,500.00  Acme Corp       INV-2024-001  Approved   Due 2026-04-15  → <bill_url>
  $1,200.00  Acme Corp       INV-2024-002  Pending    Due 2026-04-30  → <bill_url>
  $  850.00  Acme Corp       INV-2023-012  Paid       Paid 2026-03-01 → <bill_url>
```

### Bill details

When showing bill details, include the deep link if available:

```
Bill: INV-2024-001
Vendor: Acme Corp
Amount: $3,500.00 USD
Status: Approved — awaiting payment
Due: 2026-04-15
Created: 2026-03-20
Memo: Q1 office supplies
Open in Ramp: <bill_url>          ← include only if bill_url is in the response

Line items:
  1. Printer paper (500 reams)     $2,000.00
  2. Toner cartridges (50 units)   $1,500.00
```

### Pending approvals

```
5 bills pending your approval ($12,450.00 total):

  $5,000.00  HighSpot        INV-4401    Due 2026-03-28  → <bill_url>
  $3,200.00  Cometeer        INV-882     Due 2026-04-01  → <bill_url>
  $2,500.00  UPS Store       INV-7722    Due 2026-04-05  → <bill_url>
  $1,200.00  Slack           INV-9001    Due 2026-04-10  → <bill_url>
  $  550.00  Canva           INV-3344    Due 2026-04-12  → <bill_url>
```

From ramp-public/skills, MIT.

More from ramp-public/skills