spend-analysis

Non-Negotiables

• Always query both transactions and bills for complete vendor spend. Card charges and bill payments are separate resources — there is no unified spend endpoint.
• Pass --agent for machine-readable JSON output on all commands.
• Handle amount format differences: transactions use strings ("$1,048.25", "-$259.49"), bills use numbers (15000), PO amounts use numbers. Reimbursement amounts are in dollars.
• Paginate until next_page_cursor is null — a single page may not return everything.
• Flag vendor name variants explicitly (e.g., "Delta Air Lines" vs "Delta Airlines") — the API does not normalize.
• Negative transaction amounts are refunds. Include them in totals but call them out.

Workflow

Step 1: Pull card transactions

For each vendor (or all vendors if doing a broad analysis):

ramp transactions list \
  --transactions_to_retrieve all_transactions_across_entire_business \
  --reason_memo_merchant_or_user_name_text_search "<vendor>" \
  --from_date <YYYY-MM-DD> \
  --to_date <YYYY-MM-DD> \
  --include_count \
  --page_size 200 \
  --agent

If next_page_cursor is not null, paginate:

ramp transactions list \
  --transactions_to_retrieve all_transactions_across_entire_business \
  --reason_memo_merchant_or_user_name_text_search "<vendor>" \
  --from_date <YYYY-MM-DD> \
  --to_date <YYYY-MM-DD> \
  --page_size 200 \
  --next_page_cursor "<cursor>" \
  --agent

For broad analysis (all vendors): Omit --reason_memo_merchant_or_user_name_text_search to pull all transactions, then group client-side.

Step 2: Pull bill payments

For a specific vendor:

ramp bills search --query "<vendor>" --include_paid --limit 50 --agent

For broad analysis (all vendors):

ramp bills list --include_paid --limit 50 --agent

Repeat either with --page_cursor if next_page_cursor is not null.

Note: bills search has no date range filter and returns due_date but not payment_date. For date-bounded actual spend, drill into paid bills with ramp bills get <id> --agent to get payment_date, then filter by that. If drilling into every bill is impractical, filter by due_date but label the result as "bills due in period" rather than "spend in period." Bills with payment_status: "OPEN" are unpaid — report them separately as commitments.