PandaDoc HubSpot Custom Object Merge Fields: Complete Enterprise Reference

Standard HubSpot deal, contact, and company tokens cover most sales proposals, but enterprise revenue teams eventually hit the ceiling of the default object model. The moment a RevOps team models Subscriptions, Contracts, Product Lines, Territories, or Renewals as custom objects in HubSpot Enterprise, the question becomes: how do we get that data into a PandaDoc merge field without duct-taping a Zapier flow onto every template?

This is one of the more common friction points we see in enterprise HubSpot rollouts. The standard PandaDoc HubSpot integration is built around the core CRM objects (Deal, Contact, Company, Owner), and custom-object support behaves differently. This reference walks through what does and does not work natively, how associations decide which record’s data lands in a document, and where the correct answer is Zapier or a custom API instead of native mapping.

Key takeaways

• HubSpot custom objects require Enterprise (or Ops Hub Enterprise) to create. If the portal is on Professional, custom-object merge fields are not a conversation yet, regardless of PandaDoc plan
• PandaDoc Business or Enterprise is the plan gate on the document side. The native HubSpot integration is not on Essentials or Free
• Custom-object properties are exposed through the association model: PandaDoc reads the record associated to the source Deal (or Contact), so association labels and cardinality matter more than the field names
• The most common failure mode is not a bug: it is a missing or wrong association type between the Deal and the custom-object record, which makes the field vanish from the token picker
• When a custom object has many-to-one relationships (a Deal with several Subscription line items), native mapping breaks down and a Zapier or custom-API path is usually the right call
• Test every custom-object token against a fully-populated Deal before rolling a template out to reps: half-populated associations produce silent blanks, not errors

What are HubSpot custom objects and when do teams create them?

HubSpot custom objects are RevOps-defined record types that sit alongside the standard Deal, Contact, Company, and Ticket objects. Available only on Enterprise tiers (Sales Hub Enterprise, Service Hub Enterprise, or Ops Hub Enterprise for the API-driven variety), they let a team model entities that do not fit the default CRM schema, with their own properties, associations, and pipelines.

Common patterns we see in enterprise HubSpot portals:

Subscriptions: a recurring revenue record separate from the Deal, tracking tier, seat count, MRR, renewal date, contract term, and billing cycle. Useful when one Deal can spawn several subscription lines, or when a customer has multiple active subscriptions across product lines

Contracts: the legal instrument, often with its own effective date, expiry, auto-renewal clause, and signed PDF URL. Kept separate from the Deal so that renewals and amendments can be tracked without creating new deals

Product Lines / SKUs: for teams whose product catalog is complex enough that HubSpot’s built-in Products object is insufficient, particularly when SKUs have hierarchy or bundle logic

Territories: a geographic or account-segment record used for routing, commission split, and pricing tier

Assets: hardware, licenses, or account provisioning records that a customer accumulates over time and needs to appear on renewals or upsell proposals

The trigger for a team to create a custom object is almost always the same: they’ve outgrown storing something as a comma-delimited text field on the Deal, and they need reporting or automation against it. Once the object exists, the next question is inevitably how to get its data onto a proposal.

Does PandaDoc natively expose HubSpot custom-object properties as merge fields?

Yes, but with conditions. The native PandaDoc HubSpot integration supports custom objects on PandaDoc Business and Enterprise plans, provided the HubSpot portal is Enterprise (custom objects don’t exist below that tier). Custom-object properties surface in the PandaDoc token picker only when the custom-object record is associated to the source Deal or Contact the document is being generated from, and only after the object type has been enabled in the PandaDoc integration settings.

The behavior is different from standard object tokens in three important ways:

Association-driven, not property-driven: PandaDoc doesn’t fetch every custom-object record in the portal. It reads the record(s) associated to the Deal you’re generating from. If no association exists, no data flows

Cardinality matters: If the Deal is associated to exactly one Subscription record, PandaDoc can populate a single set of Subscription tokens. If the Deal is associated to five Subscriptions, the native token picker becomes ambiguous, and you typically need PandaDoc’s pricing table or a Zapier-populated variable to render multiple rows

Association label sensitivity: HubSpot Enterprise supports multiple association labels between the same two object types (Primary Subscription, Add-on Subscription, Renewed Subscription). PandaDoc’s mapping usually keys off the default or primary association, so a record connected only via a non-default label may not appear

The upshot: enable the custom object in the integration settings, associate exactly one custom-object record of that type to the Deal, and standard-looking tokens become available. Anything more complex than that pattern typically requires a fallback path.

How do I enable custom objects in the PandaDoc HubSpot integration?

In PandaDoc, go to Settings > Integrations > HubSpot, and look for the object-mapping section. Enterprise-plan portals will show any custom objects defined in HubSpot alongside the standard Deal, Contact, and Company objects. Toggle the custom object on, choose which properties to expose to templates, and save. In HubSpot itself, confirm the custom object has been given a full API name (not just a display label) and that the PandaDoc app scope covers it.

Two menu paths worth remembering:

HubSpot > Settings > Data Management > Objects > Custom Objects: where the object schema lives. Confirm the object exists, its singular and plural labels are set, and the association definitions to Deal or Contact are declared. Note the internal object type ID (a string like p1234567_subscription), because it appears in PandaDoc’s mapping UI

PandaDoc > Settings > Integrations > HubSpot > Object Mapping: where you toggle the object on for token exposure and pick which properties to sync. If the custom object doesn’t appear here, the PandaDoc app is almost always missing the CRM scope for that object type: reinstall the app and re-consent, choosing an account with Super Admin rights in HubSpot

Property selection matters at scale. Custom objects often have dozens of internal-use properties (audit fields, calculated fields, lifecycle stages) that reps never need in a proposal. Only expose the fields that will actually be referenced from templates: it keeps the token picker sane and avoids reps mistakenly inserting an internal field into a customer-facing document.

What does the plan-gate reality look like in an enterprise rollout?

Custom-object merge fields require both sides of the integration to be on the correct tier. HubSpot’s plan gate is Enterprise (Sales, Service, or Ops Hub Enterprise), and PandaDoc’s plan gate is Business or Enterprise. If either side is under-plan, the mapping simply won’t appear, and the failure mode is silent: no error, just no field in the token picker.

The combinations we see in enterprise HubSpot rollouts:

HubSpot Enterprise + PandaDoc Business: custom objects work, though some advanced PandaDoc features (SSO, advanced roles, some workspace controls) sit on PandaDoc Enterprise. Fine for most custom-object merge use cases

HubSpot Enterprise + PandaDoc Enterprise: full compatibility including SSO alignment, workspace segmentation, and role-based template access. Recommended for teams over ~50 seats or with regulated-industry document controls

HubSpot Professional + any PandaDoc plan: custom objects don’t exist in the portal, so this conversation stops at the HubSpot side. Standard Deal/Contact/Company tokens work

HubSpot Ops Hub Enterprise (standalone): the Ops Hub tier alone unlocks custom objects even without Sales Hub Enterprise, which is a cost-saver we occasionally recommend for RevOps-heavy teams whose sales reps are on Sales Hub Pro

Confirm both plan tiers before scoping a custom-object mapping project. The number of enterprise rollouts we’ve seen stalled by a Professional-tier HubSpot portal with an ambitious Subscription-object plan is not small.

How does the association model decide which custom-object record populates a merge field?

PandaDoc uses HubSpot’s association graph, starting from the source Deal (or Contact) the document is being generated from, and walks one hop out. If the Deal is associated to a single Subscription record, that record’s properties fill the Subscription tokens. If multiple records exist, PandaDoc typically picks the primary association or the most recently associated record, depending on version and configuration.

This is the mental model to hold when a merge field is behaving unexpectedly:

1. The rep clicks Create Document from a Deal record in HubSpot
2. PandaDoc opens with the Deal ID as context
3. For each enabled custom object in the template’s tokens, PandaDoc queries HubSpot: “give me the record(s) of type X associated to this Deal”
4. If exactly one record comes back, tokens populate directly
5. If multiple come back, PandaDoc resolves to the primary or first-returned record, which may or may not be what the rep expected

The failure paths cluster around step three. A Deal with no associated Subscription produces blank tokens. A Deal associated to the wrong Subscription (an old record that was never disassociated) produces stale data. A Deal associated via a non-primary label may not surface at all, depending on how the mapping is configured.

For teams with strict data-hygiene expectations, we recommend adding a HubSpot workflow that enforces the association at deal-stage change: when a Deal moves to Proposal or Negotiation stage, verify the primary Subscription (or Contract, or whichever custom object drives the proposal) is associated, and flag the rep if it is missing.

What does a real custom-object mapping look like end to end?

Take a Subscription custom object with three fields (tier, monthly price, seat count) that a SaaS team wants on every renewal proposal. The end-to-end path is: create the object and fields in HubSpot Enterprise, enable it in PandaDoc’s integration settings, associate the Subscription record to the target Deal, insert Subscription tokens in the PandaDoc template, and generate the document from the Deal. Tokens resolve at document creation, not at send.

Walking through the setup:

HubSpot side:

1. Under Settings > Data Management > Objects > Custom Objects, create a Subscription object with singular label Subscription, plural Subscriptions, and a primary property (Subscription Name)
2. Add three custom properties: tier (dropdown: Starter/Growth/Enterprise), monthly_price (currency), seat_count (number)
3. Define an association type between Subscription and Deal, one-to-many (a Deal can have one primary Subscription, a Subscription can be tied to multiple renewal Deals over time)
4. Populate at least one test Subscription record and associate it to a real Deal in a non-production pipeline

PandaDoc side:

1. Under Settings > Integrations > HubSpot > Object Mapping, toggle Subscription on
2. Select the three properties (tier, monthly_price, seat_count) as exposed to templates
3. Open a proposal template, insert tokens using the Token picker: they’ll appear under the Subscription namespace (exact syntax varies with integration version, so verify against the picker rather than typing them by hand)
4. Save the template

Test:

1. From the test Deal, click Create Document in the PandaDoc panel
2. Verify Subscription tokens populate with the associated record’s values
3. Change the Subscription’s tier value in HubSpot, regenerate the document, confirm the new value flows through

That last step matters: PandaDoc reads token values at document-creation time, not template-edit time. Editing a Subscription record after a document has been generated does not retroactively update sent documents.

For pricing complexity beyond flat tier lookups, this is often the point where we bring PandaDoc CPQ into the design. Pricing tables driven by custom-object line items scale better than trying to render N Subscription records through N sets of merge fields.

Why aren’t my custom-object fields showing in the PandaDoc token picker?

Four causes account for almost every “the field isn’t there” report. In order of frequency: the object isn’t enabled in PandaDoc’s integration settings, the app’s OAuth scope doesn’t cover the custom object (usually because the app was installed before the object was created), the association type between Deal and custom-object record isn’t the one PandaDoc expects, or the field is enabled but there’s a sync-delay window on very fresh custom objects.

Diagnostic checklist:

Permission scope: Reinstall the PandaDoc app in HubSpot with a Super Admin account. If the custom object was created after the app was originally installed, the OAuth grant likely doesn’t include it. A fresh install re-consents to the current object schema

Object mapping toggle: In PandaDoc Settings > Integrations > HubSpot > Object Mapping, confirm the object is toggled on and the specific field is in the exposed-properties list. Fields not in that list won’t appear in the token picker even if the object is enabled

Association type mismatch: In HubSpot, confirm the association between Deal and the custom object uses the default association type, or that PandaDoc’s mapping has been pointed at the correct labeled association. Records connected only via a non-default label are invisible to the default mapping

Field name collision: Custom-object property internal names must be unique within the object, but occasionally a custom-object property collides with a reserved keyword or with a same-named property on the Deal. When in doubt, rename the custom-object property with a distinctive prefix (e.g., sub_tier instead of tier)

Sync-delay window: For objects and fields created within the last few minutes, allow up to 15 minutes for the PandaDoc token picker to refresh. Force a refresh by disconnecting and reconnecting the integration if needed

Deal has no associated record: Even a perfectly configured field will not preview a value in the token picker if the test Deal you’re viewing has no associated record of that custom-object type. Test against a Deal you know has a full association

If all five have been checked and the field still isn’t appearing, the object type or field itself may not be supported by the current version of PandaDoc’s integration. This is where the decision to fall back to Zapier or a custom API comes in.

When should I use native mapping vs Zapier vs a custom API?

Native mapping is the right call for single-record associations and static field values. Zapier is the right call when the transformation is non-trivial (concatenation, lookups, conditional logic) or when the source data lives in a system HubSpot doesn’t directly hold. A custom API integration is the right call when the record cardinality is high (many line items rendered dynamically), when the operation must be transactional, or when compliance requires the middleware layer to be under the team’s own control.

Decision table:

Scenario	Native Mapping	Zapier	Custom API
Single Subscription associated to Deal, flat fields to tokens	Yes	Overkill	Overkill
Contract expiry date to a token, formatted as MM/DD/YYYY	Yes (PandaDoc token formatting)	Optional	No
Product-line records rendered as pricing-table rows	No (cardinality too high)	Workable but fragile	Yes (populate PandaDoc pricing table via API)
Data from a third system (billing, provisioning) not in HubSpot	No	Yes if in Zapier catalog	Yes if custom source
Real-time price calculation with conditional discounts	No	Fragile	Yes
Compliance requires no third-party data processor	No	No	Yes (self-hosted middleware)
Rep-triggered document with 100+ possible template variants	Partial	Fragile at scale	Yes
One-off enterprise deal with custom legal terms	No	No	Yes (populate manually or via one-off script)
High-frequency renewals (>50/day) with same template	Yes if data model is clean	Slow (Zapier task limits)	Yes (better throughput)

Two heuristics we apply when scoping this in enterprise HubSpot rollouts:

Cardinality rule: If the answer to “how many custom-object records will populate this document?” is more than one and less than deterministic, plan for a custom API from the start. Zapier can hack it, but the maintenance cost grows fast

Ownership rule: If the data flow needs to survive the team’s Zapier admin leaving, or if the compliance posture requires a documented data-processing path, build it as a custom integration owned in the team’s own codebase. Zapier’s audit story is thin

Teams that want a purpose-built path here are what our Proposal Engine, our flagship PandaDoc implementation for enterprise revenue teams is designed for: middleware that sits between HubSpot custom objects and PandaDoc’s document API, handling the association resolution, cardinality expansion, and pricing-table population that native mapping doesn’t cover.

What does the fallback path via Zapier or custom API look like in practice?

Zapier fallback: trigger a Zap on a HubSpot event (deal-stage change, custom-object property update), fetch the associated custom-object records via HubSpot’s API step, transform the data into a flat variable set, and use PandaDoc’s Zapier action to create a document from a template, passing the variables in as merge-field overrides. Custom API fallback: replicate the same shape as a service, giving the team full control over error handling, retries, logging, and the eventual sunset of Zapier tasks.

The Zapier pattern is roughly:

1. Trigger: HubSpot deal enters a specific stage
2. Action: HubSpot > Get Custom Object Records associated to Deal
3. Action: Formatter > shape the data (concatenate SKUs, sum quantities, format currency)
4. Action: PandaDoc > Create Document from Template, passing shaped variables

The custom-API pattern is:

1. Webhook receives the HubSpot workflow event
2. Service calls HubSpot’s associations v4 API to fetch the exact records, respecting association labels
3. Service transforms data with the team’s own logic (in code, tested, versioned)
4. Service calls PandaDoc’s Documents API, either creating from a template with merge fields or generating from scratch with pre-populated pricing tables
5. Service writes back a completion status to HubSpot, updating a deal property that HubSpot workflows can then act on

The custom-API path is more work upfront but pays off as soon as the team needs conditional logic, high throughput, or auditability. For teams where the proposal is the product, this is usually where they land.

FAQ

Do HubSpot custom objects work with PandaDoc’s free plan? No. The native HubSpot integration requires PandaDoc Business or Enterprise. Custom objects also require HubSpot Enterprise on the CRM side. Both plan gates must be met.

Can PandaDoc pull data from HubSpot custom objects not associated to the source Deal? Not through native mapping. Native mapping walks one association hop from the Deal (or Contact) the document is being generated from. Data on unassociated records requires Zapier or a custom API to fetch and inject.

What happens if a Deal is associated to multiple custom-object records of the same type? Native mapping typically resolves to the primary association or the first-returned record. This is rarely what the rep intends when there are multiple Subscriptions or Contracts. High-cardinality scenarios usually need a pricing-table pattern or a custom-API populated set of merge fields.

How long does a newly created custom-object field take to appear in PandaDoc’s token picker? Usually within a few minutes, though up to 15 minutes is normal. Disconnecting and reconnecting the integration forces an immediate refresh. If the field never appears, check that it was added to the exposed-properties list in PandaDoc’s object-mapping settings.

Can we use HubSpot custom-object data in a PandaDoc pricing table? Not directly through native mapping in most cases. Pricing tables sourced from custom-object line items typically require either a manual copy at document time or an API-driven population step. This is one of the strongest cases for a middleware layer.

---

Custom-object merge fields are where the enterprise HubSpot and PandaDoc stacks either lock in as a scalable proposal engine, or turn into a maintenance drag on RevOps. Getting the association model, plan gates, and fallback strategy right at the start is the difference. If you’re standing up custom objects for Subscriptions, Contracts, or Territories and want the mapping designed before the first template goes to reps, book a scoping call and we’ll walk through the model with your team.