REST API

Virtual try-on API

Integrate Irisphera virtual try-on into a custom store or app with the REST API: authentication, shopper sessions and try-on generation.

Request an API key

On this page

Before you start
Overview
Authentication
Endpoints at a glance
1. Add your products
2. Create a shopper session
3. Generate a try-on
Errors
Usage

Before you start#

A merchant API key, issued by Irisphera
A server you control, to keep the key secret and create shopper sessions
Products in an Irisphera collection, identified by your SKU

Overview#

The API is served from https://api.irisphera.com and returns errors as application/problem+json. Each try-on generation costs €0.06. See the estimator on the pricing page.

The full API reference is shared with your API key. This page covers the main flow.

Authentication#

Caller	Header	Use for
Your server	`MERCHANT-API-KEY: <key>`	Catalog, shopper sessions and usage. Never put it in browser or mobile code.
Shopper's browser or app	`Authorization: Bearer <token>`	Try-on calls, with a short-lived token that your server creates.

Endpoints at a glance#

Method	Path	Purpose
POST	`/merchant/v2/collection-context`	Get your channel for shopper sessions
POST	`/merchant/v2/shopper-sessions`	Open a shopper session
POST	`/merchant/v2/shopper-sessions/{sessionId}/access-tokens`	Refresh a shopper token
GET	`/shopper/v2/stylist-preview/{skuCustomId}`	Check whether a product supports try-on
POST	`/shopper/v2/stylist-preview`	Generate a try-on
GET	`/merchant/v1/subscription`	Check quota and usage

1. Add your products#

Create a collection and add products to it, keyed by your SKU (skuCustomId). You can also import a collection from a feed URL.

2. Create a shopper session#

On your server, fetch your channel once with POST /merchant/v2/collection-context, then open a session for each shopper. The response includes an accessToken and its expiresAt time. Refresh it with POST /merchant/v2/shopper-sessions/{sessionId}/access-tokens.

Create a session

curl https://api.irisphera.com/merchant/v2/shopper-sessions \
  -H "MERCHANT-API-KEY: $IRISPHERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "<channelId>",
    "currentIdentity": {
      "namespace": "<namespace>",
      "kind": "ANONYMOUS",
      "externalId": "visitor-123"
    }
  }'

3. Generate a try-on#

Check that a product is ready with GET /shopper/v2/stylist-preview/{skuCustomId}. If the category is UNAVAILABLE, don't offer try-on for it.

Then send the shopper's photo with the product SKU. The response contains generatedImage as a base64 WebP, plus a resultUrl that stays valid for 24 hours.

Generate a try-on

curl https://api.irisphera.com/shopper/v2/stylist-preview \
  -H "Authorization: Bearer $SHOPPER_TOKEN" \
  -F skuCustomId=DRESS-LILAC-S \
  -F [email protected] \
  -F isFaceBlurred=false

Note

Accepted photo formats: PNG, JPEG, WebP and AVIF.

Errors#

Errors use the application/problem+json format, with a status, a title and details you can log.

Important

A 420 response means the shopper's photo couldn't be used. Ask them for another one rather than retrying the same image.

Usage#

Check your quota and current usage with GET /merchant/v1/subscription.

Was this page helpful?