Go to docs navigationGo to article contentGo to table of contentsGo to footer navigation

The best ways of using Integration API

Last updated

The Integration API is designed specifically for backend-to-backend communication. It provides extensive access to data and functionality, but it is not intended for direct use in frontend applications. We put a lot of effort into the API performance, but nevertheless, it’s a business logic-heavy application that is not designed to handle high-traffic scenarios. For any frontend operations, please use the dedicated APIs built for customer-facing use cases. To learn more, visit the DTC API documentation.

Do not use in the frontend#

Connecting the Integration API directly to your frontend store can lead to significant issues, including exposure of sensitive data and degraded performance. Additionally, such usage is likely to be rate-limited.

Do not use via a frontend proxy#

Implementing a thin proxy layer between your frontend and this API is also discouraged, as it introduces performance issues. We have seen cases when this approach resulted in substantial performance degradation.

In limited scenarios, the Integration API may be used to serve requests from an internal administration panel with low traffic, or from a custom PoS that requires stock per warehouse or brick-and-mortar data. The main point is that any user interaction in a system with potentially high traffic (a typical web store) should be approached with caution.

If you found an Integration API function that you feel is missing from DTC API, please get in touch with us. We welcome your feedback and suggestions for improvement.

Typical use cases#

  • Importing or updating product catalog (products, variants, sizes, categories, media, etc.)
  • Fetching data for report generation
  • Massive updates (for example, to assign attributes to all customers or change categories)
  • Syncing stock or other data

Please avoid “fetching all orders/products/etc.” to get in sync between Centra and your system, as it’s slow and requires you to perform lots of extra operations.

It may also be tempting to fetch the latest changes based on the updatedAt field, and it works relatively fine in some scenarios. But since it doesn’t capture changes to related entities, you could miss some important updates. For example, Product.updatedAt changes on direct product updates, but not necessarily when its variants, displays, custom attributes or translations are updated.

All these (and more) cases are properly handled by the Events system which will be a much better approach that guarantees that your app won’t miss any important updates.

General recommendations#

Optimize queries#

GraphQL queries in this API can be heavy, as they allow access to large datasets and complex relationships. Always try to optimize your queries to request only the fields and entities you actually need. Avoid broad queries that fetch unnecessary data, as this may lead to increased latency and higher system load.

Use caching where possible#

Certain data - such as countries, currencies, or other reference information - changes infrequently. To improve performance and reduce redundant calls, implement caching mechanisms for such resources.

The same applies to complex entities like size charts or categories. In these cases, a more advanced cache may be necessary, offering greater benefits.

Use the Events system#

While the Integration API allows you to fetch large volumes of data, doing so is rarely efficient. To stay informed about changes on Centra’s side, consider using the Events system, which is designed to notify your backend only of the changes and updates that matter to your business needs. When it comes to updating your cache data, this system is the best way.

Use batch operations#

The Integration API supports many operations that let you modify multiple entities at once. Try to combine multiple updates into a single batch operation whenever it’s possible. These mutations are:

  • assignAttributesBatch / unassignAttributesBatch
  • setPricesBatch / setAlteredPricesBatch
  • setStock
  • setTranslations
  • setCampaignVariants / unsetCampaignVariants
  • setCategoryDisplays / unsetCategoryDisplays
  • createMediaBatch
  • and others

When sending many subsequent requests, keep an HTTP/2 connection open to reduce network time.

Use gradual updates#

Send updates from your side to Centra since the last sync, not a full sync of an entire catalog, prices, or stock values.

By following these practices, you will ensure efficient, secure, and maintainable integrations with the Integration API.