Skip to main content
Most merchants don’t need the API. The standard Genlook Shopify app provides a fully functional widget that works out of the box. This API documentation is for developers building custom integrations or advanced use cases. If you’re looking for standard setup instructions, check out our main documentation.

​
When to Use the API

The Genlook Widget API is designed for:
  • Custom widget implementations - Building a completely custom try-on experience
  • Advanced integrations - Integrating try-on into custom apps or platforms
  • White-label solutions - Embedding Genlook into third-party applications
  • Special use cases - Scenarios where the standard widget doesn’t meet your needs
Standard setup is recommended for 99% of merchants. The standard Shopify app widget is easier to set up, fully customizable through the admin panel, and includes all features like analytics, email collection, and integrations.

​
Base URL

All API requests are made through your Shopify store’s app proxy: 
https://your-store.myshopify.com/apps/proxy_genlook-x/public
Replace your-store with your actual Shopify store domain.
The app proxy path (/apps/proxy_genlook-x) is configured when you install the Genlook app. This path is consistent across all stores.

​
Authentication

Authentication is handled automatically by Shopify’s app proxy system. You don’t need to:
  • Generate API keys
  • Manage authentication tokens
  • Include authorization headers
The app proxy ensures requests are authenticated and associated with your Shopify store. This means you can make API calls directly from your store’s frontend without exposing credentials.

​
Rate Limits

Different endpoints have different rate limits PER USERS to ensure fair usage:
EndpointRate Limit
Upload Image10 requests per 5 minutes
Create Generation50 requests per week
Check CreditsCached for 2 minutes
Share Generation20 requests per minute
Exceeding rate limits will return HTTP 429 (Too Many Requests). Implement exponential backoff and retry logic in your application.

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeMeaning
200Success
400Bad Request - Invalid parameters
401Unauthorized - Authentication failed
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Error Responses

When an error occurs, the response body includes details: 
{
  "message": "Error description",
  "code": "ERROR_CODE"
}
Common error codes:
  • QUOTA_EXCEEDED - Monthly generation quota reached
  • RATE_LIMIT_EXCEEDED - Too many requests in time period
  • BILLING_NOT_ALLOWED - Billing issue or plan expired

​
Request Format

Most endpoints accept JSON in the request body: 
{
  "field1": "value1",
  "field2": "value2"
}
File uploads use multipart/form-data: 
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="image.jpg"
Content-Type: image/jpeg

[binary data]
------WebKitFormBoundary--

​
Response Format

Successful responses return JSON: 
{
  "field1": "value1",
  "field2": "value2"
}

​
Best Practices

Polling intervals: When polling generation status, use a 2-second interval. Don’t poll more frequently than necessary.
Error handling: Always check response status codes and handle errors gracefully. Show user-friendly messages for quota and rate limit errors.
Caching: Credit checks are cached for 2 minutes. Cache results on your end to avoid unnecessary API calls.

​
Endpoints Overview

Upload Image

Upload customer photos for virtual try-on

Create Generation

Request a virtual try-on generation

Generation Status

Check the status of a generation job

Collect Email

Collect customer email addresses

Share Generation

Create shareable links for try-on results

Download Image

Download generated try-on images

Check Credits

Verify if credits are available

Tracking Events

Send analytics events