API reference
Storefront Management API
Configure the hosted storefront, arrange products, test newsletter delivery and review website AI drafts.
Save a storefront before arranging the catalog
Read GET /api/developer/storefront. A missing storefront returns storefront:null. POST creates it with 201, or updates an existing storefront with 200. PATCH saves supported identity, presentation and site structure. Published, draft, hidden and suspended are different states; saving a configuration is not necessarily publication.
Use an account session with storefront.view. Workspace changes, newsletter tests, catalog ordering and storefront AI need storefront.manage and all-products scope. Single-product placement changes additionally enforce the assigned product. Product credentials do not administer a storefront.
Preserve concurrent website edits
Read siteStructure and preserve its revision when saving navigation, page settings or shell behavior. A stale revision or simultaneous structure save returns STOREFRONT_EDIT_CONFLICT. Keep your unsaved edits, reload and reconcile them rather than repeatedly overwriting another session.
Product order accepts an ordered products array, up to 500 owned products, with optional homepageMerchandising.heroProductId. Array position becomes sort order and attached:false hides a placement. PUT and PATCH on one placement both normalize omitted fields to defaults; send the intended full placement, not an assumed sparse patch. Product placement does not bypass product publication, entitlement or checkout rules.
SoundSync
Illustrative catalog placement
Show a product in the catalog
curl --fail-with-body -sS -X PUT "$SOUNDSYNC_API_BASE/api/developer/storefront/products/123" \
-H "Authorization: Bearer $DEVELOPER_TOKEN" -H "Content-Type: application/json" \
--data '{"visibility":"visible","sortOrder":0,"productSlug":"example-instrument","customHeadline":null,"customDescription":null,"metadata":{}}'Test delivery without subscribing customers
Newsletter readiness checks transport configuration. Newsletter test actually sends a confirmation-style test to the signed-in teammate account, with a three-per-minute limit. It does not subscribe that teammate or prove inbox placement. Customer newsletter signup and its verification link remain separate from purchase audience enrollment and suppressions.
Review website AI before saving
Banner, copy, template, style and navigation tools use saved storefront/product context and optional currentStorefront fields. Banner generation may create a public draft asset. A returned suggestion is not a saved or published website change.
Storefront AI has its own latest-50 draft list. Applied/discard changes only review status, not storefront content or physical asset deletion. Check draftId and persistenceWarning. These IDs cannot be substituted for product-setup or operational AI draft IDs.
SoundSync
Connected workflows
SoundSync
Requests and responses
GET
/api/developer/storefront
Read saved storefront configuration
- Auth
- Account Bearer JWT
- Scope
- storefront.view.
- Returns
- HTTP 200: storefront.
- Notes
- Returns storefront:null when absent. This is private configuration, including metadata and saved navigation, not the public catalog.
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",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_user_id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"status": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"logo_url": {
"type": [
"string",
"null"
]
},
"banner_url": {
"type": [
"string",
"null"
]
},
"website_url": {
"type": [
"string",
"null"
]
},
"support_url": {
"type": [
"string",
"null"
]
},
"primary_color": {
"type": [
"string",
"null"
]
},
"accent_color": {
"type": [
"string",
"null"
]
},
"theme_mode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
POST
/api/developer/storefront
Create the storefront or update an existing one
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- slug: string
- status: draft | published | hidden | suspended
- displayName: string
- headline: string
- description: string
- logoUrl: string,null
- bannerUrl: string,null
- websiteUrl: string,null
- supportUrl: string,null
- primaryColor: string
- accentColor: string
- themeMode: light | dark | system
- websiteTemplate: string
- visualStyle: string
- navMode: string
- siteStructure: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- pageTemplates: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- homepageMerchandising: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- templateContentSlots: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 201: storefront, created, updated.
- Notes
- 201 means created; an existing storefront follows the update path with 200 and updated:true. CamelCase and supported snake_case fields are accepted. A saved draft is not a published storefront.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"hidden",
"suspended"
]
},
"displayName": {
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"bannerUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
},
"supportUrl": {
"type": [
"string",
"null"
]
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"themeMode": {
"type": "string",
"enum": [
"light",
"dark",
"system"
]
},
"websiteTemplate": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"navMode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_user_id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"status": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"logo_url": {
"type": [
"string",
"null"
]
},
"banner_url": {
"type": [
"string",
"null"
]
},
"website_url": {
"type": [
"string",
"null"
]
},
"support_url": {
"type": [
"string",
"null"
]
},
"primary_color": {
"type": [
"string",
"null"
]
},
"accent_color": {
"type": [
"string",
"null"
]
},
"theme_mode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"created": {
"type": "boolean"
},
"updated": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
PATCH
/api/developer/storefront
Save storefront identity, layout and navigation
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- slug: string
- status: draft | published | hidden | suspended
- displayName: string
- headline: string
- description: string
- logoUrl: string,null
- bannerUrl: string,null
- websiteUrl: string,null
- supportUrl: string,null
- primaryColor: string
- accentColor: string
- themeMode: light | dark | system
- websiteTemplate: string
- visualStyle: string
- navMode: string
- siteStructure: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- pageTemplates: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- homepageMerchandising: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- templateContentSlots: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: storefront, updated.
- Notes
- Read the current configuration first. Send siteStructure.revision when changing the structure; stale revisions or concurrent structure writes return 409 STOREFRONT_EDIT_CONFLICT. Keep unsaved edits, reload and reconcile rather than blindly retrying. Saving structure records up to 50 historical snapshots; this is not an unlimited backup guarantee.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"hidden",
"suspended"
]
},
"displayName": {
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"bannerUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
},
"supportUrl": {
"type": [
"string",
"null"
]
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"themeMode": {
"type": "string",
"enum": [
"light",
"dark",
"system"
]
},
"websiteTemplate": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"navMode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_user_id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"status": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"logo_url": {
"type": [
"string",
"null"
]
},
"banner_url": {
"type": [
"string",
"null"
]
},
"website_url": {
"type": [
"string",
"null"
]
},
"support_url": {
"type": [
"string",
"null"
]
},
"primary_color": {
"type": [
"string",
"null"
]
},
"accent_color": {
"type": [
"string",
"null"
]
},
"theme_mode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"updated": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
GET
/api/developer/storefront/newsletter/readiness
Inspect newsletter confirmation transport
- Auth
- Account Bearer JWT
- Scope
- storefront.view.
- Returns
- HTTP 200: configured, status, message, sender.
- Notes
- Configured transport is not proof of inbox delivery. Does not subscribe a customer or send a test.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"configured": {
"type": "boolean"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
},
"sender": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
POST
/api/developer/storefront/newsletter/test
Send a confirmation-email test to the signed-in teammate
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Returns
- HTTP 200: sent, recipient, message.
- Notes
- Actually sends email to the authenticated actor account, not an arbitrary body recipient. Limited to 3 requests per minute per signed-in user. Requires configured transport and a saved storefront. Does not create a newsletter subscription; provider acceptance is not guaranteed inbox placement.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"sent": {
"type": "boolean"
},
"recipient": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 429, 500, 503.
GET
/api/developer/storefront/products
List permitted storefront product placements
- Auth
- Account Bearer JWT
- Scope
- storefront.view; results restricted to assigned products.
- Returns
- HTTP 200: storefront, products.
- Notes
- Can initialize the developer storefront/default product placements. This read is not a zero-write health check. Returns placement rows with a nested product, not the public catalog product array.
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
},
"developer_user_id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"status": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"logo_url": {
"type": [
"string",
"null"
]
},
"banner_url": {
"type": [
"string",
"null"
]
},
"website_url": {
"type": [
"string",
"null"
]
},
"support_url": {
"type": [
"string",
"null"
]
},
"primary_color": {
"type": [
"string",
"null"
]
},
"accent_color": {
"type": [
"string",
"null"
]
},
"theme_mode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"storefront_id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"visibility": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"product_slug": {
"type": [
"string",
"null"
]
},
"custom_headline": {
"type": [
"string",
"null"
]
},
"custom_description": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"is_draft": {
"type": "boolean"
},
"product_type": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
PUT
/api/developer/storefront/products/order
Save ordered product placements and optional homepage hero
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- products: array (required)
- homepageMerchandising: object
- Returns
- HTTP 200: storefront, products, count.
- Notes
- items aliases products; product_id/id alias productId. Array position determines sort order; duplicate or foreign products fail. attached:false sets hidden. An explicit homepage hero must be a valid visible placement. Send the intended placement fields; this is not a generic sparse patch.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"visibility": {
"type": "string",
"enum": [
"visible",
"featured",
"unlisted",
"hidden"
]
},
"attached": {
"type": "boolean"
}
},
"additionalProperties": true
},
"minItems": 1,
"maxItems": 500
},
"homepageMerchandising": {
"type": "object",
"properties": {
"heroProductId": {
"type": [
"integer",
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"required": [
"products"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_user_id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"status": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"logo_url": {
"type": [
"string",
"null"
]
},
"banner_url": {
"type": [
"string",
"null"
]
},
"website_url": {
"type": [
"string",
"null"
]
},
"support_url": {
"type": [
"string",
"null"
]
},
"primary_color": {
"type": [
"string",
"null"
]
},
"accent_color": {
"type": [
"string",
"null"
]
},
"theme_mode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"storefront_id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"visibility": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"product_slug": {
"type": [
"string",
"null"
]
},
"custom_headline": {
"type": [
"string",
"null"
]
},
"custom_description": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"is_draft": {
"type": "boolean"
},
"product_type": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"count": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
PUT
/api/developer/storefront/products/{productId}
Save one owned product placement
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and assigned-product access.
- Request fields
- visibility: visible | featured | unlisted | hidden
- sortOrder: integer
- productSlug: string
- customHeadline: string,null
- customDescription: string,null
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: setting, storefront, product.
- Notes
- Both methods use the same upsert normalization: omitted visibility defaults visible, sortOrder defaults 0, and omitted custom copy clears it. Read and send the intended full placement; PATCH does not preserve every omitted placement field. Does not publish the underlying product.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"featured",
"unlisted",
"hidden"
]
},
"sortOrder": {
"type": "integer"
},
"productSlug": {
"type": "string"
},
"customHeadline": {
"type": [
"string",
"null"
]
},
"customDescription": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"setting": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"storefront_id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"visibility": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"product_slug": {
"type": [
"string",
"null"
]
},
"custom_headline": {
"type": [
"string",
"null"
]
},
"custom_description": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"is_draft": {
"type": "boolean"
},
"product_type": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_user_id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"status": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"logo_url": {
"type": [
"string",
"null"
]
},
"banner_url": {
"type": [
"string",
"null"
]
},
"website_url": {
"type": [
"string",
"null"
]
},
"support_url": {
"type": [
"string",
"null"
]
},
"primary_color": {
"type": [
"string",
"null"
]
},
"accent_color": {
"type": [
"string",
"null"
]
},
"theme_mode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
PATCH
/api/developer/storefront/products/{productId}
Save one owned product placement
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and assigned-product access.
- Request fields
- visibility: visible | featured | unlisted | hidden
- sortOrder: integer
- productSlug: string
- customHeadline: string,null
- customDescription: string,null
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- HTTP 200: setting, storefront, product.
- Notes
- Both methods use the same upsert normalization: omitted visibility defaults visible, sortOrder defaults 0, and omitted custom copy clears it. Read and send the intended full placement; PATCH does not preserve every omitted placement field. Does not publish the underlying product.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"featured",
"unlisted",
"hidden"
]
},
"sortOrder": {
"type": "integer"
},
"productSlug": {
"type": "string"
},
"customHeadline": {
"type": [
"string",
"null"
]
},
"customDescription": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"setting": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"storefront_id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"visibility": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"product_slug": {
"type": [
"string",
"null"
]
},
"custom_headline": {
"type": [
"string",
"null"
]
},
"custom_description": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"is_draft": {
"type": "boolean"
},
"product_type": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"storefront": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_user_id": {
"type": "integer",
"minimum": 1
},
"slug": {
"type": "string"
},
"status": {
"type": "string"
},
"display_name": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"logo_url": {
"type": [
"string",
"null"
]
},
"banner_url": {
"type": [
"string",
"null"
]
},
"website_url": {
"type": [
"string",
"null"
]
},
"support_url": {
"type": [
"string",
"null"
]
},
"primary_color": {
"type": [
"string",
"null"
]
},
"accent_color": {
"type": [
"string",
"null"
]
},
"theme_mode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
POST
/api/developer/storefront/ai/banner
Generate a storefront banner draft
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- currentStorefront: object
- notes: string
- instructions: string
- mood: string
- visualMood: string
- tone: string
- targetCustomer: string
- bannerUse: string
- aspectRatio: string
- Returns
- HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
- Notes
- Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"currentStorefront": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"hidden",
"suspended"
]
},
"displayName": {
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"bannerUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
},
"supportUrl": {
"type": [
"string",
"null"
]
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"themeMode": {
"type": "string",
"enum": [
"light",
"dark",
"system"
]
},
"websiteTemplate": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"navMode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"notes": {
"type": "string"
},
"instructions": {
"type": "string"
},
"mood": {
"type": "string"
},
"visualMood": {
"type": "string"
},
"tone": {
"type": "string"
},
"targetCustomer": {
"type": "string"
},
"bannerUse": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"draftId": {
"type": [
"integer",
"string",
"null"
]
},
"toolType": {
"type": "string"
},
"suggestions": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"provider": {
"type": "string"
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"persistenceWarning": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 409, 429, 500, 502.
POST
/api/developer/storefront/ai/copy
Generate a storefront copy draft
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- currentStorefront: object
- notes: string
- instructions: string
- mood: string
- visualMood: string
- tone: string
- targetCustomer: string
- bannerUse: string
- aspectRatio: string
- Returns
- HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
- Notes
- Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"currentStorefront": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"hidden",
"suspended"
]
},
"displayName": {
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"bannerUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
},
"supportUrl": {
"type": [
"string",
"null"
]
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"themeMode": {
"type": "string",
"enum": [
"light",
"dark",
"system"
]
},
"websiteTemplate": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"navMode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"notes": {
"type": "string"
},
"instructions": {
"type": "string"
},
"mood": {
"type": "string"
},
"visualMood": {
"type": "string"
},
"tone": {
"type": "string"
},
"targetCustomer": {
"type": "string"
},
"bannerUse": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"draftId": {
"type": [
"integer",
"string",
"null"
]
},
"toolType": {
"type": "string"
},
"suggestions": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"provider": {
"type": "string"
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"persistenceWarning": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 409, 429, 500, 502.
POST
/api/developer/storefront/ai/template
Generate a storefront template draft
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- currentStorefront: object
- notes: string
- instructions: string
- mood: string
- visualMood: string
- tone: string
- targetCustomer: string
- bannerUse: string
- aspectRatio: string
- Returns
- HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
- Notes
- Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"currentStorefront": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"hidden",
"suspended"
]
},
"displayName": {
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"bannerUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
},
"supportUrl": {
"type": [
"string",
"null"
]
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"themeMode": {
"type": "string",
"enum": [
"light",
"dark",
"system"
]
},
"websiteTemplate": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"navMode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"notes": {
"type": "string"
},
"instructions": {
"type": "string"
},
"mood": {
"type": "string"
},
"visualMood": {
"type": "string"
},
"tone": {
"type": "string"
},
"targetCustomer": {
"type": "string"
},
"bannerUse": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"draftId": {
"type": [
"integer",
"string",
"null"
]
},
"toolType": {
"type": "string"
},
"suggestions": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"provider": {
"type": "string"
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"persistenceWarning": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 409, 429, 500, 502.
POST
/api/developer/storefront/ai/style
Generate a storefront style draft
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- currentStorefront: object
- notes: string
- instructions: string
- mood: string
- visualMood: string
- tone: string
- targetCustomer: string
- bannerUse: string
- aspectRatio: string
- Returns
- HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
- Notes
- Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"currentStorefront": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"hidden",
"suspended"
]
},
"displayName": {
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"bannerUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
},
"supportUrl": {
"type": [
"string",
"null"
]
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"themeMode": {
"type": "string",
"enum": [
"light",
"dark",
"system"
]
},
"websiteTemplate": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"navMode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"notes": {
"type": "string"
},
"instructions": {
"type": "string"
},
"mood": {
"type": "string"
},
"visualMood": {
"type": "string"
},
"tone": {
"type": "string"
},
"targetCustomer": {
"type": "string"
},
"bannerUse": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"draftId": {
"type": [
"integer",
"string",
"null"
]
},
"toolType": {
"type": "string"
},
"suggestions": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"provider": {
"type": "string"
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"persistenceWarning": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 409, 429, 500, 502.
POST
/api/developer/storefront/ai/navigation
Generate a storefront navigation draft
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Request fields
- currentStorefront: object
- notes: string
- instructions: string
- mood: string
- visualMood: string
- tone: string
- targetCustomer: string
- bannerUse: string
- aspectRatio: string
- Returns
- HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
- Notes
- Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"currentStorefront": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"hidden",
"suspended"
]
},
"displayName": {
"type": "string"
},
"headline": {
"type": "string"
},
"description": {
"type": "string"
},
"logoUrl": {
"type": [
"string",
"null"
]
},
"bannerUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
},
"supportUrl": {
"type": [
"string",
"null"
]
},
"primaryColor": {
"type": "string"
},
"accentColor": {
"type": "string"
},
"themeMode": {
"type": "string",
"enum": [
"light",
"dark",
"system"
]
},
"websiteTemplate": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"navMode": {
"type": "string"
},
"siteStructure": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"pageTemplates": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"homepageMerchandising": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"templateContentSlots": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"notes": {
"type": "string"
},
"instructions": {
"type": "string"
},
"mood": {
"type": "string"
},
"visualMood": {
"type": "string"
},
"tone": {
"type": "string"
},
"targetCustomer": {
"type": "string"
},
"bannerUse": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"draftId": {
"type": [
"integer",
"string",
"null"
]
},
"toolType": {
"type": "string"
},
"suggestions": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"provider": {
"type": "string"
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"persistenceWarning": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 409, 429, 500, 502.
GET
/api/developer/storefront/ai/drafts
List the latest 50 storefront AI drafts
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Returns
- HTTP 200: drafts.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"drafts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"storefront_id": {
"type": [
"integer",
"string",
"null"
]
},
"tool_type": {
"type": "string"
},
"generated_payload_json": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"generated_asset_id": {
"type": [
"string",
"null"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"applied_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"discarded_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
POST
/api/developer/storefront/ai/drafts/{draftId}/applied
Mark a storefront draft applied
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Returns
- HTTP 200: draft.
- Notes
- Developer-scoped review status only. Does not apply content, publish a website or physically delete an asset. These IDs are not operational or product-setup draft IDs.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"draft": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"storefront_id": {
"type": [
"integer",
"string",
"null"
]
},
"tool_type": {
"type": "string"
},
"generated_payload_json": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"generated_asset_id": {
"type": [
"string",
"null"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"applied_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"discarded_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.
POST
/api/developer/storefront/ai/drafts/{draftId}/discard
Mark a storefront draft discard
- Auth
- Account Bearer JWT
- Scope
- storefront.view, storefront.manage and all-products scope.
- Returns
- HTTP 200: draft.
- Notes
- Developer-scoped review status only. Does not apply content, publish a website or physically delete an asset. These IDs are not operational or product-setup draft IDs.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"draft": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"storefront_id": {
"type": [
"integer",
"string",
"null"
]
},
"tool_type": {
"type": "string"
},
"generated_payload_json": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"generated_asset_id": {
"type": [
"string",
"null"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"applied_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"discarded_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500.