A migration can put every customer name into HubSpot and still leave the team unable to answer a renewal question. The missing information is often the relationship: which account owns the agreement, which people use the product and which commercial event the team is working on.
We recommend designing those relationships before mapping individual columns. For a SaaS business, the migration should preserve the context your sales and customer teams need to act, with a clear boundary around the information that remains in billing or product systems.
TLDR: Define accounts, people, commercial events and subscription concepts separately. Choose stable identifiers, map the required relationships and test representative customer scenarios. Select HubSpot objects according to the actual business requirement and account capabilities, rather than assuming every source table needs a custom object.
Describe the customer before choosing the object
Start with a plain-language model of your business. Is the paying organization the same as the organization using the product? Can one account have several agreements? Can a person work with more than one account? Who should see the context when a renewal or expansion request arrives?
These are design questions, not field-mapping questions. Write the answers with your sales, customer and finance stakeholders before deciding where each concept belongs.
HubSpot uses objects, records, properties and associations as CRM building blocks, with some objects depending on the account subscription. HubSpot's data model documentation provides the product reference. Verify the current account before committing to an object or feature.
If your team is still defining ownership and process requirements, review the scope of HubSpot onboarding and training alongside the migration plan. Data transfer should follow an approved model.
Keep business concepts distinct
We recommend documenting the purpose of each concept, its authoritative source and the question it must help someone answer.
| Business concept | Question to preserve | Mapping decision to document |
|---|---|---|
| Account | Which organization does this customer relationship concern? | The account identifier, parent relationships where relevant and ownership rules. |
| Person | Who is involved, and in what capacity? | The person identifier and required account relationships. |
| Commercial event | Which sale, renewal or expansion is being worked? | The event identifier, status meaning and relationship to the account. |
| Subscription context | What agreement or product context must the team understand? | The authoritative source, necessary CRM representation and update responsibility. |
This table describes business concepts. It does not prescribe four HubSpot objects or claim that the CRM should replace a billing platform. Use the supported account capabilities and your integration requirements to choose the implementation.
Preserve identifiers before cleaning the labels
Names are useful to people, but they are weak as the only migration matching rule. Document the source identifier for every included entity and the destination identifier after transfer. Decide how to handle records that have no reliable source identifier before importing them.
HubSpot's import documentation explains the use of unique identifiers to update existing records, avoid unintended duplicates and create associations. The import-tool overview should inform the method you select.
Do not assume that a company name or a shared email domain always represents the account relationship your business intends. Review ambiguous cases and record the approved rule. Keep the original identifier available in the migration evidence even when you standardize a display name.
Map relationships as deliverables
HubSpot associations connect records within and between objects. Its association documentation explains how those relationships are represented.
For each relationship required by your process, specify the source keys, destination keys, meaning and acceptance check. A migration plan that counts records but does not reconcile relationships is incomplete for this purpose.
Hypothetical example: One customer account has two commercial agreements. A purchasing contact is involved with both, while a technical contact supports only one. The intended CRM view must preserve those distinctions well enough for the team to identify the right people during a renewal.
The example does not establish which object configuration to use. It establishes the scenario that the proposed configuration must pass. Test it in the account and integration design you actually intend to operate.
Decide what stays outside the CRM
List the information your team needs in HubSpot and explain why. Do not copy every billing detail, product event or historical payload merely because it exists in the source.
For each included field, identify whether the CRM holds an authoritative value, a synchronized reference or a derived operational view. Then define which system may update it and how conflicting values are handled.
For information excluded from the migration, document how the team will retrieve it when needed and who owns retention. Sensitive information needs a separate assessment of permitted use, account capabilities and applicable obligations. Do not infer permission to transfer it from ordinary CRM access.
Our overview of HubSpot integrations can help you inventory the connected systems involved. Validate the specific connector and behavior in your plan rather than assuming an integration name guarantees the required mapping.
Test scenarios before accepting the migration
Choose cases that expose the model: a new customer, an account with multiple agreements, a changed contact, a closed commercial event and an ambiguous source record. For each case, write the question a user should be able to answer and the evidence that demonstrates the answer is correct.
Reconcile records and required relationships separately. Check ownership and the important fields that support the scenario. Where an integration will continue updating the data, include a controlled update in the acceptance plan.
The HubSpot portal audit checklist offers a broader review structure. Keep the migration acceptance focused on the model and the included source data.
Build a small SaaS relationship test before importing the backlog
The following fictional account map turns the earlier scenario into testable requirements. These labels are invented source references, not HubSpot object names, real customers or an assertion that a billing connector supports this design.
- Account AC-100: The organization with the commercial relationship. Both agreements belong to this account.
- Agreements AG-10 and AG-20: Separate subscriptions in the fictional source system. The renewal team must distinguish them even though they share an account.
- Contact P-10: The purchasing contact for both agreements. The intended view must preserve that responsibility.
- Contact P-20: The technical contact for AG-20 only. The model must not imply that this person owns the technical relationship for AG-10.
Have the intended user answer a specific question: which contact should we involve in the technical review of AG-10? In this example, the source has not supplied that person. “Unknown, needs review” is the correct result. Reusing P-20 because the company matches would create information the source does not support.
Test changed and missing relationships
Next, simulate an approved change to the purchasing contact. Check which relationships should change and which should stay intact. Keep the original source references and the expected destination references in the test evidence. A renamed company should not silently become a second customer account.
Add a deliberately incomplete agreement with no approved account match. We recommend keeping it in an exception register instead of assigning it to a convenient company. Record the decision owner, reason and next action. A smaller accepted population with explained exceptions is more useful than a larger population with invented relationships.
Test the ongoing update boundary
Migration is a transfer at a point in time. If product or billing information will continue to change elsewhere, the operating design also needs an update rule. Identify which system controls each included value, how the CRM receives changes, and what the team does when the source is unavailable. Test the actual integration configuration separately from the initial import.
Frequently asked questions
Does every SaaS migration need custom objects?
No universal object prescription follows from this example. Choose the representation after documenting the relationships and confirming account capabilities. A custom object should solve an approved requirement, not merely duplicate a source table.
Should billing history be copied into HubSpot?
We recommend moving only the information the agreed CRM process needs. Document what remains in the source, how authorized users retrieve it, and which system owns the current value. Review sensitive information separately.
What proves that the model survived the migration?
Retain a source-to-destination identifier crosswalk, relationship checks and user scenarios with observed results. A correct total contact count does not establish that an agreement is attached to the right account or person.
Hand over the model, not only the import files
Retain the approved definitions, field map, identifier crosswalk, relationship map, exception register and test results. Your team should know how the migrated information is maintained after launch and who approves changes to its meaning.
If the relationships are still unresolved, discuss the design through HubSpot operations and CRM architecture before authorizing transfer. We recommend accepting the migration when the agreed customer scenarios work and the evidence supports that conclusion.
Product documentation checked August 29, 2026. Object availability and integration behavior require account-specific verification.
