# Limits To assure good performance for every project, the API platform imposes limits on certain parameters and objects. Some limits can be increased per project on customer request. Most limits only apply to projects created after the introduction of the respective limit. To decide whether you should request a higher limit or redesign your solution, see [Limit increase guidance](/api/limit-increase-guidance.md). The current value of a project's limits can be accessed via the `limits` field on the [GraphQL API](/api/graphql.md). If the limit applies to the total amount of a resource type, the current usage can be accessed as well. ## General ### JSON document size JSON documents persisted through any API endpoint must not be larger than **16 megabytes**. If an update action causes an existing resource to exceed this size limit, the request will fail with a [ResourceSizeLimitExceeded](/search.md?urn=ctp:api:type:ResourceSizeLimitExceededError) error. This limit isn't related to the general [request body size](/api/limits.md#request-body-size). A request can still be smaller than **16 megabytes** and fail if the resulting document exceeds this limit. For best performance, we recommend limiting your average documents to **100 KB**. Large documents, for example a Product with many Product Variants, or an Order with many Line Items, should not exceed **2 MB**. The size limit also applies to updates made by background processes with [eventual consistency](/api/general-concepts.md#eventual-consistency). When a resource is close to **16 megabytes**, a background update that would push it past the limit is not applied, and the affected fields remain stale until the resource shrinks below the limit. For example, if a Product is close to the size limit, updates to a Product Variant's `availability` triggered by [InventoryEntry](/search.md?urn=ctp:api:type:InventoryEntry) changes may not be reflected on the Product. ### Request body size The HTTP request body of any API call must not exceed **14 megabytes**. Requests with a larger body are rejected with an HTTP [`413` Content Too Large](/api/errors.md#413-content-too-large) response before they reach the endpoint logic. This limit applies to the raw HTTP request. Some endpoints enforce a stricter limit on their payload; for example, [Product image uploads](/api/projects/products.md#upload-product-image) are capped at a smaller size, documented on the endpoint. ### URL and headers size The combined size of the request URL (including all query parameters) and HTTP headers must not exceed **about 15 kilobytes**. Requests that exceed this limit are rejected before reaching the endpoint logic and are listed among the [disallowed requests](/api/general-concepts.md#disallowed-requests). This limit is most commonly reached when passing long query parameter values, such as a [`where`](/api/general-concepts.md#query-features) predicate with many values in an `in (...)` expression, or a long list of [expansion paths](/api/general-concepts.md#reference-expansion). To keep query strings compact, use [input variables](/api/predicates/query.md#input-variables) to move repeated values into separate `var.*` query parameters, and split large ID sets into multiple smaller requests. ### Field content size For performance reasons, the maximum size of a searchable field within an [AttributeDefinition](/search.md?urn=ctp:api:type:AttributeDefinition) can not exceed **10922 characters**. Non searchable fields are only limited by the overall JSON document size. ### String content limits Any limitations in length and content of string fields are documented in the API reference of each resource with `MinLength`, `MaxLength`, and `Pattern`. If a `Pattern` is not specified, any UTF-8 encoded Unicode characters are accepted. Additionally, the length of string fields is limited by the overall [JSON document size](/api/limits.md#json-document-size). ### Slugs A Slug must match the pattern **\[a-zA-Z0-9\_-]**, hence they are limited to **256** characters. ### Queries Within a query, up to **500** elements can be fetched. When using [pagination](/api/general-concepts.md#pagination), the maximum offset is **10000**. The `total` field of [PagedQueryResult](/api/general-concepts.md#pagedqueryresult) is limited to the maximum `offset` when the results are filtered with a [Query Predicate](/api/predicates/query.md). See our performance tips for [best practices in optimizing queries](/api/performance-tips.md#query-and-retrieve-data) and [recommended response sizes](/api/performance-tips.md#response-size). For guidance on when to redesign instead of requesting a higher query limit, see [Limit increase guidance](/api/limit-increase-guidance.md#deep-pagination-and-aggregate-style-queries). ### Update actions per request For performance reasons, the maximum number of update actions within a single request is limited to **500**. ### Reference Expansion An [expansion path](/api/general-concepts.md#expansion-paths) is limited to a maximum depth of **3** references. ### GraphQL Queries with a complexity score greater than or equal to **20000** are not executed, and a [QueryComplexityLimitExceeded](/api/graphql.md#querycomplexitylimitexceeded) error is returned. ### Load testing Visit [Load testing](/api/load-testing.md) to learn about the [limits](/api/load-testing.md#obligations-and-responsibilities) and [exclusion periods](/api/load-testing.md#exclusion-periods) that apply. ## Authorization ### External OAuth 2.0 endpoint timeouts When using tokens issued by an [external OAuth 2.0 introspection endpoint](/api/authorization.md#request-an-access-token-using-an-external-oauth-server), the OAuth 2.0 service must respond in **500 ms**, including network latency. If the introspection endpoint times out or a connection cannot be established, the request will fail. The response has a `504 Gateway Timeout` or `502 Bad Gateway` HTTP status code and an [ExternalOAuthFailed](/search.md?urn=ctp:api:type:ExternalOAuthFailedError) error code. ### Refresh tokens The number of refresh tokens is limited to **10 million**. If the limit is exceeded, the least recently used refresh tokens are deleted. Creating new refresh tokens continues to work. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#product-and-pricing-model-limits). ## Product Catalog ### Categories A maximum number of **10000** [Categories](/api/projects/categories.md) can be created. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#product-and-pricing-model-limits). ### Product Variants A maximum number of **100** [ProductVariants](/api/projects/products.md#productvariant) can be specified on a [Product](/search.md?urn=ctp:api:type:Product). This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Variants If your Project uses the `Modular` [ProductCatalogModel](/api/projects/project.md#productcatalogmodel), a maximum number of **10000** [Variants](/api/projects/variants.md#variant) can be created per [Product](/api/projects/products.md#product). If your Project uses the `Classic` [ProductCatalogModel](/api/projects/project.md#productcatalogmodel), a maximum number of **100** [ProductVariants](/api/projects/products.md#productvariant) can be created per [Product](/api/projects/products.md#product). ### Product Search A maximum number of **10000** [StandalonePrices](/api/projects/standalone-prices.md#standaloneprice) per [Product](/search.md?urn=ctp:api:type:Product) can be indexed for [Product Search](/api/projects/product-search.md). A maximum number of **15000** [ProductSelections](/api/projects/product-selections.md#productselection) per Product can be indexed for Product Search. A maximum number of **15000** [Stores](/api/projects/stores.md#store) per Product can be indexed for Product Search. A maximum number of **50** Product Attributes per Product and a maximum number of **50** Variant Attributes per Product Variant can be [indexed](/api/projects/product-search.md#product-indexing) for Product Search. Within a search request, up to **100** elements can be fetched. In pagination, the maximum offset is **10000**. Queries with string values cannot contain more than **256** characters. Exceeding this limit will return an invalid input error. You can include a maximum of **50** expressions in a single request. This includes all compound expressions. For performance reasons, the maximum size of a searchable field within an [AttributeDefinition](/search.md?urn=ctp:api:type:AttributeDefinition) can not exceed **10922 characters**. The number of terms per facet is limited to **200**. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Product Projection Search For performance reasons, the maximum size of a searchable field within an [AttributeDefinition](/search.md?urn=ctp:api:type:AttributeDefinition) can not exceed **10922 characters**. The number of terms per facet is limited to **200**. Within a search request, up to **500** elements can be fetched. In pagination, the maximum offset is **10000**. Search results are based on the first **256** characters of the [full-text search](/api/projects/product-projection-search.md#full-text-search) query parameter only. Everything beyond **256** characters will be ignored. You can continue to pass longer query parameters, the API call will still be successful. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Attribute Groups A maximum number of **100** [Attribute Groups](/api/projects/attribute-groups.md) can be created per project. ### Product Tailoring A maximum number of **100000000** [Product Tailoring](/api/projects/product-tailoring.md) can be created per project. This limit can be increased per project after we review its impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Product Selections The maximum number of SKUs per Product Selection matches the limit on [Product Variants](/api/projects/products.md#productvariant) per Product. The default value is **100** and can be increased per project on customer request after reviewing the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. In the `Modular` [ProductCatalogModel](/api/projects/project.md#productcatalogmodel) , this limit is fixed to **1000**. Additionally, in this mode, each Product can be included in at most **1000** Product Selections and excluded from at most **1000** Product Selections. ## Pricing and Discounts ### Standalone Prices The maximum number of **50000** [StandalonePrices](/api/projects/standalone-prices.md#standaloneprice) can be specified per [ProductVariant](/search.md?urn=ctp:api:type:ProductVariant). This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, the project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#product-and-pricing-model-limits). ### Embedded Prices A maximum number of **100** [Embedded Prices](/api/types.md#price) can be specified per [ProductVariant](/search.md?urn=ctp:api:type:ProductVariant). Tiered prices, if any, are also counted towards this limit. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. If you want to go over this limit, you can also use [StandalonePrices](/api/projects/standalone-prices.md) for an alternative way for pricing your products. For more guidance, see [Limit increase guidance](/api/limit-increase-guidance.md#choose-an-alternative-before-you-request-an-increase). ### Cart Discounts The number of active [CartDiscounts](/api/projects/cartDiscounts.md#cartdiscount) that do not require a Discount Code (`isActive=true` and `requiresDiscountCode=false`) and are independent of any Store is limited to **100**. Additionally, each Store can have up to **100** active [CartDiscounts](/api/projects/cartDiscounts.md#cartdiscount) that do not require a Discount Code. Thus, the overall limit of active Cart Discounts without Discount Codes is **100** + (**100** \* number of Stores in a Project). The limit applies independently for non-recurring Orders (with `recurringOrderScope` set to `AnyOrder` or `NonRecurringOrdersOnly`) and for recurring Orders (with `recurringOrderScope` set to `AnyOrder`, `RecurringOrdersOnly`, or `ApplicableRecurrencePolicies`). These limits can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#discount-and-checkout-limits). ### Cart Discount's Stores A [CartDiscount](/search.md?urn=ctp:api:type:CartDiscount) can be associated with up to **500** [Stores](/api/projects/stores.md). This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Discount Codes A [Cart](/search.md?urn=ctp:api:type:Cart) can contain up to **10** [DiscountCodes](/api/projects/discountCodes.md#discountcode). A [DiscountCode](/search.md?urn=ctp:api:type:DiscountCode) can be associated with up to **10** [CartDiscounts](/api/projects/cartDiscounts.md#cartdiscount). ### Discount Groups The maximum number of [DiscountGroups](/api/projects/discount-groups.md#discountgroup) that can exist in a Project is **100**. A DiscountGroup can contain up to **100** [CartDiscounts](/api/projects/cartDiscounts.md#cartdiscount). ### Product Discounts The maximum number of [ProductDiscounts](/api/projects/productDiscounts.md#productdiscount) that can be active at the same time is **500**. ## Carts, Orders, and Shopping Lists ### Payment Methods A Customer or Associate can have up to **50** active and **100** inactive [PaymentMethods](/api/projects/payment-methods.md#paymentmethod). The limits apply independently per Customer or Associate and do not overlap. A Project can contain up to **1000000** [PaymentMethods](/api/projects/payment-methods.md#paymentmethod) that are not assigned to a Customer or Associate. ### Shopping Lists A [ShoppingList](/search.md?urn=ctp:api:type:ShoppingList) can contain up to **250** line items and up to **100** text line items. The maximum number of [Shopping Lists](/api/projects/shoppingLists.md) that can be added to a project is **10000000**. If your project contains more shopping lists, the [automatic clean-up task](/api/general-concepts.md#automatic-cleanup) deletes the ones closest to their configured retention. This is determined using `lastModifiedAt + deleteDaysAfterLastModification`. Projects created before January 2020 may still contain Shopping Lists without `deleteDaysAfterLastModification`. In those projects, the automatic cleanup task will continue using the legacy behavior, deleting the least recently modified resources. To avoid your project exceeding its limits, we recommend the following best practices: - Only create Shopping Lists when a user adds a Line Item. - Use shorter retention periods for short-lived Shopping Lists (for example, wedding wishlists). These limits can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#resource-count-limits). ### Carts The maximum number of [Carts](/api/projects/carts.md) that can be added to a project is **10000000**. If your project contains more Carts, the [automatic clean-up task](/api/general-concepts.md#automatic-cleanup) deletes the ones closest to their configured retention. This is determined using `lastModifiedAt + deleteDaysAfterLastModification`. Projects created before January 2020 may still contain Carts without `deleteDaysAfterLastModification`. In those projects, the automatic cleanup task will continue using the legacy behavior, deleting the least recently modified resources. To avoid your project exceeding its limits, we recommend the following best practices: - Only create Carts when a user adds a Line Item. - Set a short retention period to avoid accumulating stale data. - Use shorter retention periods for short-lived Carts (for example, in-store Carts). - Delete Carts once they are converted into Orders. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#resource-count-limits). ### Shipping Methods The maximum number of [Shipping Methods](/api/projects/shippingMethods.md#shippingmethod) that can be added to a project is **100**. The maximum number of Stores that you can assign to a [Shipping Method](/api/projects/shippingMethods.md#shippingmethod) is **100**. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, the project key, and use case. ### Shipping Zones The maximum number of [Zones](/api/projects/zones.md#zone) that can be added to a project is **100**. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, the project key, and use case. ### Order Edits The maximum number of [Order Edits](/api/projects/order-edits.md) that can exist per project is **100000**. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, the project key, and use case. ### Order Search Only Orders from the last **3 months** are indexed and can be retrieved. ## Customers ### Customers The maximum number of [Customers](/api/projects/customers.md#customer) that can be added to a project is **10000000**. The maximum number of [Customer Groups](/api/customers-overview.md#customer-groups) that can be assigned to a Customer is **500** . These limits can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, the project key, and use case. ### Customer Search A maximum of **10000** [addresses](/api/types.md#addresses) per Customer can be indexed for [Customer Search](/api/projects/customer-search.md). The first **10000** addresses in the [Customer](/search.md?urn=ctp:api:type:Customer) `addresses` field are indexed. ### Customer Groups The maximum number of [Customer Groups](/api/projects/customerGroups.md#customergroup) that can be added to a project is **10000**. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, the project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#b2b-hierarchy-and-permission-limits). ### Business Units The hierarchy of [Business Units](/api/projects/business-units.md) is limited to **5** levels. Each top-level Business Unit can have a maximum of **4000** Divisions, including all direct and indirect children. Each [Business Unit](/api/projects/business-units.md) can have up to **2000** [Associates](/search.md?urn=ctp:api:type:Associate), and each [Associate](/search.md?urn=ctp:api:type:Associate) can have up to **5** [AssociateRoleAssignments](/search.md?urn=ctp:api:type:AssociateRoleAssignment). Each [Business Unit](/api/projects/business-units.md) can have up to **500** [Customer Groups](/api/projects/customerGroups.md#customergroup). These limits can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#b2b-hierarchy-and-permission-limits). ### Business Unit Search A maximum of **10000** [addresses](/api/types.md#addresses) per Business Unit can be indexed for [Business Unit Search](/api/projects/business-unit-search.md). The first **10000** addresses in the [BusinessUnit](/search.md?urn=ctp:api:type:BusinessUnit) `addresses` field are indexed. ## Audit Log ### Change History With Audit Log Basic, [Records](/api/history/change-history.md#record) are stored for **1** year. With Audit Log Premium, [Records](/api/history/change-history.md#record) are stored for **3** years. To request a trial of Audit Log Premium, contact the [commercetools support team](https://support.commercetools.com/). ## Configuration ### Stores The number of [Stores](/api/projects/stores.md) is limited to **300000**. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Store's Inventory Supply Channels A [Store](/api/projects/stores.md) can be associated with up to **100** Inventory Supply [Channels](/api/projects/channels.md). This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Store's Product Distribution Channels A [Store](/api/projects/stores.md) can be associated with up to **100** Product Distribution [Channels](/api/projects/channels.md). This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Store's Product Selections A [Store](/api/projects/stores.md) can be associated with up to **100** [Product Selections](/api/projects/product-selections.md). ### Tax Categories The maximum number of [Tax Categories](/api/projects/taxCategories.md#taxcategory) that can be added to a project is **100**. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, the project key, and use case. ## Customize Data and Behavior ### Custom Objects A maximum of **20000000** [Custom Objects](/api/projects/custom-objects.md) can be created. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Product Types A maximum of **1000** [Product Types](/api/projects/productTypes.md#producttype) can be created. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### API Extensions A maximum of **25** [Extensions](/api/projects/api-extensions.md) can be created per project. Each [successful API Extension response](/api/projects/api-extensions.md#response) can include up to **100** [update actions](/api/projects/api-extensions.md#updates-requested). This limit can be increased per project after we review the performance impact. To request an increase, contact the [commercetools support team](https://support.commercetools.com/) and provide your region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#extensibility-and-eventing-limits). Each [Extension](/api/projects/api-extensions.md) can contain up to **3** [expansion paths](/api/general-concepts.md#expansion-paths). The reference expansion itself also has some [limits](/api/limits.md#reference-expansion). ### Subscriptions A maximum of **50** [Subscriptions](/api/projects/subscriptions.md) can be created per project. This limit can be increased per project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. For design alternatives and review criteria, see [Limit increase guidance](/api/limit-increase-guidance.md#extensibility-and-eventing-limits). ## AI tools ### Hosted MCP tool invocations A maximum of **1000000** tool invocations can be made per Project per month. This limit applies to [Managed MCP Servers](/api/projects/managed-mcp-servers.md). This limit can be increased per Project after commercetools reviews its impact. To request an increase, contact the [commercetools support team](https://support.commercetools.com/) and provide the region, Project key, and use case. ## Import API ### Import Containers A maximum of **1000** [Import Containers](/api/import-export/import-container.md#importcontainer) can be created per Project. Import Containers created without a `retentionPolicy` are automatically deleted **72 hours** after creation. Set a [TimeToLiveRetentionPolicy](/api/import-export/import-container.md#timetoliveretentionpolicy) to use a custom duration (within the allowed minimum and maximum). This limit can be increased per Project after we review the performance impact. Contact the [commercetools support team](https://support.commercetools.com/) and provide the region, project key, and use case. ### Import Operations An [Import Operation](/api/import-export/import-operation.md#importoperation) is automatically deleted **48** hours after it is created. Learn [best practices](/api/import-export/best-practices.md#utilize-the-lifetime-of-import-operations) with this limit. ### Import Requests An [Import Request](/api/import-export/overview.md#what-are-importrequests) may contain a maximum of **20** resources to import. Learn [best practices](/api/import-export/best-practices.md#import-large-data-sets) with this limit. ## Related pages - [Area overview page with navigation](/api.md) - [Previous page: Errors](/api/errors.md) - [Next page: GraphQL](/api/graphql.md) - [Search documentation and API specs](/search.md)