Legacy Expense Platform to Ramp Migration

Overview

Treat the migration as a sequence of independently reconciled cohorts, not a bulk import. Map business meaning before identifiers, keep legacy and Ramp authority explicit during coexistence, and retire the old platform only after financial close.

Prerequisites

• Identify the Ramp application, environment, business entities, affected data and workflows, accountable owner, and rollback boundary.
• Read references/official-docs.md and re-check endpoint schemas, scopes, limits, and support status before a live operation.
• Use synthetic fixtures or Ramp sandbox until production access and business effects are explicitly approved.
• Prepare approved secret storage and a sanitized evidence location.

Current Contract

• Ramp users, entities, funds, cards, transactions, bills, reimbursements, vendors, and accounting objects have distinct relationships and endpoint contracts.
• Current virtual-card authority is fund-backed and governed through spend controls; legacy card abstractions should not be mapped one-to-one without review.
• Accounting connections distinguish Ramp identifiers from ERP remote identifiers and require explicit sync receipts.
• Webhook coverage and incremental filters vary by object, so migration reconciliation cannot depend on one universal change feed.

Instructions

1. Inventory legacy tenants/entities, users, roles, cards, limits, policies, vendors, open expenses, bills, reimbursements, receipts, accounting mappings, integrations, and retention duties.

1. Create a signed semantic mapping for each object and state, including unsupported values, money/currency conversion, ownership, destination ID, and disposition.

1. Build sandbox fixtures for normal, boundary, duplicate, missing-owner, invalid-currency, closed-period, and rollback cases; validate against current Ramp schemas.

1. Migrate one entity or department cohort, run parallel read/reconciliation, and hold card or accounting writes until users, controls, balances, and mappings are approved.

1. Cut over with frozen checkpoints and named authority, reconcile open and late-arriving items through financial close, then revoke legacy access under retention policy.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Business and finance owners approve semantic mappings and cutover; security/privacy approve identity and data movement; accounting approves balances, mappings, and final close.

Output

A source inventory, semantic map, cohort plan, exception ledger, ID crosswalk, sandbox proof, parallel-run reconciliation, cutover/rollback record, and retirement evidence.

Error Handling

Examples

Example 1

Migrate one subsidiary's users and recurring software cards into approved Funds while keeping the legacy issuer read-only for late settlement.

Example 2

Move open reimbursements and vendor mappings, reconcile ERP references, and retire the old export only after period close.

Validation

• Every source record has one destination, exception, or approved retirement disposition.
• Identity, entity, currency, amount, and accounting mappings reconcile independently.
• No spend authority or production write is enabled before approval.
• Rollback and coexistence cover late, duplicated, and in-flight records.

Resources

• Official documentation and contract notes
• Re-check the dated contract and current OpenAPI schema before any live request.
• Treat unresolved vendor behavior, authority, or financial state as a stop condition.