Limit increase guidance

Limits protect platform stability, indexing performance, and predictable response times. Some limits are hard architectural boundaries. Other limits can be reviewed per project.

Why limits exist

Limits protect critical parts of the platform, such as document storage, query execution, indexing, and synchronous request handling. Without these boundaries, one workload could degrade performance for other workloads in the same region.

When you approach a documented limit, first identify what is creating the pressure:

• object size
• query shape
• indexing volume
• synchronous business logic
• total resource count

The best solution often depends more on that pressure point than on the resource name.

Evaluate the limit first

Before you request an increase, answer the following questions:

1. Is this a hard architectural limit or a project-specific limit?
2. Is the workload synchronous or asynchronous?
3. Is the pressure caused by document size, query depth, indexing fan-out, or total resource count?
4. Can you reduce the load by partitioning data, batching requests, or changing the integration pattern?
5. If you raise the limit, what part of the system becomes more expensive to execute or maintain?

If the answer points to object growth, deep pagination, or heavy synchronous processing, redesign is often better than requesting an increase.

Limits that aren't increased

Some limits are fixed because increasing them would create disproportionate performance or stability risk.

Document size and searchable field size

Use a different data model when you approach these limits:

• Split large documents into smaller resources.
• Move large blobs or media to external storage and keep only a reference.
• Keep searchable text short, and store long-form content outside the indexed field.
• Reduce the number of Product Variants, localized values, or Custom Fields stored in a single document.

Deep pagination and aggregate-style queries

Use a different retrieval pattern instead:

• Replace offset-based pagination with the iterate over all elements pattern.
• Narrow result sets with selective predicates.
• Turn off total when you do not need it.
• Export data to an external analytics or search system for large-scale counting and reporting.

Expansion depth and query complexity

Use these alternatives when you approach those limits:

• Fetch only the fields you need.
• Split large requests into smaller calls.
• Move non-critical follow-up work to asynchronous processing.
• Reshape your data model so fewer nested lookups are needed at request time.

Import request and retention boundaries

These limits are designed for predictable background processing. When you approach them, batch data differently and design your import workflow around the documented retention window.

Limits that may be increased after review

Project-specific increases are usually reviewed when the use case is valid and the performance impact is understood. The key question is not only how high the limit should go, but also what cost that higher value introduces.

Resource count limits

These increases are usually evaluated based on:

• growth rate
• cleanup and retention strategy
• average object size
• read and write patterns
• whether data can be partitioned across projects, Stores, or containers

Product and pricing model limits

These increases are usually evaluated based on:

• total Product and Product Variant count
• number of prices, Customer Groups, Stores, or Channels per Product
• expected Product document size
• search and indexing requirements
• frequency of catalog and pricing updates

Discount and checkout limits

These increases are usually evaluated based on:

• predicate complexity
• number of targeted Products, Stores, or regions
• cart size and checkout behavior
• whether broader rules can replace many narrow rules

B2B hierarchy and permission limits

These increases are usually evaluated based on:

• hierarchy depth
• associates per Business Unit
• role assignment volume
• how often permission checks happen in synchronous flows
• whether a flatter structure or different segmentation model is possible

Extensibility and eventing limits

These increases are usually evaluated based on:

• peak request or message volume
• average and peak execution time
• whether synchronous logic can move to the application or to asynchronous workflows
• whether multiple handlers can be consolidated behind one endpoint or queue

Choose an alternative before you request an increase

When you approach a limit, use the following alternatives first.

Reduce object size

• Keep average resource size small.
• Remove redundant Custom Field data.
• Store large text, binary data, and infrequently used payloads outside the resource.

Partition the data model

• Use Stores to reduce the amount of product and price data loaded in synchronous flows.
• Split high-density Custom Objects across multiple containers.
• Consider separate projects when the data model is truly independent by region, brand, or business domain.

Change the integration pattern

• Use the Import API for high-volume background ingestion.
• Use Subscriptions instead of polling.
• Keep validation or enrichment in your application when synchronous API Extensions are not required for every client.

Simplify retrieval patterns

• Replace deep pagination with cursor-style iteration.
• Fetch only the fields you need in GraphQL.
• Limit reference expansion to the cases where it reduces real request cost.
• Export analytics and reporting workloads to external systems.

Simplify pricing, search, and hierarchy models

• Use fewer Product Variants per Product when possible.
• Prefer Standalone Prices when embedded price volume would inflate Product documents.
• Consolidate Product Selections, Stores, and Customer Groups where native behavior does not require one-to-one mapping.
• Flatten Business Unit hierarchies and reduce per-user role fan-out.