topic Re: What scopes are required to call HubSpot properties API (e.g., for cart object)? in APIs & Integrations

What scopes are required to call HubSpot properties API (e.g., for cart object)?

Shrinath — Mon, 14 Jul 2025 11:49:16 GMT

Hi,

I'm trying to understand the required scopes for calling the HubSpot properties API,

specifically:GET /crm/v3/properties/{objectType}

For example, if I want to fetch properties for the cart object (/crm/v3/properties/carts), do I only need the crm.objects.carts.read scope, or is the crm.schemas.carts.read scope also required?
I tested this by including only crm.objects.carts.read, and the API worked fine — I received the expected response.
But the documentation mentions either of the two scopes.

So I’m wondering:
Which scopes are actually required to call the properties API?Is crm.objects.carts.read alone sufficient?
When should we use crm.schemas.carts.read?

Any clarification would be greatly appreciated. Thanks!

Re: What scopes are required to call HubSpot properties API (e.g., for cart object)?

BrandonWoodruff — Mon, 14 Jul 2025 13:17:47 GMT

Hello,

Short answer:

Yes, crm.objects.carts.read is sufficient to call GET /crm/v3/properties/carts.

Why the docs mention both:

The HubSpot Properties API lists either of the following scopes as valid:

crm.objects.{objectType}.read
crm.schemas.{objectType}.read

These two scopes both authorize access to read object schema (i.e., properties), but they serve different purposes:

Scope Use Case

crm.objects.carts.read	Grants access to object records and basic schema reads like fetching properties.
crm.schemas.carts.read	Grants access only to the object’s schema, not its records. Typically used in schema-specific integrations or admin tools.

TL;DR – When to use which?

Use **crm.objects.carts.read** if your integration also interacts with object records (create/read/update carts, etc.).
Use **crm.schemas.carts.read** only if your app needs to read schema but not touch object data.

If you already have crm.objects.carts.read, you do not need to add crm.schemas.carts.read — it’s redundant for the GET /properties/{objectType} endpoint.

Let me know if this helps, or if you have any other questions!

✔️ Was I able to help answer your question? Help the community by marking it as a solution.

Brandon Woodruff
Senior Software Developer @ Pearagon
Still have questions? Reach out at brandon@pearagon.com

Re: What scopes are required to call HubSpot properties API (e.g., for cart object)?

Jaycee_Lewis — Mon, 14 Jul 2025 19:16:08 GMT

Hey, @Shrinath 👋 I did a quick test. I made a new Private App and added a single scope. Then I made a request to the Properties API to get all the Cart properties. Worked without an issue.

I understand why the endpoint doc for this is confusing, as it lists all the related scopes and links them with multiple OR statements. But to your original question, `crm.objects.carts.read` is the bare minimum scope you need to get a successful response. Additional doc — Full Scopes documentation with a link to the specific one you need — here.

Have fun testing! — Jaycee

Re: What scopes are required to call HubSpot properties API (e.g., for cart object)?

Shrinath — Tue, 15 Jul 2025 07:28:39 GMT

@Jaycee_Lewis @BrandonWoodruff
Thanks for clarification.

One more thing, If have only crm.objects.carts.read scope in my app, Will i get 403-forbidden error?

Re: What scopes are required to call HubSpot properties API (e.g., for cart object)?

Shrinath — Tue, 15 Jul 2025 07:40:27 GMT

Thanks for clarification.

One more thing, If have only crm.objects.carts.read scope in my app, Will i get 403-forbidden error?

Re: What scopes are required to call HubSpot properties API (e.g., for cart object)?

Shrinath — Tue, 15 Jul 2025 07:43:23 GMT

Thanks for clarification.
Actually, Im getting 403-forbidden error for properties api call even though my app has crm.objects.carts.read.

Re: What scopes are required to call HubSpot properties API (e.g., for cart object)?

GRajput — Wed, 16 Jul 2025 07:34:40 GMT

Hi @Shrinath

"The required scope is crm.objects.carts.read
Here is the doc link of the API endpoint to carts

https://developers.hubspot.com/docs/reference/api/crm/objects/carts

I hope this will help you out. Please mark it as Solution Accepted and upvote to help another Community member.

Thanks!