A website rarely stands alone. An online store has to send orders to the accounting system, fetch shipping rates, update stock from a supplier and notify customers when the parcel has shipped. All of it happens through APIs: fixed ways for systems to talk to each other.
Here we go through how to choose the right way to integrate, what you need to decide before anyone writes code, and how to avoid the two things that most often go wrong: keys that leak, and a site that stalls when the other system does. Which ready-made integrations exist depends a lot on your choice of platform.
What an API is, in brief
An API is a set of addresses another system makes available, and rules for what you can send and get back. Your site sends a request to, say, /orders with a key that shows who it is, and gets a response back, usually in JSON. Most web APIs are built as REST, but GraphQL, gRPC and webhooks are also widespread. We go through the differences in the guide to REST, GraphQL and gRPC. For the rest of this guide, it’s enough to know that every call goes over the internet, takes time and can fail.
Three ways to integrate
| Ready-made plugin | Integration platform | Your own integration | |
|---|---|---|---|
| Example | A plugin from the shipping or accounting system | Zapier, Make or n8n between two systems | Code in your theme or a custom plugin |
| Suits | Standard tasks with well-known systems | Simple flows with low volume | Special rules, large volumes, several systems |
| Cost | A license, often low | A monthly subscription that rises with the number of runs | Development and maintenance |
| Risk | You depend on the plugin’s quality | Yet another system and login to keep track of | Someone has to own the code |
Start by checking whether there’s a maintained plugin from one of the two vendors. It solves the vast majority of standard tasks. An integration platform is good for trying out a flow or for things that happen a few times a day. Your own code makes sense when the rules are your own, or when the volume makes the other solutions expensive or slow.
What to decide first
Most integrations that go wrong go wrong because nobody decided which system is right. If both the store and the inventory system can change a product, which one wins? For each type of data, decide where it’s owned: products and prices perhaps in your ERP, orders in the store, customers in both. Then you also know which way data should flow.
Next, decide how fast it needs to be. Stock status on a popular product may need to be updated within minutes, while bookkeeping can happily happen at night. Real time is more expensive and more fragile than a fixed run every fifteen minutes, so only choose it where it matters. And decide what should happen when the other system is down: should the order still go through, and who gets notified? Finally, read the API’s documentation for limits on the number of calls and for a test environment, so you don’t test against real data.
The keys stay on the server
An API key is a password. Call an API that requires a key directly from the browser’s JavaScript, and the key sits in the code, which any visitor can read. Instead, the call has to go from your server: the browser asks your site, your site asks the API with the key, and only the response is passed on. In WordPress a call typically looks like this, with the key in wp-config.php and the response stored in a transient, so the API isn’t called for every visitor:
// wp-config.php: define( 'SHIPPING_API_KEY', '...' );
function clypper_shipping_rates() {
$rates = get_transient( 'shipping_rates' );
if ( false !== $rates ) {
return $rates;
}
$response = wp_remote_get( 'https://api.example.com/v1/rates', [
'timeout' => 5,
'headers' => [ 'Authorization' => 'Bearer ' . SHIPPING_API_KEY ],
] );
if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
return []; // use a default rate, and log the error
}
$rates = json_decode( wp_remote_retrieve_body( $response ), true );
set_transient( 'shipping_rates', $rates, HOUR_IN_SECONDS );
return $rates;
}Give the key as few permissions as possible, for example read-only access if the integration only fetches data. If you receive webhooks, check the signature on every message, so no one else can send fake orders or status updates to your site.
When the API is slow or down
An external API is another company’s server, and at some point it will be slow or down. The question is whether your site goes down with it. The first safeguard is a short timeout. WordPress waits 5 seconds by default, and many plugins set it higher. If the API is called during a page view, the visitor waits the whole time, and all the PHP processes can end up waiting for the same response.
The second safeguard is to avoid calls during the page view altogether. Data that doesn’t change every second, like shipping rates, product data and exchange rates, can be fetched in the background and stored locally. Orders that have to be passed on can be queued in a background job, in WooCommerce usually with Action Scheduler, so the customer gets their order confirmation even if the accounting system is down, and the order is sent once it’s back up.
If a call fails, retry with increasing pauses, for example after one, five and twenty minutes, instead of hammering away. Make sure it’s safe to send the same thing twice, so a resent order isn’t booked twice; many APIs support an idempotency key for exactly that. And log every failed call with time, address and response, but never with the key or the customer’s personal data. If the other system can send webhooks, use them rather than asking every minute whether there’s anything new: it’s both faster and puts less load on both sides.
Maintenance
An integration isn’t finished when it works. APIs get new versions, and old ones are shut down with a few months’ notice, usually sent to the email address that created the key. Make sure that email gets read, that errors in the integration notify a person and not just a line in a log, and that someone is responsible for fixing it when it happens.
Frequently asked questions
Can I call an API directly from JavaScript in the browser?
Only if the API is public and doesn’t require a secret key, such as a map or an open dataset. If it requires a key, the call has to go through your server.
What does an API integration cost?
A ready-made plugin can cost a small annual license. Your own integration depends on how many systems and rules are involved, and on the quality of the API. Remember to include maintenance, not just development.
What’s the difference between an API and a webhook?
With an API, your site asks the other system. With a webhook, the other system sends a message to your site by itself when something happens, for example when a parcel has shipped.
Want help?
We build integrations between WooCommerce and accounting, inventory and shipping systems, and we maintain them when the APIs change. Read more about integrations and custom development.