> ## Documentation Index > Fetch the complete documentation index at: https://docs.vantage.sh/llms.txt > Use this file to discover all available pages before exploring further. # Ramp > Sync Ramp merchant and card transaction data into Vantage as Custom Providers. Vantage integrates with [Ramp](https://ramp.com/) to bring corporate card costs into Vantage alongside your cloud, SaaS, and AI costs. Once connected, you choose which Ramp merchants Vantage should track. Each selected merchant becomes its own [Custom Provider](/connecting_custom_providers), and Vantage syncs that merchant's settled card transactions daily. With Ramp connected, every Vantage feature that works on provider costs, including [Cost Reports](/cost_reports), [Virtual Tags](/tagging), [Budgets](/budgets), [Cost Alerts](/cost_alerts), [Anomaly Alerts](/cost_anomaly_alerts), [Canvas](/canvas), and the [FinOps Agent](/vantage_finops_agent), works on Ramp costs too. ## How It Works Vantage connects to the Ramp Developer API with a Client ID and Client Secret, lists the merchants in your Ramp account, and lets you pick which merchants to connect. For each merchant you select, Vantage creates a Custom Provider named after the merchant and imports that merchant's card transactions. ```mermaid theme={null} flowchart LR Ramp[Ramp API] --> Merchants["Selected merchants"] Ramp --> Transactions["Settled card transactions"] Merchants --> Providers["Custom Providers"] Transactions --> Providers Providers --> Reports["Cost Reports"] Providers --> Tags["Virtual Tags and Budgets"] Providers --> Agent["Canvas and FinOps Agent"] ``` Vantage aggregates each merchant's settled transactions into one cost row per day, Ramp category, and currency. The table below shows how Ramp transaction data appears in Vantage. | Vantage dimension | Ramp source | Example | | - | - | - | | Provider | One Custom Provider per connected merchant, keyed as `custom_provider:` | `Acme Inc.` | | Account | Ramp merchant ID | `6a1f...` | | Service | Ramp merchant name | `Acme Inc.` | | Category | Ramp [cost category](https://support.ramp.com/setting-up-category-and-merchant-restrictions) | `SaaS / Software` | | Charge Type | Always `Usage` | `Usage` | | Cost | Sum of settled transaction amounts for the day | `$240.00` | | Usage | Number of settled transactions for the day, in the `Transactions` unit | `3` | | Currency | Transaction currency as recorded by Ramp | `USD` | Ramp merchant costs do not include tags, regions, resources, or subcategories. To allocate Ramp costs to teams, products, or cost centers, use [Virtual Tags](/tagging) as shown in the [Example Workflows](#example-workflows) below. > [!NOTE] > > Vantage imports only settled transactions. Pending transactions are excluded until they settle, declined transactions are never imported, and refunds appear as negative costs on the day they settled. Totals in Vantage can therefore differ slightly from the live transaction feed in Ramp. ## Connect Ramp ### Prerequisites Before you connect Ramp to Vantage, make sure you have: * A Vantage role that can manage integrations, such as **Organization Owner** or **Integration Owner**. See [Role-Based Access Control](/rbac). * Admin access to your Ramp account so you can create a Ramp Developer API app. * A Ramp Developer API app with the **Client Credentials** grant type and the `merchants:read` and `transactions:read` scopes. > [!NOTE] > > If your organization restricts access to the provider by IP address, add the following Vantage IP addresses to your provider's allowlist: > > ### Create a Ramp Developer App Vantage authenticates with Ramp using the OAuth 2.0 Client Credentials flow. Create a dedicated app in Ramp so that you can rotate or revoke Vantage's access independently of other integrations. See Ramp's [Quickstart](https://docs.ramp.com/developer-api/v1/getting-started) and [Authorization](https://docs.ramp.com/developer-api/v1/authorization) guides for details. **1. Open the Ramp Developer console** In Ramp, navigate to **Company > Developer**. You need Ramp admin access to see this page. **2. Create an app** Click **Create New App**, give it a descriptive name such as `Vantage`, and accept the terms. **3. Add the Client Credentials grant type** Under **Grant types**, click **Add new grant type** and select **Client Credentials**. Vantage does not use the Authorization Code flow, so no redirect URI is required. **4. Configure scopes** Under **Scopes**, click **Configure allowed scopes** and select both `merchants:read` and `transactions:read`. Vantage uses `merchants:read` to list the merchants you can sync and `transactions:read` to import card transactions. No write scopes are required. **5. Copy the credentials** Copy the app's **Client ID** and **Client Secret** and store them securely until you paste them into Vantage. > [!WARNING] > > Store your Ramp Client Secret securely. Do not paste it into Canvas, the FinOps Agent, Slack, or any client-side application. If a secret is exposed, rotate it in Ramp and update the credentials in Vantage as described in [Rotate Ramp Credentials](#rotate-ramp-credentials). ### Create the Connection **1. Open the Ramp integration** In Vantage, navigate to [Settings > Ramp](https://console.vantage.sh/settings/ramp). You can also open **Settings**, select **Integrations**, and choose **Ramp** from the Additional Integrations section. **2. Enter connection details** Paste the **Client ID** and **Client Secret** from your Ramp Developer app. **3. Connect the account** Click **Connect**. Vantage validates the credentials by requesting an access token from Ramp and reading a page of recent transactions. If the app is missing the Client Credentials grant type or either scope, Vantage shows an authorization error and does not save the connection. **4. Select merchants** After the connection is saved, Vantage opens the merchant selection screen. See [Select Merchants](#select-merchants) below to choose which merchants to connect. > [!NOTE] > > Each Vantage account supports one Ramp connection. If you need to switch to a different Ramp Developer app, update the credentials on the existing connection rather than creating a second one. ## Select Merchants The Ramp connection does not import any costs until you select at least one merchant. Each merchant you connect becomes its own Custom Provider in Vantage, so choose the vendors you want to track and leave out one-off or personal expenses you do not need in cost reporting. **1. Open the All Ramp Merchants tab** On the Ramp connection page, the **Merchants** section has two tabs. * **Connected** lists merchants Vantage already tracks. * **All Ramp Merchants** lists the remaining merchants from your Ramp account, with their Ramp **Category**. **2. Find merchants** Use the **Search merchants by name** field to narrow the list. On the All Ramp Merchants tab, Ramp matches the start of the merchant name and the match is case-sensitive, so search for `Acme` rather than `acme` or `me`. **3. Select the merchants to connect** Select the checkbox next to each merchant you want to track. Merchants whose status is **Available** can be connected. Merchants marked **Overlaps native** are disabled because you already have a native Vantage integration for that provider. See [Native Provider Overlap](#native-provider-overlap) below. **4. Click Connect merchants** As you select merchants, the table header shows how many are selected and a **Connect N merchants** button. Click it. Vantage creates a Custom Provider for each selected merchant and immediately starts importing its transactions for the current month and the previous six months. A confirmation message reports how many merchants were connected or skipped. **5. Confirm workspace access** If your account has exactly one workspace, new merchants are added to it automatically. If you have several workspaces, assign each new merchant: 1. On the **Connected** tab, click the merchant name to open its Custom Provider page. 2. In the **Workspace Access** section, select the workspaces where that merchant's costs should appear. A merchant's costs show up only in the workspaces it is assigned to. See [Manage Workspace Provider Integrations](/workspaces#manage-workspace-provider-integrations) for how workspace assignment controls cost visibility. > [!TIP] > > Start with the merchants that make up most of your recurring costs, such as developer tooling, observability, design, and communication vendors. You can return to the Ramp page at any time to add more merchants or remove ones you no longer need. ### Native Provider Overlap If you already have a native Vantage integration connected for a provider, Vantage prevents you from also connecting that provider's Ramp merchant. For example, if AWS is connected to Vantage, the `Amazon Web Services` merchant in Ramp is marked **Overlaps native** and cannot be selected. This keeps the same costs from being counted twice under two providers. Keep the native integration in these cases. Native integrations give you resource-level detail, tags, usage, and daily granularity that card transactions cannot provide. Ramp data is the right fit for vendors Vantage does not integrate with natively. Overlap detection is based on a curated list of merchant names that map to Vantage providers, including AWS, Microsoft Azure, Google Cloud, Snowflake, Databricks, MongoDB Atlas, Datadog, OpenAI, Anthropic, GitHub, Vercel, Cloudflare, and others. If you connect a native integration after connecting the same vendor from Ramp, disconnect the Ramp merchant to avoid double counting. ## Manage Connected Merchants ### Add Merchants **1. Open the Ramp connection** Navigate to [Settings > Ramp](https://console.vantage.sh/settings/ramp) and select the connection. **2. Select merchants on the All Ramp Merchants tab** Select the checkbox next to each merchant you want to add. **3. Click Connect merchants** Vantage creates a Custom Provider for each selected merchant and starts its imports. ### Remove Merchants **1. Open the Ramp connection** Navigate to [Settings > Ramp](https://console.vantage.sh/settings/ramp) and select the connection. **2. Select merchants on the Connected tab** Select the checkbox next to each merchant you want to remove. **3. Click Disconnect merchants** The selected merchants are disconnected, and their Custom Providers and imported costs are removed from Vantage. > [!WARNING] > > Disconnecting a merchant deletes its Custom Provider and all of its imported costs. Any Cost Reports, Saved Filters, or Virtual Tag rules that reference that provider will no longer match it. Reconnecting the merchant later creates a new Custom Provider with a new token and re-imports the current month and the previous six months. ### Work with Ramp-Managed Custom Providers Connected merchants appear in the [Custom Providers](https://console.vantage.sh/settings/custom_providers) list next to any Custom Providers you created manually, with a **Managed by Ramp** badge. On a Ramp-managed Custom Provider page, you can: * Edit the **Name** and **Description**. Renaming is useful when Ramp's merchant name is not the vendor name your team recognizes, for example renaming `ACME INC *SUBSCRIPTION` to `Acme Inc.`. * Upload an icon so the vendor is easy to recognize in reports and filters. See [Set a Custom Provider Icon](/connecting_custom_providers#set-a-custom-provider-icon). * Assign workspaces in the **Workspace Access** section. * Review the monthly import history in the **Imports** section. You cannot upload CSV files to or delete a Ramp-managed Custom Provider, in the console or through the API. Ramp owns the cost data for these providers. To remove one, disconnect the merchant from the **Connected** tab on the Ramp page. See [Remove Merchants](#remove-merchants). ### Rotate Ramp Credentials If you rotate the Client Secret in Ramp, or move Vantage to a new Ramp Developer app, update the stored credentials without disconnecting any merchants. **1. Open the Ramp connection** Navigate to [Settings > Ramp](https://console.vantage.sh/settings/ramp) and select the connection. **2. Enter the new credentials** In the **Update Ramp Account** section, paste the new **Client ID** and **Client Secret**. **3. Click Update Credentials** Vantage validates the new credentials against Ramp before saving them. All connected merchants continue importing with the new credentials. ### Disconnect Ramp To remove the Ramp integration entirely, navigate to [Settings > Ramp](https://console.vantage.sh/settings/ramp), open the dropdown menu next to the connection, and click **Remove**. Removing the connection deletes every Ramp-managed Custom Provider and its imported costs. If you only want to stop tracking some vendors, remove individual merchants instead. ## Data Refresh | Event | Behavior | | - | - | | Merchant connected | Vantage imports the current month and the previous six months of settled transactions for that merchant. | | Daily sync | Once per day, after the UTC day closes, Vantage re-imports the current month and the previous six months for each connected merchant. Late-settling transactions and refunds anywhere in that window are picked up on the next sync. New transactions from the prior day appear in Vantage the following day. | | No new transactions | If a merchant has no settled transactions in a month, that month shows no costs. Previously imported months are not affected. | See [Provider Data Refresh](/provider_data_refresh) for how other native Vantage integrations refresh. ## Example Workflows The examples below assume you have connected Ramp and a handful of merchants. Replace the provider, report, and tag names with the names in your account. Where a workflow references a provider token, you can find it on the Custom Provider page as the **Provider ID**, for example `custom_provider:accss_crdntl_123a45bfdaf38765`. ### Track All SaaS Costs in One Cost Report Use this when you want a single report of the vendors you pay for by card, separate from infrastructure costs. **1. Create a Cost Report** Create a new [Cost Report](/cost_reports) and name it `SaaS Vendors`. **2. Filter to Ramp merchants** Under **Filters**, select **Provider** and check each Ramp-managed Custom Provider. Alternatively, switch to [VQL](/vql) and list the provider tokens directly. ```sql theme={null} costs.provider IN ('custom_provider:accss_crdntl_123a45bfdaf38765', 'custom_provider:accss_crdntl_7c2e91f04ab6d3e8', 'custom_provider:accss_crdntl_0f8b3d6e2a91c457') ``` **3. Group by Provider** Set **Group By** to **Provider** to see costs per vendor over time. Save the report and optionally share it with finance through a [Report Notification](/report_notifications). Expected output: one line per vendor, showing monthly card costs for each. New merchants you sync from Ramp need to be added to the filter unless you use a Saved Filter that you update in one place. > [!TIP] > > Create a [Saved Filter](/saved_filters) named `Ramp Vendors` with the same provider list. Reuse it across Cost Reports, Budgets, and Cost Alerts so you only need to update one filter when you sync a new merchant. ### See True Cost of Goods Sold Use this when your product runs on a mix of native cloud providers and card-paid vendors, and you want a complete COGS number. **1. Start from your infrastructure report** Open a Cost Report you already use for COGS, for example one filtered to your production AWS accounts and your OpenAI integration. **2. Add the Ramp vendors that serve production** Add the Ramp-managed Custom Providers that are part of delivering your product. Leave out internal tools like design or HR software. **3. Group by Provider** Group by **Provider** to see how card-paid vendors compare with cloud costs. Pair the report with a [Business Metric](/business_metrics) such as active customers to calculate cost per customer across every provider. Expected output: a COGS report where cloud providers and Ramp vendors appear side by side, with unit costs that reflect your full infrastructure bill rather than only the providers with billing APIs. ### Analyze Costs by Ramp Category Use this when you want to understand what kinds of vendors you pay for rather than which specific vendors. Ramp assigns each merchant a [cost category](https://support.ramp.com/setting-up-category-and-merchant-restrictions), such as `SaaS / Software`, `Advertising`, or `Cloud Computing`. Vantage stores this as the **Category** dimension on each Ramp cost row. **1. Open your SaaS Vendors report** Open the report from the first example, or any report filtered to Ramp merchants. **2. Group by Category** Set **Group By** to **Category**. Each line now represents a Ramp cost category across all connected merchants. **3. Drill into a category** Add a **Category** filter for `SaaS / Software` and change the grouping back to **Provider** to see which software vendors make up that category. Expected output: costs by vendor category, which is useful for board reporting, annual planning, and comparing software costs against headcount. ### Allocate Vendor Costs to Teams with Virtual Tags Use this when finance needs card costs attributed to cost centers, and Ramp merchants do not carry tags. **1. Create a Virtual Tag** Navigate to **Settings > Tags**, select the **Virtual Tags** tab, and create a tag with the key `Cost Center`. See [Create Virtual Tags](/tagging#create-virtual-tags). **2. Add a value per team** Add one value per team, then filter that value to the Ramp merchants the team owns. For example, `Engineering` includes Linear, PagerDuty, and Postmark, `Design` includes Figma, and `Marketing` includes HubSpot. Select those Custom Providers in the filter, or match them in [VQL](/vql) with each merchant's **Provider ID** from its Custom Provider page. **3. Include your cloud providers in the same tag** Add rules for native providers so that one tag covers everything. For example, `costs.provider = 'aws' AND costs.account_id = '111111111111'` can also map to `Engineering`. **4. Report by Cost Center** Group any Cost Report by the `Cost Center` virtual tag, or create a [Segment](/segments) per team so each team sees its own cloud and vendor costs in one place. Expected output: a single `Cost Center` dimension that spans AWS accounts, native SaaS integrations, and Ramp card costs. Vendors that are shared across teams can be split with a [cost-based allocation](/tagging#cost-allocation-tags) rule instead of a fixed mapping. ### Catch Subscription Creep with Usage Use this when you suspect seats, add-ons, or duplicate subscriptions are growing quietly. Every Ramp cost row includes a usage value equal to the number of settled transactions, in the `Transactions` unit. A vendor that is charged once per month should show one transaction per month. More than that often means multiple cards, multiple seats billed separately, or duplicate subscriptions. **1. Open your SaaS Vendors report** Group by **Provider** and set the date range to the last six months. **2. Switch the Y-axis to Usage** Change the Y-axis from **Cost** to **Usage** to chart the number of transactions per vendor per month. See [Usage-Based Reporting](/usage_based_reporting). **3. Investigate vendors with rising transaction counts** Vendors whose transaction count climbs month over month are candidates for consolidation. Open the vendor in Ramp to see which cardholders made the charges. Expected output: transaction counts per vendor over time. Use the result to consolidate seats under one plan or to cancel subscriptions no one is using. ### Set Guardrails on Vendor Costs Use this when you want to be notified about vendor costs without checking reports manually. * **Budget**: Create a [Budget](/budgets) on your `SaaS Vendors` Cost Report with a monthly amount. Budget alerts notify you when forecasted costs exceed the plan. * **Cost Alert**: Create a [Cost Alert](/cost_alerts) on the same report, grouped by **Provider**, that fires when any vendor increases more than 25% month over month. This catches annual renewals that were billed at a higher tier and plan upgrades made by individual cardholders. * **Anomaly Alert**: Enable [Anomaly Alerts](/cost_anomaly_alerts) on the report to catch unexpected one-day spikes, such as a vendor charging twice or a usage-based tool exceeding its normal range. * **Report Notification**: Send a weekly [Report Notification](/report_notifications) to a Slack channel so finance and engineering leads see vendor cost trends without logging in. Expected output: notifications in Slack, Microsoft Teams, or email when vendor costs deviate from plan, with links back to the report for investigation. ### Compare Ramp Vendors with Cloud and AI Costs Use this when you want card-paid vendors and your largest providers in one table, so leadership sees the full picture in one place. Show last month's costs versus the month before for my cloud, AI, and SaaS providers alongside each Ramp card vendor. Include the month-over-month change, the trailing six-month total, and each row's share of total costs. Expected output: one row per provider and Ramp vendor with last month's costs, the prior month's costs, the change, the six-month total, and each row's share of total costs. Card vendors usually sort below cloud and AI providers, which makes fast-growing vendors easy to spot. ![Canvas table comparing cloud, AI, and SaaS provider costs with Ramp card vendors month over month](https://assets.vantage.sh/docs/ramp-canvas-total-costs.png) ### Review Vendors for Consolidation and Renewals Use this before a budgeting cycle or a contract renewal. Using my "SaaS Vendors" Cost Report, rank each provider by costs over the last 6 months. Include total costs, average monthly costs, month-over-month growth for the most recent month, and the number of transactions. Flag any providers that look like duplicates or that overlap with a native integration I already have connected. Expected output: a ranked vendor table with growth and transaction counts. Use it to decide which contracts to renegotiate first, then add an [Annotation](/annotations) to the report on each renewal date so the next price change is easy to explain. ### Forecast Vendor Costs for Planning Use this when finance needs a forward-looking view of card costs by category. Using my "SaaS Vendors" Cost Report, show monthly costs by Category for the last 6 months and forecast the next 6 months. Call out the fastest-growing category and the three providers driving its growth. Expected output: a category-level forecast you can paste into a planning document. Vantage [forecasting](/forecasting) is also available directly on the Cost Report. ## Ask the FinOps Agent You can also ask the [FinOps Agent](/vantage_finops_agent) one-off questions about Ramp costs in the Vantage console. Name the relevant Cost Report, provider, or virtual tag so the agent can scope the analysis. Try prompts like: * `Which Ramp vendors grew the most month over month, and what was each one's total last month?` * `Show total costs by Cost Center for last quarter, including both AWS and my Ramp vendors.` * `Which vendors in my SaaS Vendors report had more than one transaction last month?` * `Compare costs in the SaaS / Software category this quarter to the same quarter last year.` * `Create a Cost Report with all of my Ramp vendors grouped by provider and set a $20,000 monthly budget on it.` ## Related Ramp Documentation The Vantage integration uses these Ramp concepts and APIs: * [Quickstart: create a developer app](https://docs.ramp.com/developer-api/v1/getting-started) * [Authorization and grant types](https://docs.ramp.com/developer-api/v1/authorization) * [Client Credentials flow](https://docs.ramp.com/developer-api/v1/authorization/client-credentials) * [Scopes](https://docs.ramp.com/developer-api/v1/authorization/scopes) * [Token endpoint](https://docs.ramp.com/developer-api/v1/api/authorization) * [Merchants endpoint](https://docs.ramp.com/developer-api/v1/api/merchants) * [Transactions endpoint](https://docs.ramp.com/developer-api/v1/api/transactions) ## Troubleshooting > **I do not see Ramp on the Integrations page** > > Confirm that your Vantage user has permission to manage integrations. You need a role such as **Organization Owner** or **Integration Owner**. Ramp appears in the **Additional Integrations** section of the Integrations page, not in the main provider section. > **The Client ID and Client Secret are rejected** > > Vantage shows `Authorization error: check the Client ID and Client Secret, and that the app allows merchants:read and transactions:read.` when Ramp refuses the credentials. > > In the Ramp Developer console, confirm that the app has the **Client Credentials** grant type enabled and that both `merchants:read` and `transactions:read` are in its allowed scopes. Scopes that are not allowed on the app cannot be requested by Vantage even if the credentials are correct. Also confirm that you copied the secret from the same app as the Client ID. > **A merchant does not appear on the All Ramp Merchants tab** > > The All Ramp Merchants list shows 15 merchants at a time. Use **Next** to page through, or search for the merchant. Search on this tab matches the beginning of the merchant name and is case-sensitive, so `Acme` matches but `acme` and `me` do not. If nothing matches, the tab shows `No search results for "..."`. > > Merchants that are already on the **Connected** tab do not appear under All Ramp Merchants. The list comes directly from Ramp, so a vendor that does not yet exist as a merchant in your Ramp account is not listed. > **A merchant is marked Overlaps native and cannot be selected** > > This is expected. You already have a native Vantage integration for that provider, so syncing it from Ramp would count the same costs twice. Keep the native integration, which provides more detail than card transactions. See [Native Provider Overlap](#native-provider-overlap). > **Merchant costs do not appear in Cost Reports** > > Check the following, in order: > > 1. **Workspace access:** Open the merchant's Custom Provider page and confirm it is assigned to the workspace you are viewing. Accounts with more than one workspace must assign new merchants manually. > 2. **Import status:** The Imports section of the Custom Provider page shows each month's import. A first import can take some time, especially for merchants with many transactions. > 3. **Settled transactions:** Only settled transactions are imported. A merchant with only pending transactions shows no costs until they settle. > 4. **Report filters:** Confirm the report's provider filter or Saved Filter includes the new Custom Provider. > **Totals in Vantage differ from Ramp** > > Vantage imports settled transactions only, dated by the time of the transaction in UTC. Ramp's dashboard may show pending transactions, use your local time zone, or present amounts in your home currency. Refunds appear in Vantage as negative costs on the day they settled. Transactions in a non-USD currency are stored in their original currency; see [Currency Conversion](/vantage_account#currency-conversion) to report them in a single currency. > > Late-settling transactions and refunds in the current month and the previous six months are picked up by the daily sync. Older months are not re-imported. > **I cannot upload a CSV to or delete a Ramp merchant Custom Provider** > > This is expected. Custom Providers with the **Managed by Ramp** badge receive their costs from Ramp, so CSV upload and deletion are disabled in the console and the API returns an error for those operations. To remove the provider, select the merchant on the **Connected** tab of the Ramp page and click **Disconnect merchants**. To add costs that Ramp does not have, create a separate manual Custom Provider. > **The sync stopped and imports show an authorization error** > > The import log shows `Ramp rejected the stored Client ID and Client Secret. Update them in Settings → Ramp.` when Ramp stops accepting the stored credentials, for example after the secret was rotated or the app was deleted in Ramp. > > Create or rotate the credentials in the Ramp Developer console, then update them in the **Update Ramp Account** section of the Ramp connection page. Imports resume on the next daily sync. > **Ramp is not listed with cost provider integrations** > > This is expected. Ramp is a connection that creates Custom Providers for the merchants you select. The Custom Providers themselves appear in the **Provider** filter of Cost Reports, in the Custom Providers list, and in VQL as `custom_provider:`. There is no `ramp` provider value. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.