Centra has a few different APIs used for different purposes. This documentation explains all the different APIs used to connect to Centra.
From one developer to another, we’re here to help you!
Building an experience on Centra’s APIs? Sign up to become a partner in order to enter the certification path, be invited to webinars and get direct Slack channel support with Centra after you are certified.
What are you waiting for? Get in touch to get going with Centra.
Installation#
Each API has its own plugin. Some of the APIs need activation from Centra, such as the subscription API, but the other ones can be easily enabled by adding a new plugin to your store.
To enable a plugin in Centra, go to SYSTEM, then select STORES. Select what store you want your API to connect to and select the API in the list of plugins. You will need administration rights to have access to SYSTEM.
Endpoints#
Every API installed in Centra gets its own API-endpoint. This endpoint will then be the prefix of every API-call. In the documentation, this value is called <base>.
Authentication#
For authentication we use the API key, which is a shared secret generated in the Plugin settings of the API. You can use the API-authorization: foo header with the token. The overview section of each API Reference might also define other rules of how to authenticate.
Example request:
curl -H "API-Authorization foo" <base>/orders
Rate limiting#
Rate limiting is a mechanism which protects our APIs and underlaying servers from being overloaded. We try to detect both sudden bursts of requests, which can overflow our receive queues, as well as prolonged increased series of API requests, threatening to overload our internal server resources over longer period of time. Monitoring of those rate limits can also give Centra a good idea of how much resources your integration needs, and how scalable it will be in the future.
For now, rate limits are only introduced to our GraphQL API. In the future, we will introduce them in other APIs as well.
Types of rate limits introduced:
Total number of requests - to avoid too many requests to the server, we limit their number
Sum of query complexities of those requests - more complex query generally requires more time and resources to be processed
Total number of mutations among those requests - another layer of complexity that can’t be calculated, so we limit their number
Each of those will be calculated within two timeframes:
10 seconds - ensures that there is no sudden short-term burst that can overwhelm the server
1 hour - ensures that there is no prolonged pressure on the server
[REST] Checkout API#
If you are building a front end for your brand or DTC store, either as a website or a mobile app, you should look into using Checkout API. It's our hybrid webshop API, able to operate both in Client and Server mode, giving you access to products catalog, prices, payments, checkout, shipping options, vouchers, anything you need to build a webshop. To read more about building a front end using Checkout API, visit Creating Front End for Centra store section.
[REST] Shop API#
Shop API is an older webshop API, which only works in authenticated Server mode. It is stateless, operates directly on selections (instead of sessions), and is not aware of the end-user context the way Checkout API is. It's not recommended to be used to build webshops directly, but due to its nature of always serving all of the data, it becomes very useful when implemented on server middle-ware for cache building and/or static page generation.
[REST] Integration API (Order API)#
If your integration takes care of orders after they are created in Centra, you can be interested in using Order API. It covers lots of functions, like WMS integrations, Return Management Systems, Stock management, etc. For those orders you may want to update existing Orders, create and modify Shipments, read or manipulate Stock, or read/create/update Returns. You also have access to Customer data and the Supplier Module. With the right API plugin config, you will also be able to insert Orders directly into Centra (e.g. when migrating from another e-commerce platform), or manipulate Vouchers (e.g. generating cloned vouchers for your influencers). To learn more, see Order API reference.
Order API was originally built as a pick-and-pack service integration API, with a lot of functionality added over the years. It is, however, very far from being feature-complete. For this reason we are developing GraphQL API.
[GQL] GraphQL Integration API#
This is designed to be the last integration API we will ever need. It gives you granular access to almost all parts of Centra, including the parts previously available only from the backend UI. The only limit is your imagination.
GraphQL is now officially out of Beta, and it has more features than ever. A full ERP integration guide using GraphQL is available for anyone looking to replace their old SOAP or REST integration. More on product setup can be found in the PIM guide. Besides that, GQL API references section offers lots of copy-pastable examples, both for DtC as well as Wholesale use cases. To learn more, see GraphQL Integration API.
Oh by the way, did we mention that GraphQL offers 100% code coverage? Integral part of the API are the automatically generated GraphQL API specifications for Centra Integration API. This means that everyone who has the basic grasp of GQL APIs in general, and knows the syntax used, is able to immediately use any and all of the available functions. Is there a use case you can think of how to implement? Now you no longer need documentation pages with instructions, now the available options are at your fingertips, with suggestion, immediate validation and basically self-writing code. You really have to try it to believe it. And once you do, you can use it to do anything with your Centra. Within reason, right?
[SOAP] ERP system integrations (deprecated)
Many customers use the ERP systems, like Navision, to store the master of the data for Products, Customers, Pricelists and so on. If you need to integrate to those systems, you may be interested in our SOAP API. Since in this case Centra works in a slave mode, this is currently the only API that allows you to modify Centra Products, Pricelists, Shipping, Invoices, etc. We very rarely add new features to this API, but we also have comprehensive docs covering most of use cases required when working with an ERP system. They are all described in our ERP integration guide.
[REST] Subscription API (deprecated)
This API was replaced by the new subscriptions functionality.
Centra APIs and functions#
Existing Limitations#
Order API can be used to update stock values, but only for one Warehouse per each plugin instance.
Order API only supports attributes on product and variant level. They are only returned through the GET /products endpoint.
SOAP API only supports custom attributes built into existing plugins, like Ingrid. It does not support custom attributes defined in the customer config.
Checkout API has limited support for Wholesale stores. We can recommend Centra Showroom for your B2B store, if you'd like.
Shop API has limited support for Wholesale stores. Again, we have B2B Showroom. It's great.
Order API can be used to create very basic vouchers, or to clone voucher templates previously defined in the Centra AMS.
Checkout API can only be used to view the historical orders of currently logged in user. As a webshop API, it doesn't have access to other orders unrelated to the shopper.
Shop API can only be used to view the historical orders of currently logged in user.
With SOAP, each event should only be fetched once, synced with the ERP and then marked as done in Centra. After that, you can no longer fetch it from Centra directly, unless there's been changes that need to be synced to the ERP as well.