Documentation

Limits

To assure good performance for every project using commercetools Composable Commerce, the API 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.

The current value of a project's limits can be accessed via the limits field on the GraphQL API. 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 error. This limit isn't related to the general request size. Even if a request is smaller than 16 megabytes, if it causes the resulting document to go over this limit, the request will fail.

For best performance, we recommend limiting your average documents to no more than 100 KB, and large documents (for example, a Product with many Product Variants, or an Order with many Line Items) to 2 MB.

Field content size

For performance reasons, the maximum size of a searchable field within an AttributeDefinition can not exceed 10 922 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.

Slugs

A Slug must match the pattern [a-zA-Z0-9_\-]{2,256}, hence they are limited to 256 characters.

Queries

Within a query, up to 500 elements can be fetched.

When using pagination, the maximum offset is 10 000. The total field of PagedQueryResult is limited to the maximum offset when the results are filtered with a Query Predicate.

See our performance tips for best practices in optimizing queries.

Update actions per request

For performance reasons, the maximum number of update actions within a single request is limited to 500.

GraphQL

Queries with a complexity score greater than or equal to 20 000 are not executed, and a QueryComplexityLimitExceeded error is returned.

Authorization

External OAuth 2.0 endpoint timeouts

If a project is using OAuth 2.0 access tokens issued by an external OAuth 2.0 introspection endpoint, the OAuth 2.0 service must respond in 500 ms, including network latency.

If the introspection endpoint does not respond within the time limit, or no connection could be established, the overall request will fail with a 504 Gateway Timeout or 502 Bad Gateway HTTP status code and an ExternalOAuthFailed 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. Please contact Support via the Support Portal and provide the region, project key, and use case.

Product Catalog

Categories

A maximum number of 10 000 Categories can be created.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Product Variants

A maximum number of 100 variants can be specified on a Product.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Attribute Groups

A maximum number of 100 Attribute Groups can be created per project.

Product Tailoring BETA

A maximum number of 100 000 000 Product Tailoring can be created per project.

This limit can be increased per project after we review its impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Pricing and Discounts

Standalone Prices

The maximum number of 50 000 StandalonePrices can be specified per ProductVariant.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, the project key, and use case.

Embedded Prices

A maximum number of 100 Embedded Prices can be specified per ProductVariant.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

If you want to go over this limit, you can also use StandalonePrices for an alternative way for pricing your products.

Tax Categories

The maximum number of Tax Categories that can be added to a project is 100.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, the project key, and use case.

Cart Discounts

The number of active CartDiscounts 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 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).

These limits can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Cart Discount's Stores

The number of Stores configured for a CartDiscount is limited to 500.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Discount Codes

The number of DiscountCodes in a Cart is limited to 10. The number of CartDiscounts in a DiscountCode is limited to 10.

Product Discounts

The maximum number of ProductDiscounts that can be active at the same time is 500.

Carts, Orders, and Shopping Lists

Shopping Lists

A ShoppingList can contain up to 250 line items and up to 100 text line items.

The maximum number of Shopping Lists that can be added to a project is 10 000 000. If your project contains more shopping lists, the automatic clean-up task will delete the ones least recently modified.

These limits can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Carts

The maximum number of Carts that can be added to a project is 10 000 000. If your project contains more carts, the automatic clean-up task will delete the ones least recently modified.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Shipping Methods

The maximum number of Shipping Methods that can be added to a project is 100.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, the project key, and use case.

Shipping Zones

The maximum number of Zones that can be added to a project is 100.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, the project key, and use case.

Order Edits

The maximum number of Order Edits that can exist per project is 100 000.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, the project key, and use case.

Customers

Customers

The maximum number of Customers that can be added to a project is 10 000 000.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, the project key, and use case.

Customer Groups

The maximum number of Customer Groups that can be added to a project is 1 000.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, the project key, and use case.

Business Units

The hierarchy of Business Units is limited to 5 levels.

Each top-level Business Unit can have a maximum of 4 000 Divisions, including all direct and indirect children.

Each Business Unit can have up to 2 000 Associates.

Each Associate can have up to 5 AssociateRoleAssignments.

These limits can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Audit Log

Records

By default, Audit Log stores Records for 1 year.

Audit Log Premium stores Records for 3 years.

To request a trial of Audit Log Premium, please contact Support via the Support Portal.

Configuration

Stores

The number of Stores is limited to 300 000.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Store's Inventory Supply Channels

The number of Inventory Supply Channels configured for a Store is limited to 100.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Store's Product Distribution Channels

The number of Product Distribution Channels configured for a Store is limited to 100.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Store's Product Selections

The number of Product Selections configured for a Store is limited to 100.

Customize Data and Behavior

Custom Objects

A maximum of 20 000 000 Custom Objects can be created.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Product Types

A maximum of 1 000 Product Types can be created.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

API Extensions

A maximum of 25 Extensions can be created per project.

Subscriptions

A maximum of 50 Subscriptions can be created per project.

This limit can be increased per project after we review the performance impact. Please contact Support via the Support Portal and provide the region, project key, and use case.

Import API

Import Operations

An Import Operation is automatically deleted 48 hours after it is created.

Learn best practices with this limit.

Import Requests

An Import Request may contain a maximum of 20 resources to import.

Learn best practices with this limit.