Practical guide

How to connect an e-commerce shop to an external API

Do not begin with a controller call. First make the data, responsibility, and outage behaviour clear.

30 minutes · E-commerce integration

First, the short version

What does connecting to an API mean?

An API is a contract between systems. When integrating an e-commerce shop, you may exchange stock, prices, orders, or customers. The contract says which data to send, how to secure it, and what a response means.

A webhook is the reverse direction: an external service tells you about a change. For regularly reading data, though, a shop usually makes an outgoing HTTP request.

Get ready

What you need before the first call

Good integration starts with questions. You can find most expensive mistakes before writing code.

Official external API documentation and access to its test environment, if it provides one.
A test account or API key. Store secrets in environment variables, not in the repository.
A list of data you truly need to transfer and the system that is the source of truth for each item.
A place for logs and a way to learn about a failure before a customer does.

Steps 1 to 3

Build an integration that survives normal operation

An external service is outside your control. Plan for a slow response, outage, and changed data.

1. Read the contract and shrink the task

Choose one small operation, such as reading stock for one product. Do not order, synchronise prices, and sync stock all at once.
Write down the URL, method, required headers, input, response, and error states.
Find out how authentication works: an API key, OAuth token, or signature. Do not guess; follow the provider documentation.
Also find the rate-limiting rules. A limit is not an error you solve by sending more requests.

Official Symfony HTTP client documentation

2. Create a dedicated client

Hide external calls in one class, such as SupplierApiClient. A controller or entity should not know a supplier URL or headers.
Configure the base URL, timeout, and authentication in one place. When a supplier changes, you will not search the whole project for the same details.
Check the HTTP status before reading a response. A 401, 404, or 500 is not ordinary data.
Map the supplier response to your own small data shape. The rest of the shop then does not depend on its field names.

composer require symfony/http-client

Official Symfony HTTP client authentication documentation

3. Plan for errors and repeats

Log safe details: operation name, response status, time, and an internal identifier. Never log a password or full token.
For temporary errors, use a limited number of retries with a pause. Do not blindly repeat requests that could create a second order.
If the external service sends changes through a webhook, accept it quickly and move further work to the background.
Measure errors and slow responses. An integration you do not know is broken will not help a customer.

Official Symfony documentation on retrying requests

Step 4

Check the integration before giving it orders

Start with harmless data reads. Only then try changes on test data.

Check credentials

Call a simple read endpoint. A 401 or 403 means an identity or permission problem, not a product data problem.
Compare one response with the documentation

Check data types, empty values, and time zones. One manually verified product exposes many wrong assumptions.
Simulate an error

Try a bad token, a slow response, or a 429 status. The shop should catch and log the error without damaging its own data.

If something goes wrong

Common problems

The API returns 401 or 403

Authentication and permissions are two different things. Check whether you send the right header type, whether the token expired, and whether the account may call that endpoint.

You get 429 Too Many Requests

Rate limiting means you call too quickly. Read response headers, reduce concurrency, use pagination, and delay the next attempt.

The supplier changed its response structure

Do not let its response flow through the whole shop. Mapping it in one client isolates the change, and a test with a saved sample response catches it faster.

An API outage stops an order

Decide what must happen now and what can wait. Store less important work for later processing and give the customer clear information.

Done

The integration has a safe foundation.

Now add further operations one by one. Each should have a clear contract, secret protection, logs, and a plan for an outage.

Read API in the glossary All guides