Skip to content
HubSpot Updates

Payments Account Public Read API: Check Payments Status Programmatically

September 4, 2026

What This Update Actually Is

HubSpot shipped a new public API endpoint that returns a HubSpot account's payments status on demand. One authenticated call to /commerce/payment-accounts/{version}/payment-accounts gives you three pieces of data: enrollment status, payments eligibility, and current transaction capabilities.

Before this shipped, none of that was accessible programmatically. Partners and integrators had to log into a portal, navigate to payment settings, and read the status with their eyes. That's a manual step that breaks automation, slows partner workflows, and creates real friction when you're managing multiple HubSpot accounts.

The endpoint is available across all hubs and tiers. Authentication requires the PAYMENTS_READ scope. That's the full scope of what shipped: straightforward, no surprises.

Why HubSpot Shipped This

HubSpot has been expanding its Commerce Hub aggressively. Payment links, subscriptions, invoices, and quotes with embedded checkout are all part of the picture now. But none of those capabilities matter if a partner's integration can't first confirm that payments is actually set up on the account it's connecting to.

The internal frustration was real. Developers building payments-adjacent workflows had to either hard-code assumptions about account status or build workarounds that added latency and error risk. Humans on the ops side were stuck doing status checks by hand before they could confidently push a payments feature to a client.

This endpoint closes that gap. It lets any authorized integration know, in real time, exactly what a given account can do with payments before it tries to do anything with payments.

How to Use It Step by Step

  1. Request the PAYMENTS_READ scope when setting up your private app or OAuth connection in HubSpot. This scope is required for the endpoint to return data.
  2. Authenticate to the HubSpot account you want to check. Use your app's access token as you would with any HubSpot API call.
  3. Call GET /commerce/payment-accounts/{version}/payment-accounts. Replace {version} with the current API version documented in HubSpot's developer portal.
  4. Parse the response. The payload returns the account's enrollment status (enrolled or not), eligibility flags (what the account qualifies for), and transaction capabilities (what it can actually process right now).
  5. Use the response as a gate. Build conditional logic in your integration so payments-dependent features only activate when the account's status confirms it's ready.
  6. Handle non-enrolled accounts gracefully. If the account isn't enrolled, surface a clear message or trigger an onboarding prompt instead of letting the integration fail silently.

What It Touches in Your HubSpot Strategy

This endpoint is narrow by design, but its impact reaches further than a single API call. Here's where it ripples.

Commerce Hub and Payments Workflows: Any automation that creates payment links, triggers invoice sends, or routes deals through a checkout step now has a reliable upstream check it can run first. That prevents broken flows caused by an account that looks active but isn't fully enrolled.

Partner and Multi-Portal Management: If you're a HubSpot partner managing multiple client portals, this is the status check you've been missing. Pair it with the Payments Checkout Settings API and the Revenue Payments API to build a full programmatic payments management layer across your client base. Together, these three endpoints let you read status, configure checkout, and manage payment records without ever opening the HubSpot UI.

Key Takeaway

The Payments Account Read API is most powerful when combined with HubSpot's other commerce endpoints. Read status first, configure settings second, create or manage payment records third. That sequence, fully automated, eliminates the manual portal checks that slow down partner implementations.

Operations Hub and Custom Integrations: Teams using Operations Hub to connect HubSpot with external billing systems, ERP tools, or custom apps can now use this endpoint as a preflight check. Before your webhook fires or your custom code action runs, confirm the account is ready. That's cleaner error handling and fewer support tickets.

Portal Auditing: For RevOps leaders who audit portals regularly, this endpoint adds a new signal to your audit process. Payments status is now a readable property you can pull into a script, a dashboard, or a report without logging in to check manually.

Key Takeaway

If your team runs periodic HubSpot portal audits, add a Payments Account API call to your audit script. It gives you enrollment status and capability data in the same pass as your other programmatic checks, with no manual UI steps required.

Who Should Care Most

This update is primarily a developer and partner story, but ops-minded humans will find real value here too. Here's the breakdown.

  • HubSpot Solution Partners building commerce integrations: use this as your account readiness gate before any payments feature goes live on a client portal.
  • RevOps engineers and custom app developers: reduce brittle assumptions in your payments-adjacent workflows by checking live account status programmatically.
  • Operations Hub power users who build cross-system automations: add a status check step before any flow that assumes HubSpot Payments is active.
  • Portal admins at growing companies: if you're planning to expand into HubSpot's commerce features, this endpoint is a clean way to confirm readiness before you invest in configuration.
  • App Marketplace ISVs: any app that surfaces payments functionality needs to know whether the connected account can use it. This endpoint makes that check reliable and repeatable.

George's Take

“The best API updates aren't flashy. They're the ones that close the gaps where humans were doing by hand what a machine should have been doing all along. This is one of those updates.”
— George B. Thomas

When I look at a HubSpot portal and spot payments enabled but nothing actually wired up correctly, it's almost always because someone assumed the account was ready without verifying it. That assumption breaks integrations, wastes implementation hours, and erodes trust in the platform. The Payments Account Read API removes that assumption entirely. For partners, it means you can build a check into your onboarding scripts right alongside your standard portal audit process. For ops teams, it means your automations finally know what they're working with before they try to act. That's not a minor convenience. That's a structural fix to a real workflow problem, and it's the kind of quiet, foundational work that makes the bigger commerce features actually reliable.

If you're building payments workflows, managing multiple client portals, or trying to get HubSpot Commerce working reliably across your tech stack, our team at Sidekick Strategies can help you map the full implementation. Book a strategy call and let's look at exactly what your portal needs to make payments work the way it should.

Frequently Asked Questions

What does the HubSpot Payments Account Read API return?

The endpoint returns three key pieces of data: the account's payments enrollment status (whether it's enrolled in HubSpot Payments), its payments eligibility (what it qualifies for based on account configuration), and its current transaction capabilities (what payment types and functions it can actually process at the time of the call).

What OAuth scope do I need to call the Payments Account Read API?

You need the PAYMENTS_READ scope enabled on your private app or OAuth connection. Without this scope, the endpoint won't return data. Add the scope during app configuration in HubSpot's developer portal before making your first call.

Which HubSpot plans include the Payments Account Read API?

The Payments Account Read API is available across all HubSpot hubs and tiers. You don't need a paid plan to access the endpoint itself, though HubSpot Payments eligibility and enrollment depend on account and geographic factors set by HubSpot separately.

How is this different from the HubSpot Revenue Payments API?

The Payments Account Read API is a status-check endpoint. It tells you whether an account is enrolled and what it can do. The Revenue Payments API lets you create payment records, retry failed payments, and manage transactions. Use the Read API as a preflight check before calling the Revenue Payments API to avoid errors on accounts that aren't ready.

Can HubSpot partners use this API to check client account status?

Yes. Partners with proper authorization to a client's HubSpot account can call this endpoint to verify payments readiness programmatically. It's especially useful during onboarding or when building commerce integrations, eliminating the need to manually check payments settings inside each client's portal.

What endpoint URL do I call to retrieve payments account status?

Call GET /commerce/payment-accounts/{version}/payment-accounts, replacing {version} with the current API version. Authenticate using an access token from an app that has the PAYMENTS_READ scope. The full endpoint structure and version details are documented in HubSpot's developer API reference.

Live Workshop

HubSpot Super Admin Workshop

Stop reacting to requests and start running your portal like the architect it needs. You leave with a filled-in plan, not just notes.

$999 · January 8, 2027 · Live virtual

Free, In Your Inbox

Get Every HubSpot Update

No spam. Unsubscribe anytime.

Comments

Join the conversation. Share what resonated, ask questions, or add your perspective.

Leave a Comment

We'd love to hear your thoughts. Your comment will appear after review.

Never shared publicly.

0/2,000

Ready To Talk?

Need Help Making Sense of HubSpot?

Sidekick Strategies helps your humans get the most out of every HubSpot update, feature, and tool. Let's make your portal work harder for you.