Context
A headless checkout on VTEX. The storefront is built by the team, the cart and the order
live in VTEX's orderForm and are reached through the Checkout API, and around that
core sit the parts the platform owns: conversion flows, payments, orders and authentication for
several merchants and storefronts.
That split puts a large part of the outcome in the front end. The cart's business rules belong to VTEX; how a customer is guided through them, what a screen says when something fails, and how many steps and how much noise stand between a full cart and a paid order are ours. In a checkout, that difference is revenue.
Problem
- Features have to land without breaking existing consumers of the API.
- Checkout is the revenue path: correct behaviour matters more than elegant code, and failures are visible immediately.
- Data crosses boundaries: orders, payments and authentication live in different services, communicated over REST and gRPC.
- An interface change in the back end implies coordinated change in the applications that consume it.
- Conversion is decided by small things: one step too many, an error that does not say what to do, a field asking for information the customer has to go looking for.
- On a payment screen, accessibility is not a polish item: keyboard focus, labels and how errors are announced decide whether some customers can buy at all.
My responsibility
Evolving existing features and endpoints, creating new endpoints when the feature required it (following the architectural patterns already established by the team), consuming those APIs in the front end, and writing tests. Most of what I did lived on the customer-facing side: guiding the customer through the flow, removing steps and noise, and keeping the payment and authentication screens usable for everyone.
What I worked on
- Checkout and conversion flows in the web applications: guiding the customer through the steps, tightening the copy and the states, and removing friction where the flow was asking for more than it needed.
- Payments and orders: features around the order lifecycle, and how an order's state is presented to the customer instead of only being correct on the server.
- Authentication: one-time codes over SMS, email and WhatsApp, across the applications that consume the platform.
- Accessibility and usability on the payment screens: keyboard navigation and focus order, visible focus, labels tied to their inputs, and errors that say what to do next instead of only what went wrong.
- Endpoints: evolving the existing ones, creating new ones when the feature required it, and consuming them from the front end.
- Observability and tests: Sentry for production issues, automated tests as the safety net for changes on a revenue path.
How I approached it
Before writing anything I read the other endpoints in the same service and followed their conventions (naming, error shape, validation) because consistency is what makes an API learnable. For changes to contracts, I treated existing consumers as constraints: extend rather than redefine, and keep the previous behaviour valid. Because the same change usually spans back end and front end, I worked on both sides of the contract instead of handing off a shape nobody had validated. And for anything touching money or order state, tests came before the change shipped.
Challenges
- Keeping compatibility while evolving a shared API used by multiple applications.
- Reasoning across REST and gRPC boundaries within one feature.
- Debugging in a system where the failure path has business consequences, using logs, traces through the observability stack, and error tracking.
- Fixing UI problems whose root cause sat in the API contract: the visible bug was rarely where the fix belonged.
- Making the checkout work for keyboard and screen reader users without making the flow worse for everybody else.
Decisions and trade-offs
- Follow the existing patterns instead of introducing a new one. Trade-off: occasionally a pattern is not the best fit, but a consistent codebase for the next engineer beat a locally elegant solution.
- Extend contracts additively. Trade-off: the API surface grows and carries legacy fields; the alternative was coordinating breaking changes across clients.
- Remove steps before adding features. Trade-off: the visible result is a shorter flow rather than a new capability, which is harder to show in a demo and easier to measure in conversion.
- Guide the customer instead of only reporting the error. Trade-off: more states to write and maintain per screen, in exchange for fewer dead ends, less support contact and fewer abandoned carts.
- Accessibility as part of the flow, not a later pass. Trade-off: more markup and more states to keep; in exchange, the payment screens work for keyboard and screen reader users, who are customers too.
Result
Features delivered on a revenue-critical path, most of them on the checkout's experience layer. The scale around it: over R$3 billion transacted on the platform.
What I learned
- In a shared API, compatibility is a feature with its own design cost.
- Reading existing code before writing new code is the cheapest architecture review available.
- Understanding the business consequence of a failure changes how much testing is enough.
- In a checkout, the interface is part of the business rule: a confusing state is a lost order, not a cosmetic problem.