API Reference
Storefront and Embedded Storefront API
Verified hosted storefront endpoints, embedded storefront bootstrap/frame-token routes, runtime attributes, cart behavior, and checkout handoff.
SoundSync
Verified storefront/embed endpoints
These routes are backed by storefrontRoutes.js and embedStorefrontRoutes.js.
GET
/api/storefronts/:slug
Fetch hosted public storefront brand/configuration by slug.
- Auth
- Public request; operation-specific verification still applies
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Returns
- Public storefront payload.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tagline": {
"type": "string"
},
"logoUrl": {
"type": "string"
},
"lightLogoUrl": {
"type": "string"
},
"darkLogoUrl": {
"type": "string"
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"backgroundColor": {
"type": "string"
},
"themeMode": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"customDomain": {
"type": [
"string",
"null"
]
},
"supportEmail": {
"type": "string"
}
},
"additionalProperties": true
},
"reviews": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
],
"minLength": 1,
"description": "Review IDs can be serialized strings; preserve the value when using moderation routes."
},
"productId": {
"type": "integer",
"minimum": 1
},
"productName": {
"type": "string"
},
"productSlug": {
"type": [
"string",
"null"
]
},
"rating": {
"type": "number"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"customerName": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedPurchase": {
"type": "boolean"
},
"imported": {
"type": "boolean"
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"supportArticles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"null"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"type": {
"type": "string"
},
"visible": {
"type": "boolean"
},
"sortOrder": {
"type": "integer"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500.
GET
/api/storefronts/:slug/products
List public products in a hosted storefront.
- Auth
- Public request; operation-specific verification still applies
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query q: string
- query category: string
- query tag: string
- query type: string
- query platform: string
- query format: string
- query minPrice: number
- query maxPrice: number
- query sort: string
- Returns
- Public products/catalog payload.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "platform",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "minPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "maxPrice",
"in": "query",
"schema": {
"type": "number"
},
"required": false,
"description": ""
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tagline": {
"type": "string"
},
"logoUrl": {
"type": "string"
},
"lightLogoUrl": {
"type": "string"
},
"darkLogoUrl": {
"type": "string"
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"backgroundColor": {
"type": "string"
},
"themeMode": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"customDomain": {
"type": [
"string",
"null"
]
},
"supportEmail": {
"type": "string"
}
},
"additionalProperties": true
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"shortDescription": {
"type": [
"string",
"null"
]
},
"price": {
"type": "number"
},
"salePrice": {
"type": [
"number",
"null"
]
},
"regularPrice": {
"type": "number"
},
"displayPrice": {
"type": "number"
},
"priceDisplay": {
"type": "string"
},
"regularPriceDisplay": {
"type": "string"
},
"salePriceDisplay": {
"type": [
"string",
"null"
]
},
"isOnSale": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"imageUrl": {
"type": [
"string",
"null"
]
},
"coverImage": {
"type": [
"string",
"null"
]
},
"developerId": {
"type": "integer",
"minimum": 1
},
"developerName": {
"type": "string"
},
"developer": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"profileUrl": {
"type": [
"string",
"null"
]
},
"verified": {
"type": "boolean"
}
},
"additionalProperties": true
},
"productType": {
"type": "string"
},
"productTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
},
"subscriptionEnabled": {
"type": "boolean"
},
"billingInterval": {
"type": [
"string",
"null"
]
},
"checkoutEligible": {
"type": "boolean"
},
"capabilities": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"requiresActivation": {
"type": "boolean"
},
"supportsSerials": {
"type": "boolean"
},
"supportsDownloads": {
"type": "boolean"
},
"marketplaceAsset": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"totalPages": {
"type": "integer"
},
"hasNextPage": {
"type": "boolean"
},
"hasPreviousPage": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500.
GET
/api/storefronts/:slug/products/:productSlug
Fetch a public storefront product detail.
- Auth
- Public request; operation-specific verification still applies
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Returns
- Public product detail payload.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tagline": {
"type": "string"
},
"logoUrl": {
"type": "string"
},
"lightLogoUrl": {
"type": "string"
},
"darkLogoUrl": {
"type": "string"
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"backgroundColor": {
"type": "string"
},
"themeMode": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"customDomain": {
"type": [
"string",
"null"
]
},
"supportEmail": {
"type": "string"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"shortDescription": {
"type": [
"string",
"null"
]
},
"price": {
"type": "number"
},
"salePrice": {
"type": [
"number",
"null"
]
},
"regularPrice": {
"type": "number"
},
"displayPrice": {
"type": "number"
},
"priceDisplay": {
"type": "string"
},
"regularPriceDisplay": {
"type": "string"
},
"salePriceDisplay": {
"type": [
"string",
"null"
]
},
"isOnSale": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"imageUrl": {
"type": [
"string",
"null"
]
},
"coverImage": {
"type": [
"string",
"null"
]
},
"developerId": {
"type": "integer",
"minimum": 1
},
"developerName": {
"type": "string"
},
"developer": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"profileUrl": {
"type": [
"string",
"null"
]
},
"verified": {
"type": "boolean"
}
},
"additionalProperties": true
},
"productType": {
"type": "string"
},
"productTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
},
"subscriptionEnabled": {
"type": "boolean"
},
"billingInterval": {
"type": [
"string",
"null"
]
},
"checkoutEligible": {
"type": "boolean"
},
"capabilities": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"requiresActivation": {
"type": "boolean"
},
"supportsSerials": {
"type": "boolean"
},
"supportsDownloads": {
"type": "boolean"
},
"marketplaceAsset": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"reviews": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
],
"minLength": 1,
"description": "Review IDs can be serialized strings; preserve the value when using moderation routes."
},
"productId": {
"type": "integer",
"minimum": 1
},
"productName": {
"type": "string"
},
"productSlug": {
"type": [
"string",
"null"
]
},
"rating": {
"type": "number"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"customerName": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedPurchase": {
"type": "boolean"
},
"imported": {
"type": "boolean"
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500.
GET
/api/embed/storefront/:storeSlug/bootstrap
Fetch the embedded storefront bootstrap payload.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Store slug, allowed parent origin, page, and product scope.
- Request fields
- query page: string
- query product: string
- Returns
- Storefront, pages, products, bundles, active page, reviews/support when requested, and embed metadata.
- Side effects
- None for GET endpoints unless noted.
- Notes
- Unauthorized embed domains return EMBED_DOMAIN_NOT_ALLOWED. Allowed embed origin/domain checks apply. The origin policy is not replaced by a developer JWT.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "product",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tagline": {
"type": "string"
},
"logoUrl": {
"type": "string"
},
"lightLogoUrl": {
"type": "string"
},
"darkLogoUrl": {
"type": "string"
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"backgroundColor": {
"type": "string"
},
"themeMode": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"customDomain": {
"type": [
"string",
"null"
]
},
"supportEmail": {
"type": "string"
}
},
"additionalProperties": true
},
"reviews": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
],
"minLength": 1,
"description": "Review IDs can be serialized strings; preserve the value when using moderation routes."
},
"productId": {
"type": "integer",
"minimum": 1
},
"productName": {
"type": "string"
},
"productSlug": {
"type": [
"string",
"null"
]
},
"rating": {
"type": "number"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"customerName": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"verifiedPurchase": {
"type": "boolean"
},
"imported": {
"type": "boolean"
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"supportArticles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"null"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"type": {
"type": "string"
},
"visible": {
"type": "boolean"
},
"sortOrder": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"siteStructureRevision": {
"type": "integer"
},
"siteStructureUpdatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"navigation": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"embed": {
"type": "object",
"properties": {
"allowed": {
"type": "boolean"
},
"domain": {
"type": [
"string",
"null"
]
},
"parentOrigin": {
"type": "string"
},
"instanceId": {
"type": "string"
},
"scriptUrl": {
"type": "string"
}
},
"additionalProperties": true
},
"pages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pageType": {
"type": "string"
},
"pageSlug": {
"type": "string"
},
"templateKey": {
"type": "string"
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"store": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tagline": {
"type": "string"
},
"logoUrl": {
"type": "string"
},
"lightLogoUrl": {
"type": "string"
},
"darkLogoUrl": {
"type": "string"
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"backgroundColor": {
"type": "string"
},
"themeMode": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"customDomain": {
"type": [
"string",
"null"
]
},
"supportEmail": {
"type": "string"
}
},
"additionalProperties": true
},
"brand": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tagline": {
"type": "string"
},
"logoUrl": {
"type": "string"
},
"lightLogoUrl": {
"type": "string"
},
"darkLogoUrl": {
"type": "string"
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"backgroundColor": {
"type": "string"
},
"themeMode": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"customDomain": {
"type": [
"string",
"null"
]
},
"supportEmail": {
"type": "string"
}
},
"additionalProperties": true
},
"page": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"shortDescription": {
"type": [
"string",
"null"
]
},
"price": {
"type": "number"
},
"salePrice": {
"type": [
"number",
"null"
]
},
"regularPrice": {
"type": "number"
},
"displayPrice": {
"type": "number"
},
"priceDisplay": {
"type": "string"
},
"regularPriceDisplay": {
"type": "string"
},
"salePriceDisplay": {
"type": [
"string",
"null"
]
},
"isOnSale": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"imageUrl": {
"type": [
"string",
"null"
]
},
"coverImage": {
"type": [
"string",
"null"
]
},
"developerId": {
"type": "integer",
"minimum": 1
},
"developerName": {
"type": "string"
},
"developer": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"profileUrl": {
"type": [
"string",
"null"
]
},
"verified": {
"type": "boolean"
}
},
"additionalProperties": true
},
"productType": {
"type": "string"
},
"productTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
},
"subscriptionEnabled": {
"type": "boolean"
},
"billingInterval": {
"type": [
"string",
"null"
]
},
"checkoutEligible": {
"type": "boolean"
},
"capabilities": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"requiresActivation": {
"type": "boolean"
},
"supportsSerials": {
"type": "boolean"
},
"supportsDownloads": {
"type": "boolean"
},
"marketplaceAsset": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"bundles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"billingInterval": {
"type": "string",
"enum": [
"monthly",
"yearly"
]
},
"trialDays": {
"type": "integer"
},
"failedPaymentGraceDays": {
"type": "integer"
},
"membershipMode": {
"type": "string",
"enum": [
"selected_products",
"all_products"
]
},
"fulfillmentMode": {
"type": "string",
"enum": [
"access",
"keep_products"
]
},
"basePriceStrategy": {
"type": "string",
"enum": [
"fixed",
"percent_discount",
"fixed_discount"
]
},
"fixedBundlePriceCents": {
"type": "integer",
"minimum": 0
},
"discountValue": {
"type": "number"
},
"cancellationBehavior": {
"type": "string",
"enum": [
"access_until_period_end",
"lock_immediately"
]
},
"environment": {
"type": "string",
"enum": [
"test",
"live"
]
},
"activeVersionId": {
"type": "integer",
"minimum": 1
},
"versions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"recurringAmountCents": {
"type": "integer",
"minimum": 0
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"shortDescription": {
"type": [
"string",
"null"
]
},
"price": {
"type": "number"
},
"salePrice": {
"type": [
"number",
"null"
]
},
"regularPrice": {
"type": "number"
},
"displayPrice": {
"type": "number"
},
"priceDisplay": {
"type": "string"
},
"regularPriceDisplay": {
"type": "string"
},
"salePriceDisplay": {
"type": [
"string",
"null"
]
},
"isOnSale": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"imageUrl": {
"type": [
"string",
"null"
]
},
"coverImage": {
"type": [
"string",
"null"
]
},
"developerId": {
"type": "integer",
"minimum": 1
},
"developerName": {
"type": "string"
},
"developer": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"slug": {
"type": [
"string",
"null"
]
},
"profileUrl": {
"type": [
"string",
"null"
]
},
"verified": {
"type": "boolean"
}
},
"additionalProperties": true
},
"productType": {
"type": "string"
},
"productTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
},
"subscriptionEnabled": {
"type": "boolean"
},
"billingInterval": {
"type": [
"string",
"null"
]
},
"checkoutEligible": {
"type": "boolean"
},
"capabilities": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"requiresActivation": {
"type": "boolean"
},
"supportsSerials": {
"type": "boolean"
},
"supportsDownloads": {
"type": "boolean"
},
"marketplaceAsset": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"support": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500.
POST
/api/embed/storefront/:storeSlug/frame-token
Issue a short-lived frame token for iframe storefront package loading.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Store slug, parent origin, instance id, frame route, storefront mode.
- Request fields
- parentOrigin: string (required)
- instanceId: string (required)
- Returns
- frameToken, expiresInSeconds 600, frameUrl, embed metadata.
- Side effects
- None for GET endpoints unless noted.
- Notes
- The parent origin must be permitted for this store. The token is private, short-lived and bound to the frame instance; it is not an account session.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"parentOrigin": {
"type": "string"
},
"instanceId": {
"type": "string"
}
},
"required": [
"parentOrigin",
"instanceId"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"frameToken": {
"type": "string"
},
"expiresInSeconds": {
"const": 600
},
"frameUrl": {
"type": "string"
},
"embed": {
"type": "object",
"properties": {
"allowed": {
"type": "boolean"
},
"domain": {
"type": [
"string",
"null"
]
},
"parentOrigin": {
"type": "string"
},
"instanceId": {
"type": "string"
},
"scriptUrl": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500.
GET
/api/embed/storefront/:storeSlug/frame-config
Validate a frame token and return iframe protocol metadata.
- Auth
- FrameToken
- Scope
- Store slug, parent origin, instance, frame route.
- Request fields
- frameToken/frame_token query
- parentOrigin/headers
- Returns
- ok, storeSlug, parentOrigin, instanceId, mode, protocol soundsync-storefront-embed, version 1.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"storeSlug": {
"type": "string"
},
"parentOrigin": {
"type": "string"
},
"instanceId": {
"type": "string"
},
"mode": {
"type": "string"
},
"protocol": {
"const": "soundsync-storefront-embed"
},
"version": {
"const": 1
},
"siteStructureRevision": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
POST
/api/embed/storefront/:storeSlug/checkout
Compatibility response for embed checkout attempts.
- Auth
- Allowed embed origin/domain; see the frame and operation notes
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Returns
- 409 USE_PRODUCT_CHECKOUT_ENDPOINT with checkoutEndpoint /api/checkout/product.
- Side effects
- None; returns a compatibility response pointing to canonical product checkout.
- Notes
- Compatibility endpoint; does not create checkout. Send authenticated checkout requests to /api/checkout/product.
Request, response and error reference
No request body fields are read by this operation.
HTTP 409 response (application/json)
{
"type": "object",
"properties": {
"code": {
"const": "USE_PRODUCT_CHECKOUT_ENDPOINT"
},
"message": {
"type": "string"
},
"checkoutEndpoint": {
"const": "/api/checkout/product"
}
},
"additionalProperties": true
}Documented failures: 400, 500.
SoundSync
Runtime attributes
The canonical snippet uses only attributes verified in public/embed/storefront.js.
| Attribute | Behavior |
|---|---|
| data-store | Required store slug used by the runtime to select the storefront. |
| data-start-page | Optional initial page; catalog is the default. |
| data-shell | content or full. Full shell can hide host chrome in viewport takeover mode. |
| data-store-nav | auto or explicit embedded navigation mode. |
| data-width | full or contained. The runtime mirrors this to data-soundsync-width. |
| data-base-path | Optional client-side route base path, defaulting to /store/. |
| data-template | Legacy override only. The runtime warns and ignores it because templates come from Website Builder. |
SoundSync
Canonical embed snippet
This snippet contains no credentials. Product and checkout data is fetched through public storefront/embed endpoints.
HTML
<script async src="https://www.soundsync.dev/storefront.js" data-api-base="https://www.soundsync.dev"></script>
<div
data-soundsync-storefront
data-store="demo-audio-labs"
data-start-page="catalog"
data-shell="content"
data-store-nav="auto"
data-width="full"
data-base-path="/store/">
</div>Checkout handoff
Embedded cart endpoints accept client display state, but checkout recalculates server-side through /api/checkout/product. /api/embed/storefront/:storeSlug/checkout intentionally returns USE_PRODUCT_CHECKOUT_ENDPOINT.