payment-lookup

Non-Negotiables

• Always search bills first, then enrich with bills get and bills attachments when available.
• Report exactly what the API returns. Don't infer payment state beyond what the status says.
• When checking whether a payment went out, search with --include_paid to include completed bills.
• Pass --agent for machine-readable JSON output on all commands.
• Bill amounts in search results are numeric dollars. Bill amounts in get responses may be in cents (divide by 100 if values look 100x too large). Transaction amounts are formatted strings ("$135.40"). Reimbursement amounts are in dollars.
• If bills get fails on a search-returned ID, fall back to the search results and note the limitation.

Workflow

Step 1: Search for the bill

ramp bills search --query "<vendor or invoice number>" --include_paid --limit 10 --agent

The --query flag matches against payee name, invoice number, and payment ID. Partial matches work (e.g., "UPS" matches "UPS Store").

If too many results, narrow with more specific terms. If zero results, try alternate vendor name spellings.

If next_page_cursor is not null, paginate with --page_cursor:

ramp bills search --query "<vendor>" --include_paid --limit 10 \
  --page_cursor "<cursor>" --agent

Step 2: Drill into details

ramp bills get <bill_id> --agent

This returns full payment detail including status, approval history, and metadata.

Use -n (dry run) to preview the request without sending:

ramp bills get <bill_id> --agent -n

Step 3: Pull the invoice attachment

ramp bills attachments <bill_id> --agent

Returns invoice files associated with the bill for cross-reference.

If get fails on a bill ID, attachments will likely fail too.

Step 4: Present findings

Summarize clearly:

Bill found: DHL
  Invoice #: 24-165-12
  Amount: $1,287.95 USD
  Payment status: [status from API]
  Approval status: [status from API]
  Memo: Business package shipment and insurance