Ecommerce API: What To Check Before You Build On One

Searching for an ecommerce API turns up three quite different things, and the results do not distinguish between them. Working out which one you are actually looking for saves a lot of reading.

A commerce backend you build on. Products, carts, checkout, orders, customers, over HTTP. You write the storefront and this holds the data.

An API on top of a platform you already use. Shopify, BigCommerce and WooCommerce all expose one. The platform still owns the storefront; the API lets you script around it.

A single-purpose commerce API. Payments, tax, shipping rates, currency. One job, done by a specialist, called from whatever else you are running.

The rest of this is about the first kind, because that is the one where the API is the whole product and where the quality of the design decides how much of your year it consumes.

What to look at, in order

The auth model, because it sets the ceiling

A commerce API needs at least two kinds of credential. A public key that a browser may hold, which can read the catalog and manage a cart and nothing else. And a secret key that only a server holds, which can read orders and customers.

If the API has one key type, either you cannot call it from the browser or you are putting a key that reads customer data into a page anybody can view. There is no third possibility. This is the first thing to check and the one most likely to be a hard stop.

After that: whether tokens are scoped, whether they can be rotated without downtime, and whether a customer-facing session token exists so that a logged-in shopper can read their own orders and no one else's.

Webhooks, and whether they are reliable

Polling for new orders works and it wastes most of its calls. Webhooks are how a serious API tells you something happened.

The questions that matter are not whether webhooks exist. They are whether deliveries are signed so you can verify they came from the platform, whether failures are retried and for how long, whether each delivery carries an identifier so you can discard the duplicate that retries will eventually produce, and whether you can see and replay recent deliveries when something goes wrong at three in the morning.

An unsigned webhook with no retries is a notification, not an integration.

Idempotency, because some calls spend money

Creating an order, capturing a payment and buying a shipping label all have consequences that cannot be undone by trying again. If the connection drops after the server acted and before you heard back, you do not know what happened.

An idempotency key solves this: send the same key with the retry and the server returns the original result instead of doing it twice. An API that does not support one on its write endpoints is an API where every network blip is a potential double charge. This is the same failure the four exchanges in a shipping integration run into, for the same reason.

Pagination, rate limits and versioning

Offset pagination drifts when the underlying data changes between pages, which for orders it always does. Cursor pagination does not. For a catalog of forty products this does not matter; for an order export it matters a great deal.

Rate limits should be documented and the response should tell you where you stand, so you can slow down rather than discover the limit by being refused.

Versioning is about what happens when the platform changes. A version in the URL or a header, with old versions supported for a stated period, means upgrades are something you schedule. No versioning means upgrades are something that happens to you.

Things that look like features and are not

GraphQL or REST. Both work. GraphQL reduces round trips and adds a query-complexity problem. REST is simpler to cache and sometimes chattier. This is near the bottom of the list of things that will determine whether your project goes well.

SDKs in nine languages. Useful, and a thin wrapper over HTTP. A good API with no SDK beats a poor API with nine.

Endpoint count. A large number usually means the model leaked into the surface. Fewer endpoints with a coherent model are easier to hold in your head.

The test worth running

Before committing, build the smallest real thing: list products, add one to a cart, complete a checkout with a test payment, receive the order webhook, verify its signature. Half a day at most.

That path crosses public auth, server auth, a money-moving write and an inbound webhook, which is nearly every category of problem the API can have. An API that is pleasant across those five steps will usually stay pleasant. One that fights you there will keep fighting.

Where we fit

dashfordevs is the first kind: a commerce backend you call over HTTP, with publishable and secret keys separated, signed webhooks with retries, idempotency on the writes that spend money, and cursor pagination on the collections that grow. The wider argument for that shape is in what headless commerce actually means.

Where we are the wrong answer: if you want a hosted storefront with themes, an API-first backend is more work than you need and you should not be reading this. If you already run a platform you are happy with and want to script around it, that platform's own API is the shorter path. And if you need one specific capability rather than a whole backend, a single-purpose API will do it better than we will.

The docs have the endpoints, and the five-step test above is a reasonable way to spend an afternoon on them.