Pipedrive's deal pipeline structure is deliberately flexible — every company can define their own stages, and Pipedrive doesn't impose a standard. This is great for customer choice. It's a nightmare for integrations. Most field-sales tools assume a HubSpot-like pipeline with "Qualification → Proposal → Negotiation → Closed Won". Pipedrive lets you have "Lead → Conversation → Demo → Spec → Negotiation → Awaiting Signature → Closed Won", or anything else. When Velocity X pulls deals from Pipedrive, it has no idea which stage is "real sales" and which is "just a lead".
The Stage-Mapping Problem
Here's the classic failure: a field-sales dashboard shows "your territory has 12 active deals". If the tool only understands HubSpot's pipeline, it counts deals in "Proposal" and "Negotiation" stages. But in Pipedrive, those stages might not exist — your company calls them "Quote Sent" and "Awaiting Response". The tool either undercounts (shows 2 deals), overcounts (shows 30, including cold leads), or crashes trying to normalise data it doesn't understand.
Velocity X solves this with an admin-configurable stage-mapping table. After you OAuth into Pipedrive, the onboarding UI reads your actual pipeline definition and asks you to map each Pipedrive stage name to one of Velocity X's 5 internal stages: Lead, Qualified, In Quote, Negotiating, Closed. Once configured, the dashboard treats your custom pipeline as if it's standardised. No more counting ambiguity.
OAuth Flow and API Scopes
Pipedrive's OAuth is straightforward: user authorises, Velocity X exchanges the code for a long-lived token, and stores it encrypted in Supabase. The scopes are granular — we request deals:read, deals:write (to sync back edits from the field), persons:read, and activities:read (webhook ingestion). We don't ask for admin scope; that would be suspicious and unnecessary.
The token refresh is automatic — Pipedrive tokens last 12 months, and we refresh them 10 days before expiry. If a user revokes access in Pipedrive, the next API call fails with 401, and Velocity X prompts them to re-authorise.
Deal Sync and Custom Fields
When a deal syncs from Pipedrive, Velocity X pulls standard fields (name, owner, value, probability, stage) plus any custom fields the company has defined. A custom field like "Hail Damage Type" in Rebuild Relief's Pipedrive syncs into Velocity X's deal record automatically — no manual field mapping needed. On the flip side, when a rep updates a deal in Velocity X's field map, those changes write back to Pipedrive, including custom fields, within 5 seconds.
Custom field conflicts are resolved by last-write-wins timestamp. If a rep sets "Hail Damage Type = Roof" in the field app at 14:30:00 and a sales admin sets it to "Gutter" in Pipedrive at 14:30:01, Pipedrive wins. Both systems sync to UTC, so timestamp collision is rare in practice.
Activity Webhooks and Sync Latency
Pipedrive fires webhooks when a deal changes. Velocity X subscribes to *dealUpdate, personUpdate, and activityAdd events. Each webhook lands in a Supabase Edge Function, which upserts the record into a local deal table and reconciles it with the current field map. End-to-end latency: 2–8 seconds depending on network and function cold-start. Guaranteed at-least-once delivery — we dedupe via event ID.
Admin Configuration: The Stage-Mapping UI
After OAuth, the admin opens /settings/crm/stage-mapping. The UI shows a two-column table: left column lists every stage in their Pipedrive pipeline (e.g. "Initial Contact", "Conversation", "Quote Sent"), right column is a dropdown of Velocity X's 5 internal stages. The admin fills in the dropdowns once, saves, and from then on all deals are normalised automatically. This same pattern works for HubSpot and Attio, just with different source stage names.
Conflict Resolution and Data Integrity
Three scenarios can cause sync conflicts: rep edits deal offline while Pipedrive syncs an update, webhook is delayed and overshoots a newer local edit, or a custom field has different data types between systems. Velocity X handles these by: (1) last-write-wins on timestamp, (2) queuing concurrent edits and applying them sequentially, (3) validating custom field types during OAuth and warning the admin if a mismatch is found. Validation errors (e.g., "your Pipedrive date field can't sync to our number field") block the integration until fixed.
Frequently Asked Questions
Can I change my stage-mapping after I've synced deals?
Yes. Changing the mapping retroactively doesn't resync deals — it just changes how new deals are categorised. Existing deals keep their mapped stage. If you realise your mapping was wrong and want to reclassify historical deals, there's a bulk-reclassify action in the admin panel.
What happens if Pipedrive adds a new stage after I've configured the mapping?
New stages in Pipedrive show a warning in the admin panel ("Unmapped stage detected: X"). The admin maps it to an internal stage, and from that point forward, deals created in that stage are normalised correctly. No downtime, no re-sync.
Does Velocity X sync all historical deals?
On first auth, Velocity X fetches your last 500 open + 100 closed deals. That typically covers 3–6 months of history depending on velocity. If you need older deals, the admin can request a full fetch via the settings panel, which may take 2–3 minutes depending on total deal count.
What if two reps edit the same deal at the same time?
Last-write-wins. If rep A marks a deal as "Won" at 14:30:00.000 and rep B updates the value at 14:30:00.005, the value edit wins and the deal stays in whatever stage B intended. Both reps see the result within a few seconds. In practice this is rare — most teams have clear territory boundaries so two reps don't edit the same deal.
The Bottom Line
Pipedrive's flexibility is a feature, not a bug — but it breaks naive integrations. Velocity X normalises that flexibility via a one-time stage-mapping configuration. Once set, field reps see a clean, standardised pipeline, deals sync bidirectionally with custom field passthrough, and admins never manually reconcile data again. If you're evaluating field-sales tools for a Pipedrive shop, ask: "Do you support stage mapping?" The answer tells you whether you'll actually trust the data in your field app.
For a live walkthrough of the stage-mapping UI and deal sync in action, book a demo. For the bidirectional sync deep-dive, read our post on CRM sync architecture.