beauty API for headless e-commerce
Beauty API for Headless E-commerce: Where It Fits in a Composable Architecture
If your store runs on a composable stack, a beauty API is not a plugin: it is one more service. Where to place the profile, the render and the recommendation without breaking the front end.
Beauty e-commerce teams that migrated to a composable stack tend to discover the same thing: the store plugins that used to solve everything no longer apply. When the front end is a framework of your own and the catalog lives in a separate service, every new capability comes in as a service. A beauty API for headless e-commerce follows that same logic: instead of installing an extension on the platform, you call an endpoint, receive JSON and decide for yourself how it looks and where it appears.
This article organises the architecture decisions: which layer does what, what runs on the server and what in the browser, where to store the beauty profile and how to handle errors without breaking the product page.
The three layers of a beauty experience
Before drawing the integration, it helps to separate three functions that are often lumped together into a single "beauty solution".
Profile layer: understanding the customer
The customer sends a selfie and receives a structured beauty profile: skin tone and undertone, skin type and condition, hair attributes and a confidence level for each field. It is a JSON response, not an interface. That is exactly what a headless front end needs: the data arrives clean and the team decides whether to show it as a card, as a step in a quiz or as an invisible attribute that feeds something else. The selfie skin and hair analysis occupies this layer.
An important clarification for the product brief: the profile describes visible attributes in a photo. It is not a clinical assessment, does not treat anything and does not replace a health professional. The front-end copy should reflect that.
Visualisation layer: seeing the product applied
This is where the virtual makeup try-on lives. It comes in two forms, and the choice is architectural, not aesthetic. The photo API receives an image and the product (lipstick or foundation) and returns the rendered image, with palettes calibrated to the brand's real products within a project. The browser SDK, in early access since September 2026, runs on the brand's domain and covers thirteen products — lipstick, foundation, blush, face powder, under-eye concealer, eyeshadow, mascara, eyebrows, eyeliner, bronzer, contour, highlighter and lip liner — plus a combined Full Look, in live camera mode or photo mode, with any #RRGGBB colour.
The practical difference: the photo API is a server-to-server call and works in any channel, including WhatsApp or a CRM. The SDK is client-side code and the render happens locally in the browser, without uploading the image. The Full Look and the eleven additional products exist only in the SDK.
Recommendation layer: turning the profile into SKUs
A profile without a catalog is a nice piece of data with no action. MaIA Beauty Advisor is the layer that reads the profile and recommends the brand's own products on WhatsApp, product pages and chat. It is not self-serve: it is delivered as a project together with the B4A team, because it depends on how your catalog is modelled.
Beauty API for headless e-commerce: the minimum diagram
A pattern that works well in composable stacks:
- BFF (backend for frontend) as the intermediary. The browser never talks directly to the beauty API. Your BFF holds the API key, adds context (logged-in customer, currency, region) and normalises the response.
- One endpoint of your own per use case. Instead of exposing the raw JSON, publish
/perfiland/try-onon your own domain. That way you can switch provider, cache or mock without touching the front end. - The front end consumes your contract, not the provider's. This prevents a new field in the response from breaking the React component or the Vue template.
- The catalog rules. The mapping between the profile and the SKUs lives in your data layer, next to stock and price, not inside the visual component.
The browser SDK is the deliberate exception to rule 1: it runs on the client by design, self-hosted by the brand, which is why the front-end team keeps full control of bundling and CSS.
Decisions worth closing before the first sprint
Where the profile lives
Three options, and none is universal. In the session (fast, lost when the browser closes). In the customer account (lets you reuse the profile in email, app and store). In the CRM as segmentation attributes. The usual approach is session plus account, with synchronisation to the CRM when the customer is logged in. Define the retention policy for the image and the profile from the start, and state it in the privacy notice.
Consent as a component, not as fine print
In headless, consent is a reusable component: a screen before the camera, with clear text about what is sent and what is stored, and a persisted state. Doing it once prevents each channel from implementing it in its own way.
Graceful degradation
What does the product page show if the call fails or the customer denies camera access? The answer cannot be a blank screen. Define the fallback: classic shade selector, colour guide, short form. The beauty experience is a decision accelerator, not a requirement to buy.
Per-field confidence in the front-end logic
Every field in the profile comes with a confidence level. Use it: when confidence is low, show two shade options instead of one, or ask for a second photo in better light. That rule belongs to your business layer and should be configurable without a redeploy.
How to start without compromising the roadmap
The advantage of the self-serve model is that the technical team can test before a formal project exists: you create an account, buy credits and get an API key in the documentation. A developer can have a real call responding in a staging environment in an afternoon, with a test selfie and curl.
A reasonable plan: sprint 1, the call from the BFF and your own contract; sprint 2, the front-end component with consent and fallback; sprint 3, profile persistence and first use in recommendation or email. Only after that do you discuss the advisor layer and the full catalog.
Going to integrate beauty into a composable stack? Create your account and your API key to test the real response, or talk to the team if you need the recommendation layer connected to your catalog.
Frequently asked questions
What changes when integrating a beauty API into a headless stack compared with a traditional platform?
On a traditional platform you usually install an extension with the interface included; in headless you receive JSON and build the interface yourself. That gives you full control over the design and where the experience appears, in exchange for more front-end work.
Can the API key live in the browser?
No. The recommendation is to call the API from your backend or BFF and expose your own endpoint to the front end. The browser SDK is different: it runs on the client by design and is self-hosted by the brand, under early access granted per account.
Does the API try-on render a full look?
No. The photo API renders lipstick and foundation on the submitted image. The thirteen products and the Full Look exist only in the browser SDK, as a local preview in live camera mode or photo mode.
Where should I store the customer's beauty profile?
It depends on the case: in the session for a one-off experience, in the customer account to reuse it across channels, and in the CRM for segmentation. The most common approach combines session and account, with a retention policy stated in the privacy notice.
Can the selfie analysis be used to evaluate skin conditions from a medical standpoint?
No. MaIA Scan describes visible attributes in a photo, such as tone, undertone, type and apparent skin condition. It is not a clinical assessment, does not treat anything and does not replace a consultation with a health professional.