Stripe to HubSpot Data Mapping and Deduplication
This document provides an overview of how Omniroo maps data from Stripe to HubSpot and the key fields used for deduplication. Understanding these mappings and deduplication keys is crucial for maintaining data integrity in your HubSpot portal.
Important Deduplication Keys (Do Not Modify Manually)
Omniroo uses specific fields as unique identifiers to prevent duplicate records in HubSpot. It is critical that you do NOT manually modify these fields in HubSpot, as doing so can break the synchronization and lead to duplicate records or incorrect data.
Object-Specific Mappings
1. HubSpot Object: Contact
Stripe customer data is mapped to HubSpot Contacts.
- Stripe Events Processed:
customer.created
,customer.updated
- Stripe Fields Mapped to HubSpot Properties:
data.object.email
→email
data.object.name
→firstname
(first word of name)data.object.name
→lastname
(remaining words of name after the first)data.object.phone
→phone
data.object.address.line1
→address
data.object.address.city
→city
data.object.address.state
→state
data.object.address.postal_code
→zip
data.object.address.country
→hs_country_region_code
- Deduplication Key:
email
(fromdata.object.email
). Do NOT manually modify theemail
property in HubSpot for synced contacts.
2. HubSpot Object: Deal
Stripe subscription data is mapped to HubSpot Deals.
- Stripe Events Processed:
customer.subscription.created
,customer.subscription.updated
,customer.subscription.deleted
- Stripe Fields Mapped to HubSpot Properties:
data.object.id
→dealname
(used as the primary identifier for the deal)- Sum of (
data.object.items.data[*].price.unit_amount
*data.object.items.data[*].quantity
) (sum of all subscription item amounts) →amount
(converted from cents to dollars) data.object.status
anddata.object.items.data[*].price.id
(price IDs of subscription items) →pipeline
anddealstage
(determined by your configured Pipeline Mapping Rules).
- Associations:
- Associated with the relevant HubSpot Contact (found via
customerEmail
). - Associated with HubSpot Line Items (created from
data.object.items.data
).
- Associated with the relevant HubSpot Contact (found via
- Deduplication Key:
dealname
(mapped fromdata.object.id
). Do NOT manually modify thedealname
property in HubSpot for synced deals.- Event Timestamp:
last_processed:subscription:{data.object.id}
- Redis Locks:
lock-{destinationID}:subscription:{data.object.id}
andlock-{destinationID}:email:{customerEmail}
- Event Timestamp:
3. HubSpot Object: Invoice
Stripe invoice data is mapped to HubSpot Invoices.
- Stripe Events Processed:
invoice.created
,invoice.updated
,invoice.paid
,invoice.payment_failed
,invoice.finalized
- Stripe Fields Mapped to HubSpot Properties:
data.object.id
→hs_title
(used as the primary identifier for the invoice)data.object.status
→hs_invoice_status
(mapped as follows:draft
→draft
,open
→open
,paid
→paid
,void
→voided
,uncollectible
→voided
, default todraft
)data.object.currency
→hs_currency
(converted to uppercase)data.object.total
→hs_amount_billed
(converted from cents to dollars; only set fordraft
status invoices)data.object.due_date
→due_date
(formatted as “YYYY-MM-DD”)
- Associations:
- Associated with the relevant HubSpot Deal.
- Associated with HubSpot Line Items.
- Deduplication Key:
hs_title
(mapped fromdata.object.id
). Do NOT manually modify thehs_title
property in HubSpot for synced invoices.
4. HubSpot Object: Line Item
Stripe line item data (from invoices and subscriptions) is mapped to HubSpot Line Items.
- Stripe Events Processed: Handled as part of
invoice.*
andcustomer.subscription.*
events. - Stripe Fields Mapped to HubSpot Properties:
data.object.lines.data[*].description
(for invoice events) ORdata.object.items.data[*].price.nickname
(for subscription events, falls back todata.object.items.data[*].price.id
) →name
(descriptive name, not used for deduplication or correlation)data.object.lines.data[*].quantity
(for invoice events) ORdata.object.items.data[*].quantity
(for subscription events) →quantity
data.object.lines.data[*].amount
(for invoice events) ORdata.object.items.data[*].price.unit_amount
(for subscription events) →price
(converted from cents to dollars)data.object.lines.data[*].id
(for invoice events) ORdata.object.items.data[*].id
(for subscription events) →hs_sku
(used as the primary identifier for the line item)
- Associations:
- Associated with the relevant HubSpot Invoice.
- Associated with the relevant HubSpot Deal.
- Deduplication Key:
hs_sku
(mapped fromdata.object.lines.data[*].id
ordata.object.items.data[*].id
). It is critical that you do NOT manually modify thehs_sku
property in HubSpot for synced line items, as this is the unique identifier used for deduplication and correlation with Stripe product/price data.
Need help? Contact Support