Ramp Card Management

Card Management

Non-Negotiables

• Use ListCards to inspect cards. Do not substitute a funds/spend-allocation listing: funds and cards are different entities.
• A card whose underlying lifecycle state is ACTIVE can still be locked and unable to spend. Never report spendability from lifecycle state alone.
• Treat is_spendable, active_locks, and blocking_task_count as the live effective status. Follow each lock's remediation_action; an overdue-task sanction routes to ramp-complete-tasks rather than repeated manual unlock.
• Pass --agent for machine-readable JSON output whenever you need to count or inspect returned fields programmatically.
• Report the fields returned by the API. Do not invent card lifecycle states.
• After every activation or unlock attempt, call ListCards again for the same cardholder and exact card UUID. Do not claim success until the postcondition reports is_spendable: true.

Workflow

Step 1: Inspect card status

MCP:

ListCards(rationale="Inspect the user's card and effective lock status")

CLI:

ramp cards list --rationale "Inspect the user's card and effective lock status" --agent

In --agent mode the response is wrapped in the standard envelope. Card records live in the returned cards array.

Admins and managers can inspect a visible employee's cards by passing that cardholder's UUID. Resolve the UUID first, then pass cardholder_user_uuid.

ramp users org-chart --rationale "find the employee's user UUID" --agent
ramp cards list --cardholder_user_uuid "USER_UUID" --rationale "Inspect this employee's card and effective lock status" --agent

Step 2: Interpret effective status

Match the intended card by its id, last_four, display_name, and cardholder. Inspect its effective lock fields before acting:

• is_spendable: false means the card cannot spend even if card_state is ACTIVE or is_locked is false.
• active_locks lists every effective CARD or SPEND_ALLOCATION_MEMBER lock with its lock_source and remediation_action.
• blocking_task_count is the number of outstanding tasks blocking spending.
• GET_ATTENTION_FEED: load ramp-complete-tasks; do not use LockOrUnlockCard to bypass the sanction.
• LOCK_OR_UNLOCK_CARD: continue to the normal lock/unlock flow below.
• UNLOCK_FRAUD_LOCKED_CARD: use the fraud-specific unlock workflow returned by the tool. The existing result is FraudLockDetected.
• CONTACT_RAMP: stop automated unlock attempts and hand the returned lock details to Ramp support.

Step 4: Activate a physical card

First call activation by the physical card's last four digits without --confirm_delivery:

ramp cards activate --last_four 1234 --rationale "activate the user's new physical card" --agent

If the result says delivery confirmation is required, ask the user to confirm that the physical card has arrived. Only after they confirm, retry with --confirm_delivery:

ramp cards activate --last_four 1234 --confirm_delivery --rationale "user confirmed their physical card arrived" --agent

Do not ask about delivery or set --confirm_delivery unless the first call says it is required.

Step 5: Lock or unlock a card

Before locking, inspect and show the user the affected card, explain that locking it will block all transactions until it is unlocked, and ask for explicit confirmation. Run the lock command only after the user confirms. Do not infer confirmation from a report of suspicious activity or a lost card.

Unlocking does not require confirmation.

Before unlocking, re-run ListCards. If any lock's remediation_action is GET_ATTENTION_FEED, stop this manual flow and load ramp-complete-tasks. If is_spendable is already true, report the live state without a redundant write.

Lock or unlock a card by its id. The id is a required positional argument:

ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action lock --rationale "user lost their card" --agent
ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action unlock --rationale "user found their card" --agent

After either write, re-run ListCards for the same cardholder. For unlock, the postcondition passes only when the exact card reports is_spendable: true. A successful unlock response, is_locked: false, or an underlying ACTIVE lifecycle state is not sufficient.

If normal unlock returns CardUnlockBlocked, it is a typed failed precondition, not a partial success. Report its remaining_locks and blocking_task_count; the returned card remains is_locked: true and is_spendable: false. Follow each remaining lock's remediation action instead of retrying the same unlock.

Fields To Inspect

Example Session

User: Why can't I use my card?

Agent: > ramp cards list --rationale "Inspect the user's card and effective lock status" --agent

Agent: This card is locked by an overdue Ramp task. Its underlying lifecycle
state does not make it spendable. I'll load `ramp-complete-tasks`, resolve the
outstanding item with you, and then re-check this exact card before saying it is
unlocked.

Gotchas