How to optimize your stock queries

Created August 19th at 2:09pm

When integrating with Centra’s Integration API to fetch stock information, it might be tempting to request all available stock fields – but that’s often unnecessary and potentially costly in terms of performance.

In almost all integration scenarios – such as syncing available stock to a frontend, marketplace, or third-party system – what you really care about is how much stock is available to allocate right now. This is exactly what the freeToAllocateQuantity field provides.

It reflects the actual sellable stock: It accounts for allocations, and other internal logic that affects what’s available to sell.
It’s fast to compute: Unlike other stock fields (e.g., availableQuantity, allocatedQuantity, incomingQuantity, etc.), which may require more intensive backend calculations, freeToAllocateQuantity is optimized for performance.
Clean and safe integration: You avoid pulling unnecessary data and reduce load on the system, keeping both your queries and Centra’s infrastructure lean.
It’s free in terms of query complexity: Unlike other stock fields, which are expensive scalars for our complexity algorithm, freeToAllocateQuantity doesn’t increase your complexity score. This means you are decreasing the chance of being slowed down by the complexity-based rate limits.

What to avoid#

Unless you have a very specific need (e.g., warehouse operations, custom allocation logic), you should not query other stock-related fields. These fields are not only more expensive to compute but also often irrelevant for external integrations.

Example#

Consider this query:

query variantsWithStock($withAdditionalStockInfo: Boolean! = false) {
  productVariants(limit: 10, where: {status: [ACTIVE]}) {
    id
    product { id }
    name
    
    stockTotals { # a summary of this variant's availability
      freeToAllocateQuantity
      availableQuantity @include(if: $withAdditionalStockInfo)
      demandQuantity @include(if: $withAdditionalStockInfo)
    }
    
    stock(limit: 20) { # per size and warehouse
      freeToAllocateQuantity
      availableQuantity @include(if: $withAdditionalStockInfo)
      demandQuantity @include(if: $withAdditionalStockInfo)
    }
  }
}

It has a low query complexity of 230, and is relatively fast to compute. But if you pass { "withAdditionalStockInfo": true } in the variables, you will find out that it’s slower, (most likely) doesn’t give you any different information, and costs a few more times in terms of complexity.

More information#

Our API provides built-in documentation on stock.

And here you can find the detailed description of our query complexity calculation.