HubSpot: Understanding hs_recurring_billing_period on One-Time Products

Summary

hs_recurring_billing_period and recurringbillingfrequency are two separate properties on the Products object in HubSpot. They are often confused because they sound related, but they serve different purposes:

The One-Time Default Behavior

"One-time" is not an actual selectable option in the recurringbillingfrequency dropdown, either in the UI or via the Properties API. It only appears as the default label when recurringbillingfrequency is left blank.

When a product is set to one-time billing:

• recurringbillingfrequency is blank/null (there is no one_time enum value, setting it explicitly via API throws an error)
• hs_recurring_billing_period still gets populated, defaulting to P1M

Because of this default, every one-time product will show hs_recurring_billing_period = P1M, and in the UI this always displays as the number 1 (not as "Monthly").

Why This Matters

If you're pulling hs_recurring_billing_period via the API to determine a product's actual billing frequency, don't rely on it alone. A value of P1M does not necessarily mean the product bills monthly, it may simply be a one-time product carrying the default.

To correctly identify a product's billing frequency:

1. Check recurringbillingfrequency first.
2. If it's blank or absent, treat the product as one-time, regardless of what hs_recurring_billing_period shows.
3. Only use hs_recurring_billing_period to interpret term/duration when recurringbillingfrequency has an actual recurring value set.

UI vs. API Differences

The UI abstracts both fields differently than how they're actually stored and named via the API.

Billing frequency

• UI: the dropdown on a product/line item literally lists "One time" as a selectable option alongside Monthly, Quarterly, Semi-annually, Annually.
• API: there is no one_time enum value for recurringbillingfrequency. Selecting "One time" in the UI simply leaves the property blank. Attempting to set it to one_time via API returns an error.

Recurring billing period / Term

• UI: shown as a plain field labeled Term, a number representing the duration of the billing term (for example, a monthly product with 12 fixed payments shows Term = 12).
• API: stored as hs_recurring_billing_period in ISO 8601 duration format (P12M), not as a plain integer.

So the same underlying data reads very differently depending on where you look: the UI shows human-friendly labels and numbers, the API returns raw ISO durations and blanks instead of "one_time."

How the Two Fields Link for Subscriptions

recurringbillingfrequency and hs_recurring_billing_period work together, not independently, when HubSpot determines how a product or line item behaves inside a subscription:

• recurringbillingfrequency sets the cadence, how often a charge occurs (monthly, quarterly, annually).
• hs_recurring_billing_period sets the term, how long that cadence runs for, expressed as a duration in months.

Together, these two values are used to calculate hs_recurring_billing_terms (read-only, calculated automatically), which resolves to either:

• FIXED, a defined number of payments, or
• AUTOMATICALLY_RENEW, no end date, continues until cancelled

When a subscription is created, HubSpot groups line items onto the same Subscription record only if they share the same billing frequency, billing terms, billing start date, and number of payments. If any of those differ, for example one line item is monthly and another is annual, they are split into separate Subscription records, each with their own billing schedule.

For a one-time product, since recurringbillingfrequency is blank, there's no cadence to combine with hs_recurring_billing_period, so it never enters a subscription record. It's simply invoiced once. The P1M default it carries is a leftover placeholder with no functional effect on billing.

Quick Reference