> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/ramp.md). # Ramp Connect Ramp to sync your team roster and card spend per vendor, surfacing software paid by card as contracts in Harmony Ramp is a corporate card and spend management platform. Connecting Ramp to Harmony turns your card spend into vendor contracts: every merchant your team pays by card appears in the Contracts page with its trailing twelve months of charges, its billing cadence where Ramp knows it, and the people who pay for it. Software that no one told IT about becomes visible the moment a card is charged for it. #### What the Ramp integration enables | Capability | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Card spend as contracts | One contract per vendor (Ramp merchant), built from the last twelve months of card charges, refreshed daily | | Shadow-software discovery | A vendor that matches Harmony's application catalog is surfaced as a discovered application, even with no other integration reporting it | | Billing cadence and renewals | Where Ramp records a vendor's billing frequency, or a card is locked to that vendor, the contract carries its billing cycle, per-cycle amount and next renewal date | | Team roster | Your Ramp users with role and status, refreshed every 6 hours, for access reviews | | Who pays | Each charge names the card holder, and the most frequent card holder becomes the contract's billing contact | *** #### Prerequisites 1. **A Ramp account** with a user who can create developer apps. Ramp requires Admin access for this; Owner and Admin roles qualify. 2. **A Harmony account** with admin privileges. *** #### Connect Ramp to Harmony **Step 1: Create a developer app in Ramp** 1. Log in to Ramp and go to **Company** > **Developer** 2. Click **Create new app** (or **Start building** if this is your first app) 3. Name the app, for example `Harmony`, and accept the Terms 4. Under **Grant types**, click **Add new grant type** and select **Client Credentials** 5. Under **Scopes**, click **Configure allowed scopes** and enable all five of: * `business:read` * `users:read` * `transactions:read` * `vendors:read` * `funds:read` 6. Copy the **Client ID** and **Client Secret**. The secret is shown once; if you lose it, rotate it in Ramp and reconnect. {% hint style="warning" %} All five scopes are required. Harmony checks every one of them when you save the connection and rejects the save if any is missing, so you cannot end up with a connection that silently syncs partial data. {% endhint %} **Step 2: Connect in Harmony** 1. Log in to your Harmony dashboard 2. Navigate to **Settings** > **Integrations** 3. Find **Ramp** under **SaaS Procurement** and click **Connect** 4. Paste the **Client ID** and **Client Secret** 5. Leave **Environment** on **Production** unless the app was created in a Ramp sandbox business 6. Click **Save** Harmony validates the credentials immediately by requesting a token from Ramp and reading your business, users, transactions, vendors and funds. A wrong secret, a disabled grant type or a missing scope fails the save with a message naming the fix. {% hint style="info" %} You can reach this page from the integration itself: **Settings** > **Integrations** > **Ramp** links to this guide. {% endhint %} *** #### Disconnect Ramp from Harmony 1. Navigate to **Settings** > **Integrations** 2. Find **Ramp** under **SaaS Procurement** and click the integration card 3. Click **Disconnect** and confirm Harmony stops syncing from Ramp. Contracts and users already synced remain in Harmony. Rotating or deleting the developer app in Ramp has the same effect: the next sync fails and stays disabled until you reconnect with new credentials. *** #### What Harmony syncs from Ramp | Data | Description | Refresh | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | Users | Name, email, Ramp role, status (active, pending invite, inactive, suspended), department, location and employee ID | Every 6 hours | | Card charges per vendor | The last twelve months of settled card transactions, grouped by Ramp merchant into one contract per vendor, with each charge as a line item: amount, currency, date, state, Ramp category and card holder | Daily | | Billing cadence | The vendor's billing frequency as recorded in Ramp's vendor list, or the interval of a card locked to that single vendor | With charges | | Vendor spend totals | Ramp's own trailing-year spend per vendor, kept alongside Harmony's figure for cross-checking | With charges | **How the contract value is computed.** A contract's value is the net of its charges in the window; refunds subtract. When Ramp gives a billing cadence, the value is the amount per billing cycle (the window total spread over the cycles that carried a charge) and the renewal date is one cycle after the latest charge. When no cadence is known, the value is the twelve-month total with no billing cycle, which Harmony reads as an annual figure, so the monthly average is still correct for monthly and annual vendors alike. **What is deliberately not synced** * Bills, reimbursements, receipts and accounting codings * Card numbers or any card credential. Harmony never requests Ramp's card vault scope * Sign-in or activity events. Ramp exposes no login signal for its users * License or seat information. Ramp has no per-user license, so every user shows a license tier of Unknown * Declined transactions, which Ramp excludes by default **Limits worth knowing** * For a vendor with more than 300 charges in twelve months, the contract keeps the 300 most recent as line items. The contract value still covers every charge. * Vendor names come from Ramp's normalized merchant names. A charge whose merchant has no name in Ramp is grouped under the statement descriptor instead. * Contracts synced from Ramp are read-only in Harmony; every sync overwrites their fields. *** #### Roles Ramp roles map to Harmony's two access levels as follows. The original Ramp role is kept on each user for access reviews. | Ramp role | Harmony role | | ----------------------------------------------------------------------------------- | ------------ | | Business Owner, Business Admin, IT Admin | Admin | | Bookkeeper (Accounting), Auditor (View-Only Admin), Employee (Business User), Guest | Member | The Manager add-on does not change the Harmony role; it is recorded as an attribute. *** #### Permissions explained | Scope | What Harmony reads with it | | ------------------- | ------------------------------------------------------------------------------------------ | | `business:read` | Your business ID and name, used to tie every synced record to your Ramp account | | `users:read` | The user roster, and the card holder's email for each charge | | `transactions:read` | Settled card transactions for the last twelve months | | `vendors:read` | The vendor list: which merchant each vendor is, its billing frequency and trailing spend | | `funds:read` | Card spend limits and the vendors they are locked to, used only to infer a billing cadence | All scopes are read-only. Harmony never creates, edits or deletes anything in Ramp. *** #### Use cases * **Find software bought on a card.** A SaaS tool charged monthly to an employee's Ramp card shows up as a contract, and if it matches the catalog, as a discovered application, without anyone filing a request. * **Prepare for renewals.** Vendors with a known billing cadence get a renewal date, so annual subscriptions surface in the renewal view before they auto-renew. * **Reconcile with procurement.** Compare Ramp card spend against NetSuite or ZipHQ contracts for the same vendor to spot tools paid twice or outside policy. * **Review access.** The roster with Ramp roles feeds Harmony's access reviews, so Owners, Admins and IT Admins on your Ramp account are visible alongside every other system. *** #### Troubleshooting **"Ramp rejected these credentials"** The Client ID or Client Secret is wrong, or the **Client Credentials** grant type is not enabled on the app. Check both under **Company** > **Developer** in Ramp. If you rotated the secret, paste the new one. **"The Ramp app is missing a required scope"** One of the five scopes is not enabled on the app. Enable it under **Configure allowed scopes** and save again. Harmony names the full list in the message. **"Could not reach Ramp"** A transient network error. Retry in a moment. **The connection worked, then syncing stopped** A scope was removed from the app, or the secret was rotated. Harmony disables a connection that Ramp rejects. Fix the app in Ramp and re-save the connection in Harmony to resume. **A vendor has no billing cycle** Ramp has no billing frequency for that vendor and no card locked to it. Set the billing frequency on the vendor in Ramp's vendor list; the next daily sync picks it up. The contract still carries the full twelve-month spend meanwhile. **Two contracts for one vendor** Ramp's merchant normalization sometimes splits a vendor across two merchant records. Harmony groups by Ramp's merchant, so it mirrors that split. Correcting the merchant on the transactions in Ramp merges them on the next sync. **Sandbox connection returns no data** A Ramp sandbox business starts empty. Use Ramp's demo actions to add transactions, and make sure the connection's **Environment** is set to **Sandbox**. *** #### Data & privacy * Harmony stores the Client ID and Client Secret encrypted and uses them only to request short-lived access tokens from Ramp. Tokens are not persisted. * Access is read-only. None of the requested scopes allows Harmony to change anything in Ramp. * Harmony does not request the card vault scope and never receives card numbers. * Charges are stored with amount, currency, date, Ramp category, merchant and card holder. Receipts, memos and accounting details are not fetched. * Disconnecting stops all synchronization immediately. Data already synced remains in Harmony until removed. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.harmony.io/integrations/saas-applications/ramp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.