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.
Forward and consume the cart-link parameter
The full storefront parent loader forwards one ss_cart query value into the permitted frame. A successful merge posts cart_link_applied; the parent checks its registered frame, source window and SoundSync origin before clearing the parameter.
This is browser navigation, not an authentication or checkout endpoint. The host must resolve the generated cart route. Existing cart items remain, and any unavailable selected product or combined cart above 100 items prevents the merge.
SoundSync
Build and test the email button
Campaign and cart-link guide
Copy or insert the link and verify the actual destination before sending.