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](https://docs.commercetools.com/api/limit-increase-guidance). The current value of a project's limits can be accessed via the `limits` field on the [GraphQL API](https://docs.commercetools.com/api/graphql). 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](https://docs.commercetools.com/api/ctp:api:type:ResourceSizeLimitExceededError) error. This limit isn't related to the general request 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. ## Field content size For performance reasons, the maximum size of a searchable field within an [AttributeDefinition](https://docs.commercetools.com/api/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](https://docs.commercetools.com/api/limits#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](https://docs.commercetools.com/api/general-concepts#pagination), the maximum offset is 10000. The `total` field of [PagedQueryResult](https://docs.commercetools.com/api/general-concepts#pagedqueryresult) is limited to the maximum `offset` when the results are filtered with a [Query Predicate](https://docs.commercetools.com/api/predicates/query). See our [performance tips](https://docs.commercetools.com/api/performance-tips#query-and-retrieve-data) for best practices in optimizing queries. For guidance on when to redesign instead of requesting a higher query limit, see [Limit increase guidance](https://docs.commercetools.com/api/limit-increase-guidance#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](https://docs.commercetools.com/api/general-concepts#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](https://docs.commercetools.com/api/graphql#querycomplexitylimitexceeded) error is returned. ## Load testing Visit [Load testing](https://docs.commercetools.com/api/load-testing) to learn about the [limits](https://docs.commercetools.com/api/load-testing#obligations-and-responsibilities) and [exclusion periods](https://docs.commercetools.com/api/load-testing#exclusion-periods) that apply. # Authorization ## External OAuth 2.0 endpoint timeouts When using tokens issued by an [external OAuth 2.0 introspection endpoint](https://docs.commercetools.com/api/authorization#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](https://docs.commercetools.com/api/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](https://docs.commercetools.com/api/limit-increase-guidance#product-and-pricing-model-limits). # Product Catalog ## Categories A maximum number of 10000 [Categories](https://docs.commercetools.com/api/projects/categories) 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](https://docs.commercetools.com/api/limit-increase-guidance#product-and-pricing-model-limits). ## Product Variants A maximum number of 100 variants can be specified on a [Product](https://docs.commercetools.com/api/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. ## Product Search A maximum number of 10000 [StandalonePrices](https://docs.commercetools.com/api/projects/standalone-prices#standaloneprice) per [Product](https://docs.commercetools.com/api/ctp:api:type:Product) can be indexed for [Product Search](https://docs.commercetools.com/api/projects/product-search). A maximum number of 15000 [ProductSelections](https://docs.commercetools.com/api/projects/product-selections#productselection) per Product can be indexed for Product Search. A maximum number of 15000 [Stores](https://docs.commercetools.com/api/projects/stores#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](https://docs.commercetools.com/api/projects/product-search#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](https://docs.commercetools.com/api/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](https://docs.commercetools.com/api/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](https://docs.commercetools.com/api/projects/product-projection-search#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](https://docs.commercetools.com/api/projects/attribute-groups) can be created per project. ## Product Tailoring A maximum number of 100000000 [Product Tailoring](https://docs.commercetools.com/api/projects/product-tailoring) 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. # Pricing and Discounts ## Standalone Prices The maximum number of 50000 [StandalonePrices](https://docs.commercetools.com/api/projects/standalone-prices#standaloneprice) can be specified per [ProductVariant](https://docs.commercetools.com/api/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](https://docs.commercetools.com/api/limit-increase-guidance#product-and-pricing-model-limits). ## Embedded Prices A maximum number of 100 [Embedded Prices](https://docs.commercetools.com/api/types#price) can be specified per [ProductVariant](https://docs.commercetools.com/api/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](https://docs.commercetools.com/api/projects/standalone-prices) for an alternative way for pricing your products. For more guidance, see [Limit increase guidance](https://docs.commercetools.com/api/limit-increase-guidance#choose-an-alternative-before-you-request-an-increase). ## Cart Discounts The number of active [CartDiscounts](https://docs.commercetools.com/api/projects/cartDiscounts#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](https://docs.commercetools.com/api/projects/cartDiscounts#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](https://docs.commercetools.com/api/limit-increase-guidance#discount-and-checkout-limits). ## Cart Discount's Stores A [CartDiscount](https://docs.commercetools.com/api/ctp:api:type:CartDiscount) can be associated with up to 500 [Stores](https://docs.commercetools.com/api/projects/stores). 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](https://docs.commercetools.com/api/ctp:api:type:Cart) can contain up to 10 [DiscountCodes](https://docs.commercetools.com/api/projects/discountCodes#discountcode). A [DiscountCode](https://docs.commercetools.com/api/ctp:api:type:DiscountCode) can be associated with up to 10 [CartDiscounts](https://docs.commercetools.com/api/projects/cartDiscounts#cartdiscount). ## Discount Groups The maximum number of [DiscountGroups](https://docs.commercetools.com/api/projects/discount-groups#discountgroup) that can exist in a Project is 100. A DiscountGroup can contain up to 100 [CartDiscounts](https://docs.commercetools.com/api/projects/cartDiscounts#cartdiscount). ## Product Discounts The maximum number of [ProductDiscounts](https://docs.commercetools.com/api/projects/productDiscounts#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](https://docs.commercetools.com/api/projects/payment-methods#paymentmethod). The limits apply independently per Customer or Associate and do not overlap. A Project can contain up to 1000000 [PaymentMethods](https://docs.commercetools.com/api/projects/payment-methods#paymentmethod) that are not assigned to a Customer or Associate. ## Shopping Lists A [ShoppingList](https://docs.commercetools.com/api/ctp:api:type:ShoppingList) can contain up to 250 line items and up to 100 text line items. The maximum number of [Shopping Lists](https://docs.commercetools.com/api/projects/shoppingLists) that can be added to a project is 10000000. If your project contains more shopping lists, the [automatic clean-up task](https://docs.commercetools.com/api/general-concepts#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](https://docs.commercetools.com/api/limit-increase-guidance#resource-count-limits). ## Carts The maximum number of [Carts](https://docs.commercetools.com/api/projects/carts) that can be added to a project is 10000000. If your project contains more Carts, the [automatic clean-up task](https://docs.commercetools.com/api/general-concepts#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](https://docs.commercetools.com/api/limit-increase-guidance#resource-count-limits). ## Shipping Methods The maximum number of [Shipping Methods](https://docs.commercetools.com/api/projects/shippingMethods#shippingmethod) 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. ## Shipping Zones The maximum number of [Zones](https://docs.commercetools.com/api/projects/zones#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](https://docs.commercetools.com/api/projects/order-edits) 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](https://docs.commercetools.com/api/projects/customers#customer) that can be added to a project is 10000000. The maximum number of [Customer Groups](https://docs.commercetools.com/api/customers-overview#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](https://docs.commercetools.com/api/types#addresses) per Customer can be indexed for [Customer Search](https://docs.commercetools.com/api/projects/customer-search). The first 10000 addresses in the [Customer](https://docs.commercetools.com/api/ctp:api:type:Customer) `addresses` field are indexed. ## Customer Groups The maximum number of [Customer Groups](https://docs.commercetools.com/api/projects/customerGroups#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](https://docs.commercetools.com/api/limit-increase-guidance#b2b-hierarchy-and-permission-limits). ## Business Units The hierarchy of [Business Units](https://docs.commercetools.com/api/projects/business-units) 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](https://docs.commercetools.com/api/projects/business-units) can have up to 2000 [Associates](https://docs.commercetools.com/api/projects/business-units#ctp:api:type:Associate), and each [Associate](https://docs.commercetools.com/api/ctp:api:type:Associate) can have up to 5 [AssociateRoleAssignments](https://docs.commercetools.com/api/projects/business-units#ctp:api:type:AssociateRoleAssignment). Each [Business Unit](https://docs.commercetools.com/api/projects/business-units) can have up to **500** [Customer Groups](https://docs.commercetools.com/api/projects/customerGroups#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](https://docs.commercetools.com/api/limit-increase-guidance#b2b-hierarchy-and-permission-limits). ## Business Unit Search A maximum of 10000 [addresses](https://docs.commercetools.com/api/types#addresses) per Business Unit can be indexed for [Business Unit Search](https://docs.commercetools.com/api/projects/business-unit-search). The first 10000 addresses in the [BusinessUnit](https://docs.commercetools.com/api/ctp:api:type:BusinessUnit) `addresses` field are indexed. # Audit Log ## Change History With Audit Log Basic, [Records](https://docs.commercetools.com/api/history/change-history#record) are stored for 1 year. With Audit Log Premium, [Records](https://docs.commercetools.com/api/history/change-history#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](https://docs.commercetools.com/api/projects/stores) 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](https://docs.commercetools.com/api/projects/stores) can be associated with up to 100 Inventory Supply [Channels](https://docs.commercetools.com/api/projects/channels). 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](https://docs.commercetools.com/api/projects/stores) can be associated with up to 100 Product Distribution [Channels](https://docs.commercetools.com/api/projects/channels). 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](https://docs.commercetools.com/api/projects/stores) can be associated with up to 100 [Product Selections](https://docs.commercetools.com/api/projects/product-selections). ## Tax Categories The maximum number of [Tax Categories](https://docs.commercetools.com/api/projects/taxCategories#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](https://docs.commercetools.com/api/projects/custom-objects) 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](https://docs.commercetools.com/api/projects/productTypes#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](https://docs.commercetools.com/api/projects/api-extensions) can be created per project. Each [successful API Extension response](https://docs.commercetools.com/api/projects/api-extensions#response) can include up to 100 [update actions](https://docs.commercetools.com/api/projects/api-extensions#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](https://docs.commercetools.com/api/limit-increase-guidance#extensibility-and-eventing-limits). Each [Extension](https://docs.commercetools.com/api/projects/api-extensions) can contain up to 3 [expansion paths](https://docs.commercetools.com/api/api/general-concepts#expansion-paths). The reference expansion itself also has some [limits](https://docs.commercetools.com/api/limits#reference-expansion). ## Subscriptions A maximum of 50 [Subscriptions](https://docs.commercetools.com/api/projects/subscriptions) 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](https://docs.commercetools.com/api/limit-increase-guidance#extensibility-and-eventing-limits). # Import API ## Import Containers A maximum of 1000 [Import Containers](https://docs.commercetools.com/api/import-export/import-container#importcontainer) 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. ## Import Operations An [Import Operation](https://docs.commercetools.com/api/import-export/import-operation#importoperation) is automatically deleted 48 hours after it is created. Learn [best practices](https://docs.commercetools.com/api/import-export/best-practices#utilize-the-lifetime-of-import-operations) with this limit. ## Import Requests An [Import Request](https://docs.commercetools.com/api/import-export/overview#what-are-importrequests) may contain a maximum of 20 resources to import. Learn [best practices](https://docs.commercetools.com/api/import-export/best-practices#import-large-data-sets) with this limit.