The Sky's (almost) the Limit

We do our best to avoid hard limits in the API when we can, but we make exceptions in a few cases in order to deliver the best performance possible to our customers.

XP Length

The maximum length for any given xp object is 8000 characters.

XP is a key example of our Flexibility Over Features philosophy in practice. It's a mechanism for adding properties to an object that your conceptual model needs but are not natively supported in OrderCloud. Like with anything, there are still best practices that should be followed when storing data in xp. Following the best practices outlined in that document will likely help keep your xp to a manageable size; however if you do find yourself getting close to the limit, it might be time to consider mapping your resource to an external data store to retrieve that additional information when needed.

Generated Variants

The maximum number of generated variants for a given product is 1500.

Generating Variants creates a Variant for each unique combination of Spec Options assigned to a given product. For example, a product with six specs that had three options each would result in 729 unique variations and generating variants would succeed. If you added a fourth option to each spec, the limit would be exceeded and generating variants would fail.

Auto Apply Promotions

The maximum number of promotions that will be applied to an order in a single call to v1/orders/{direction}/{orderID}/applypromotions or v1/cart/applypromotions is 100.

If you need to evaluate more promotions, you can make the API call again.

Products per ProductCollection

The maximum number of products in a given collection is 500.

This limit is provided to ensure optimal performance when retrieving ProductCollection entries. There is no limit on the number of ProductCollections a user can have.

Unique XP Keys on Products and Orders

We recommend sticking to around 100 unique xp keys (not values) on Products, Orders, and LineItems. For Orders especially, which have LineItem and Product xp nested inside the search document, the keys can add up quickly. If you have 100 unique keys on Order xp, LineItem xp, and Product xp respectively, your total unique xp keys for Order search documents would be 300.

These resources are optimized for searching and filtering, and at a certain point, if there are too many unique xp keys, the xp will be flattened and your search and filter capabilities will be limited. This is just one of several reasons to keep your Product and Order xp schemas consistent and limited to necessary information.

LineItems per Submitted Order

How many LineItems can you add to an Order? Well, it depends.

We have complex processes for indexing and returning submitted Orders from the API. This means extraneous data related to LineItems and their respective Product can have an influence on the limit. Staying under a few hundred LineItems per Order would be a good rule of thumb. If your marketplace needs Orders with more LineItems than that, please reach out so we can learn more about your use case and make recommendations.

Unlike the other limits discussed in this guide, this is more of a "soft" limit. The API won't prevent you from submitting an order with more LineItems than we can manage performantly, but it may not be able to index the order after it's been submitted, which will prevent it from returning in a list.

Deep Paging

This one is another soft limit, but we strongly advise against requesting pages greater than 30 to avoid performance issues.

We recommend using what we refer to as the LastID Method for the optimal performance:

1. Make your first list call with page=1&pageSize=100&sortBy=ID as query parameters

2. Keep track of the ID of the last item returned in the list

3. In subsequent calls, always request page=1&pageSize=100&sortBy=ID&ID=>{lastID}

4. Stop paginating when the query returns an empty Items array

Still have questions?
Ask in our Community Channel

Content Powered By