I've spent a lot of my career in ecommerce, and a surprising amount of that work comes down to systems talking to each other. A product page that pulls in stock from the warehouse. A checkout that hands the payment to someone else. An order that has to reach the picking team, the courier, the accounts and the marketing emails without anyone retyping it.
The two series on this site explain how that talking works: APIs for product managers covers REST APIs and webhooks, and GraphQL for product managers covers GraphQL. This post is the practical companion: where each one typically turns up in an online shop, with the platforms you're likely to meet.
The three kinds, in one line each
The three kinds, in one line each
You ask, at an address
"Create a payment for £47.52." "Find the addresses for this postcode." The workhorse of ecommerce.
You ask for exactly what you need
"This product's name, three photos, sizes, price and stock." Most common where a shop front builds its own pages.
They tell you when it happens
"The payment cleared." "The parcel left the warehouse." How systems keep each other up to date after the order.
A rule of thumb that holds up well: GraphQL is most common at the front of the shop, where pages need lots of related data quickly. REST APIs are everywhere, especially at checkout and behind the scenes. Webhooks take over once the order is placed, because most of what happens next is one system telling another that something changed.
An order, stage by stage
An order, stage by stage
- Showing the products
Product pages, category pages and search. Speed matters most here, because every extra second costs sales.
- GraphQLShopify Storefront API. A custom (headless) shop front asks for a product's title, photos, variants, price and stock in one query.
- GraphQLContentful. The buying guide, banners and size advice for the same page come from a headless content system.
- RESTAlgolia. Search results, filters and typo-tolerant suggestions, sent as the customer types.
- Checkout: address and delivery
The customer types a postcode and picks a delivery option. Fewer typos here means fewer lost parcels.
- RESTLoqate. A postcode lookup returns the addresses at that postcode, so the customer picks one instead of typing it.
- RESTMetapack. Delivery options and prices for that address: next day, nominated day, collection point.
- Payment
The step where getting the order of events right matters most.
- RESTStripe. The shop asks Stripe to create a payment for the basket total, and the card form sends the details to Stripe, never to the shop.
- RESTPayPal, Klarna. Pay with PayPal or pay later in instalments: each starts with a REST call to set up the payment.
- WebhookStripe. Stripe sends payment_intent.succeeded once the money is confirmed. That's when the order should be confirmed, not when the customer reaches the thank-you page.
- After the order
Picking, packing, shipping and stock. Mostly systems telling each other what changed.
- WebhookShopify, WooCommerce. An order created webhook tells the warehouse system or ERP there's a new order to pick.
- RESTRoyal Mail Click & Drop. The warehouse creates the shipment and prints the label.
- WebhookShipStation. A shipped notification, with the tracking number, triggers the dispatch email.
- WebhookShopify. An inventory levels update keeps stock in step on marketplaces and the warehouse system.
- Marketing and aftercare
Keeping in touch, keeping listings accurate and handling refunds.
- RESTKlaviyo. The shop sends a Placed Order event, which starts the post-purchase emails and review requests.
- RESTGoogle Merchant API. Keeps prices and stock on Google Shopping in line with the shop.
- WebhookStripe. A refund or a chargeback (charge.refunded, charge.dispute.created) alerts the customer service team.
- RESTXero. Orders, payments and refunds are posted to the accounts.
One order, end to end
Put those together and a single order is a surprising number of conversations, most of which the customer never sees:
One order, end to end
A customer buys a pack of wine glasses from a shop with its own front end on BigCommerce. Here's a simplified version of who talks to whom, and how.
- 10:02Shop front to BigCommerce GraphQL"The product's name, photos, pack sizes, price and stock"One answer, and the page appears
- 10:04Checkout to Loqate REST"The addresses at this postcode"A list to pick from
- 10:05BigCommerce to Stripe REST"Create a payment for £47.52"Ready for the card details
- 10:05Stripe to BigCommerce Webhook"The payment succeeded"Order confirmed, email sent
- 10:05BigCommerce to Warehouse Webhook"A new order to pick"Added to the picking list
- 10:06BigCommerce to Klaviyo REST"Placed Order, for this customer"Post-purchase emails start
- 14:30Warehouse to Royal Mail REST"Create a shipment and label"Label printed
- 14:31Warehouse to BigCommerce REST"Mark the order shipped, with the tracking number"Dispatch email sent
5 REST 1 GraphQL 2 webhooks for one order, between five companies and the warehouse
Two things stand out. First, the order is only confirmed when the payment provider says so (the webhook at 10:05), not when the customer clicks Pay. Second, after the first few minutes, almost nothing is the shop asking a question: it's systems reporting what they've done.
What the platforms offer
The big shop platforms offer all three kinds. Specialist services, such as payments, usually offer REST and webhooks.
What the platforms offer
| Platform | REST | GraphQL | Webhooks |
|---|---|---|---|
| ShopifyHosted shop platform | The older Admin API. New apps are expected to use GraphQL | The Admin API (running the shop) and the Storefront API (custom shop fronts) | Orders, products, stock, customers and more |
| BigCommerceHosted shop platform | The main management API | The Storefront API, for custom shop fronts | Orders, products, carts, customers |
| Adobe Commerce (Magento)Shop platform, hosted or self-run | Yes, alongside an older SOAP API | Yes, used by its own headless shop front | Through add-ons and Adobe's events tools |
| WooCommerceShop plugin for WordPress | Yes | Through community plugins | Orders, products, customers, coupons |
| commercetoolsHeadless commerce platform | Yes | Yes, covering the same data | Event subscriptions, sent through message queues |
| StripePayments | Yes, for everything | No | Payments, refunds, disputes, subscriptions |
| PayPalPayments | Yes | No | Payments, refunds, disputes |
| ContentfulHeadless content | Yes, for reading and editing content | Yes, for reading content | When content is published or changed |
Where it goes wrong
The integrations that cause the most trouble in ecommerce are rarely the clever ones. They're the ones nobody planned the unhappy path for:
- A webhook that never arrives. The payment went through, but the order never reached the warehouse. Good integrations check for gaps, for example a nightly REST call that compares orders on both sides.
- The same webhook twice. Providers retry when they don't hear back, so a "payment succeeded" can arrive twice. If that sends two confirmation emails, or worse, ships two parcels, the receiving code isn't checking whether it has seen the event before.
- Stock that drifts. The shop, the marketplaces and the warehouse each hold a stock figure. If one update is missed, the shop sells something that isn't there. Stock webhooks plus a regular full sync is the usual answer.
- A slow third party on the product page. If reviews, recommendations or delivery estimates load from another service, the page needs to work without them when that service is slow or down.
- A version retired underneath you. Platforms retire old API versions on a schedule. Shopify, for example, publishes a new Admin API version every quarter and supports each for about a year. Someone needs to own the upgrade dates.
Questions to ask on your next ecommerce project
- What's the source of truth for each thing? Products, prices, stock, orders and customers each need one home. Every other system copies from it.
- Which events do we need to hear about, and what happens if we miss one? List the webhooks, and the fallback for each.
- When exactly is an order confirmed? On the click, or on the payment provider's webhook? Customer emails, stock and analytics should all agree.
- What does the customer see if a service is down? For search, reviews, delivery options and payment, write it into the acceptance criteria.
- What are the limits and costs? Shop platforms limit how many API calls an app can make, and some services charge per call. A sale or a big import can hit both.
- Who owns each integration? The platform, an app from its marketplace, an agency or your own developers. When it breaks at 9pm on Black Friday, who gets the call?
If you'd like to see a REST API and a GraphQL API working live, the weather page and the country explorer on this site show every request and answer as it happens.