HubSpot's standard objects cover most business needs. Contacts, companies, deals, and tickets handle the majority of CRM use cases cleanly. But some businesses track things that do not fit neatly into any of those four categories: contracts, subscriptions, equipment, projects, shipments, properties, event registrations. When you try to force those things into standard objects, the data model gets messy and the reporting gets unreliable.
Custom objects exist to solve that problem. They let you define new record types that match how your business actually operates, with their own properties, associations, pipelines, workflows, and reports. Used well, they make your CRM architecture cleaner and your data more accurate. Used carelessly, they add complexity without benefit.
This guide covers when to use custom objects, how to build them correctly, and how to get the most out of them across automation and reporting.
What Are HubSpot Custom Objects?
Custom Objects vs. Standard Objects
Standard objects are the four built-in record types in HubSpot: Contacts, Companies, Deals, and Tickets. Every HubSpot portal has them. They have predefined structures with standard properties and built-in associations between them.
Custom objects are additional record types that you define. You name them, set their properties, define how they associate with other objects (standard or custom), and optionally give them pipelines and stages. A custom object called "Contract" or "Subscription" or "Project" works the same way as a standard object in the HubSpot interface: it has an index page, individual records, properties, timelines, and associations.
Custom Objects vs. Custom Properties
This is the most common point of confusion. A custom property adds a new field to an existing object. A custom object creates a new record type entirely.
If you need to track a single additional piece of information about a contact (their preferred communication language, their contract renewal date), a custom property on the Contact object is the right choice. If you need to track a separate entity with its own lifecycle, multiple properties, and relationships to multiple contacts and companies, a custom object is appropriate.
The test: does this thing I need to track have a life of its own, or is it just an attribute of an existing record? If it is an attribute, use a property. If it is a separate entity, use a custom object.
Key Capabilities
Custom objects in HubSpot support:
- Custom properties of any type (text, number, date, dropdown, file, etc.)
- Associations with standard objects and other custom objects
- Pipelines and stages for tracking lifecycle or process progress
- Record creation via UI, import, workflow, or API
- Workflow enrollment and automation triggers
- Inclusion in custom reports and dashboards
- CRM card display on associated standard object records
Subscription And Permission Requirements
Custom objects require HubSpot Enterprise. This applies to Marketing Hub Enterprise, Sales Hub Enterprise, Service Hub Enterprise, or Operations Hub Enterprise. The specific hub does not matter, but at least one Enterprise subscription is required in your portal.
Creating and editing custom objects requires Super Admin permissions. Standard admin roles cannot create or modify custom object schemas.
When (And When Not) To Use Custom Objects
Ideal Use Cases
Custom objects make sense when you are tracking a distinct business entity that:
- Has multiple properties of its own (not just one or two fields)
- Has a lifecycle or status that changes over time
- Needs to be associated with multiple contacts, companies, or deals
- Needs its own pipeline or process tracking
- Needs to appear in reports independently from standard objects
Common real-world examples:
- Contracts or agreements: Each contract has a start date, end date, value, status, and is associated with a company and one or more contacts
- Subscriptions: Each subscription has a tier, billing cycle, renewal date, and status, associated with a contact or company
- Projects or onboarding cases: Each project has a name, owner, start date, current stage, and is associated with a deal and company
- Orders or shipments: Each order has a number, status, fulfilment date, and is associated with a contact and deal
- Physical assets or properties: Each asset has a location, condition, last inspection date, and is associated with a company
When Not To Use Custom Objects
A custom object is not the right tool if:
- You only need one or two additional fields on an existing record (use custom properties)
- The data you are tracking is an attribute of a contact or company, not a separate entity (use properties)
- You do not have an Enterprise subscription and are considering a workaround (reconsider the architecture)
- The relationship is simple enough to model with deals or tickets (use standard objects)
Overusing custom objects creates a fragmented data model that is harder to maintain, harder to report on, and harder for new team members to understand. Before creating a custom object, ask: can this be modelled cleanly with existing standard objects and properties?
Decision Framework
Planning Your Custom Object Architecture
Poor planning is the most common reason custom objects create problems rather than solving them. Before creating anything in HubSpot, answer these questions in writing.
Define Purpose, Lifecycle, And Stakeholders
What is this object? What does a record represent? What stages does it move through? Who creates records, who updates them, and who needs to report on them? A custom object that three teams use needs different design considerations than one used only by RevOps.
Naming Conventions
HubSpot uses two names for every custom object: a display name (what users see) and an internal name (used in the API). The internal name is set at creation and cannot be changed. Choose it carefully.
Use singular nouns for object names (Contract, not Contracts; Subscription, not Subscriptions). Keep names descriptive but concise. Avoid abbreviations in display names. For internal names, use lowercase with underscores: contract, monthly_subscription, project_case.
Primary And Secondary Display Properties
Every custom object requires a primary display property. This is the property that appears as the record's name in the index page, search results, and association panels. Choose a property that is unique and human-readable: a contract number, a project name, an order ID.
Secondary display properties appear in list views alongside the primary property. Choose two or three properties that give immediate context without opening the record: status, associated company name, value, or due date.
Mapping Associations
Define which objects your custom object needs to associate with before you build. Common association patterns:
- Contract → associated with Company (many-to-one) and Contact (many-to-many) and Deal (one-to-one)
- Project → associated with Company (many-to-one), Contact (many-to-many), and Deal (one-to-one)
- Subscription → associated with Contact (many-to-one) and Company (many-to-one)
HubSpot supports association labels, which let you define the nature of a relationship. A contact associated with a contract can be labelled as "Signatory," "Legal Contact," or "Primary Contact" using association labels.
Plan your associations and their labels before creating the object. Adding associations after the fact is possible but more disruptive.
How To Create A Custom Object In HubSpot
Step 1: Access The Data Model Builder
In HubSpot, go to Settings (gear icon), then Data Management, then Objects. Scroll to the bottom of the object list and select Create Custom Object. Alternatively, navigate to Reports, then Data Model, to see a visual map of your current objects and create new ones from there.
Step 2: Set Name, Description, And Primary Display Property
Enter the singular and plural display names (for example, "Contract" and "Contracts"). Enter an optional description that explains what this object represents. This description is for internal documentation and helps team members understand the purpose of the object.
Create the primary display property. This is typically a name or ID field. Choose type "Single-line text" for most cases. This property will be the record title throughout the interface.
Step 3: Create Properties
After creation, add all the properties your custom object needs. Go to the custom object's settings, select Properties, and add each one.
Property planning considerations:
- Use dropdowns for status fields, not free-text, to keep data consistent and reportable
- Use date properties for start dates, end dates, and renewal dates (not text fields storing date strings)
- Use number properties for monetary values (not text) so they can be summed and calculated in reports
- Add a "Record Owner" property early so records can be assigned and filtered by owner
Step 4: Define Associations
Go to the custom object's settings and select Associations. Add associations to the standard objects and custom objects this record type should connect to.
For each association, define whether to use standard labels or create custom labels. If a contract associates with contacts in multiple roles, create custom labels (Signatory, Legal Contact, Account Manager) rather than using the default "Contact" label for all.
Step 5: Create Your First Records
After schema setup, test with a small number of manually created records before importing bulk data. Verify that the primary display property appears as expected, that associations work correctly, and that properties display in the expected format.
Working With Custom Object Records
Creating Records Manually
From the custom object's index page (accessible via CRM in the main navigation, then your custom object name), click Create Record. Fill in the required properties and associate the record with relevant contacts, companies, or deals.
Importing Records
Use HubSpot's import tool to create records in bulk. Prepare a CSV with column headers matching your custom object's property internal names. Map each column to its property during the import process. Include an association column (email address for contacts, company domain for companies) to create associations during import.
Creating Records Via Workflows
Custom objects can be created as a workflow action. A workflow enrolled on contacts, companies, or deals can create a new custom object record and associate it with the enrolling record. This is useful for automating record creation based on triggers: a deal moving to "Closed Won" creates a Project record, or a form submission creates a Subscription record.
Record Views And CRM Cards
Customise how custom object records appear by editing the record layout in settings. Pin the most important properties to the left column. Add the association panel for each associated object type. Use CRM cards to display custom object records on the sidebars of associated standard object records (a Contract card appearing on the associated Company record, for example).
Pipelines, Stages And Process Tracking
Creating Custom Object Pipelines
Custom objects support pipelines and stages, similar to Deal pipelines. Go to the custom object's settings, select Pipelines, and create your first pipeline. Add stages that reflect the lifecycle of the record: for a Contract object, stages might be Draft, Under Review, Sent for Signature, Active, Expired.
Stage Design Best Practices
Keep stage counts manageable. Five to eight stages is usually sufficient. More stages create reporting complexity without proportional insight. Each stage should represent a meaningfully different status that triggers different actions or is useful to report on separately.
Define stage-entry requirements before building. What must be true for a record to advance to the next stage? Use required properties per stage (available in the pipeline settings) to enforce data completeness as records progress.
Pipeline Automation
Workflow triggers are available based on custom object pipeline stage. When a Contract moves to "Sent for Signature," a workflow can send a notification to the account owner, create a task with a follow-up deadline, and update a property on the associated Company record. This is where custom objects connect to operational automation and stop being just a data storage layer.
Using Custom Objects Across HubSpot
Workflows And Automation
Custom objects can enrol in workflows as the primary object. You can trigger workflows when:
- A custom object record is created
- A property value changes
- A pipeline stage changes
- A date property is reached (for renewal reminders, expiry alerts)
Custom objects can also be the target of workflow actions from other objects. A contact-based workflow can create or update a custom object record associated with that contact.
Reporting And Dashboards
Custom objects appear in the custom report builder. You can create reports on custom object records, filter by properties, measure pipeline stage distribution, and cross-reference with associated standard objects (reporting on contract value by associated company industry, for example).
For HubSpot services that include CRM architecture and reporting setup, custom object reporting is often where the most valuable operational insights live. Take a look at our work to see how we have built connected CRM data models for B2B clients, or get started with a conversation about your current data architecture.
Best Practices For Scalable Custom Objects
Governance And Documentation
Every custom object should have written documentation before it goes live. Document: the purpose of the object, who creates and owns records, what each property represents, which associations are used and what labels mean, and which workflows interact with it. Store this documentation in a shared location (Notion, Confluence, a Google Doc) that the whole team can access.
Without documentation, custom objects become tribal knowledge. When the admin who built them leaves, the logic behind the architecture is lost.
Property Design And Data Quality
Use dropdowns and defined value lists wherever possible. Free-text properties accumulate inconsistent data (Active vs. active vs. ACTIVE vs. Live) that makes filtering and reporting unreliable. For any property that will be used in segmentation, filtering, or reporting, use a structured property type.
Add required properties to pipeline stages to prevent records from advancing without critical data. A contract should not be able to move to "Active" without a signed date and a contract value.
Testing In Sandbox
If your HubSpot Enterprise portal includes a sandbox environment, build and test custom objects there before creating them in production. Test the full workflow: record creation, association, pipeline progression, workflow trigger, and report inclusion. Schema decisions made in production are difficult to reverse.
Object And Property Limits
HubSpot Enterprise supports up to ten custom objects per portal. Each custom object supports up to 1,000 properties. These limits are high enough for most use cases but worth knowing before designing an architecture with many distinct objects.
Object names and internal names cannot be changed after creation. Plan naming carefully before creating, because a poorly named object requires either living with the name or deleting and recreating the object and all its records.
Common Mistakes And How To Avoid Them
Creating A Custom Object When A Property Would Suffice
The most common mistake is creating a custom object for data that is simply an attribute of an existing record. If the only thing you need to track is a contract renewal date and a contract value, those are two properties on the Company record, not a separate custom object. Reserve custom objects for entities with their own lifecycle and associations.
Irreversible Schema Decisions
The internal name, set at creation, cannot be changed. If you name a custom object "cont" instead of "contract" in the internal name field, that is permanent. Before creating any custom object in production, write out the display name and internal name and have a second person review them.
Under-Documented Associations
Building associations without labels, or with generic labels that do not reflect the actual relationship, creates confusion when records have multiple contacts associated in different roles. Define and document your association labels before building.
Reporting Blind Spots
Custom objects appear in reports only when they are included in the report's object selection. If a team member builds a company report and does not include the custom Contract object, they will not see contract data. Train report builders on which custom objects are available and how to include them.
Real-World Examples
Contracts Or Subscriptions
A B2B SaaS company tracks customer contracts as a custom object. Each contract has: Contract Name (primary display), Value, Start Date, End Date, Status (dropdown: Draft, Active, Expiring, Expired), and Owner. The contract associates with a Company (one-to-one) and Contacts (many-to-many, with labels: Signatory, Legal Contact). A workflow fires 60 days before End Date and creates a renewal task for the account owner.
Projects Or Onboarding Cases
A professional services firm creates a Project custom object for each client engagement. Each project has: Project Name, Type, Start Date, Target Completion Date, and a pipeline with stages (Kickoff, In Progress, Review, Complete). Projects associate with the related Deal (one-to-one) and the delivery team Contacts. A report tracks average project duration by project type and delivery owner.
Orders Or Inventory Items
A manufacturing company tracks Orders as a custom object. Each order has: Order Number (primary display), Product SKU, Quantity, Status (Received, In Production, Shipped, Delivered), and Shipping Date. Orders associate with the related Deal and the Contact who placed the order. A workflow updates the associated Deal to "Closed Won" when an order status moves to Delivered.
Getting Started Checklist
Before creating your first custom object:
- Confirm you have at least one HubSpot Enterprise subscription in your portal
- Confirm you have Super Admin permissions
- Document the object's purpose, stakeholders, and data requirements
- List all properties needed with their types and whether they are required
- Map all associations and define labels for each
- Determine whether the object needs a pipeline and design its stages
- Plan naming: singular and plural display names, and internal name
- Test in sandbox if available before building in production
- After creation, build a report and a test workflow before going live with full team access
- Document the finished object schema and share it with the team
FAQs
What Are HubSpot Custom Objects?
Custom objects are user-defined record types in HubSpot that extend the standard objects (Contacts, Companies, Deals, Tickets). They allow you to track business entities that do not fit the standard model, such as contracts, subscriptions, projects, or orders, with their own properties, associations, pipelines, and automation.
Which HubSpot Plan Do I Need For Custom Objects?
HubSpot Enterprise. Any Enterprise Hub (Marketing, Sales, Service, or Operations) unlocks custom objects for the portal. They are not available on Professional or Starter tiers.
What Is The Difference Between A Custom Object And A Custom Property?
A custom property adds a new field to an existing object. A custom object creates an entirely new record type. Use a custom property when you need to track an additional attribute of a contact, company, or deal. Use a custom object when you need to track a separate entity with its own lifecycle and relationships.
Can Custom Objects Have Associations With Contacts And Deals?
Yes. Custom objects support associations with all four standard objects (Contacts, Companies, Deals, Tickets) and with other custom objects. Associations can include custom labels to define the nature of each relationship.
Can I Create Pipelines For Custom Objects?
Yes. Custom objects support pipelines and stages, configured in the custom object's settings. Pipelines work the same way as Deal pipelines, with drag-and-drop boards, stage-required properties, and workflow triggers on stage changes.
Can I Use Custom Objects In Workflows And Reports?
Yes. Custom objects can enrol in workflows as the primary object and can be the target of workflow actions from other objects. They appear in the custom report builder and can be cross-referenced with associated standard objects in reports.
Can I Rename A Custom Object After Creating It?
The display name can be changed. The internal name, used in the API and set at creation, cannot be changed. This is the most common schema mistake. Plan your internal naming carefully before creating the object in production.
When Should I Use A Custom Object Instead Of A Standard Object?
When you need to track a distinct business entity with multiple properties, its own lifecycle or status progression, associations with multiple record types, and its own pipeline. If the data is simply an additional attribute of an existing record, a custom property is the right tool.
A Note On Sources
Feature descriptions and configuration steps in this article reflect HubSpot's published capabilities for custom objects as of mid-2026. HubSpot updates its interface, object limits, and feature availability regularly. Verify current capabilities, limits (object count per portal, property limits per object), and subscription requirements at knowledge.hubspot.com before planning your implementation.
The ten-object and 1,000-property limits cited in this article reflect HubSpot's published Enterprise limits at the time of writing. These limits are subject to change. Confirm current limits directly with HubSpot or in the HubSpot developer documentation before designing an architecture that approaches these thresholds.
HubSpot is an independent platform. Belt Creative has no commercial relationship with HubSpot. Platform mentions are for informational purposes only and do not constitute an endorsement.