API reference
Product Releases API
Read, preview, save, cancel and retry versioned release plans.
Prepare privately, publish on a reviewed schedule
Schedule a draft product release using a local date/time and IANA time zone. Review the resolved UTC instant, product readiness and intended storefront/marketplace placement before confirming. Optional launch-sale settings are reviewed with the release, while existing subscription selling settings remain in place.
At execution, SoundSync rechecks the product, author permissions, billing, assets and approved actions. A blocked release needs attention. Polling, provider preparation and outages can delay publication; a schedule is not a guaranteed exact-second launch.
SoundSync
Release plan operations
GET
/api/products/{id}/release
Read a saved release plan, readiness and recent history
- Auth
- Account Bearer JWT
- Scope
- products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.
- Returns
- HTTP 200: plan, readiness, history, worker.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"plan": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
},
"version": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"scheduledAt": {
"type": "string",
"format": "date-time"
},
"timeZone": {
"type": "string"
},
"localTime": {
"type": "string"
},
"disambiguation": {
"type": "string"
},
"actions": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"hidden"
]
},
"listPublicly": {
"type": "boolean"
},
"storefrontPlacement": {
"type": "string",
"enum": [
"none",
"visible",
"featured",
"hero",
"hidden"
]
},
"sale": {
"type": "object",
"properties": {
"salePrice": {
"type": [
"number",
"string"
]
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"title": {
"type": "string"
},
"currency": {
"type": "string"
},
"saleChannelScope": {
"type": "string",
"enum": [
"universal",
"website",
"marketplace"
]
}
},
"additionalProperties": true,
"required": [
"salePrice",
"endsAt"
]
}
},
"additionalProperties": true
},
"outcome": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"attempts": {
"type": "integer",
"minimum": 0
},
"nextAttemptAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"releasedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"authorUserId": {
"type": "integer",
"minimum": 1
},
"workspaceId": {
"type": "integer",
"minimum": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"readiness": {
"type": "object",
"properties": {
"ready": {
"type": "boolean"
},
"blockers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"setup": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"productDraft": {
"type": "boolean"
},
"selling": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
},
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"worker": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: RELEASE_STALE_VERSION, RELEASE_REVIEW_REQUIRED, RELEASE_NOT_READY, RELEASE_TIME_AMBIGUOUS, RELEASE_TIME_NONEXISTENT, RELEASE_PROCESSING.
POST
/api/products/{id}/release/preview
Review the resolved instant and current Launch planning
- Auth
- Account Bearer JWT
- Scope
- products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.
- Request fields
- localTime: string (required)
- timeZone: string (required)
- disambiguation: reject | earlier | later
- scheduledAt: string
- actions: object
- Returns
- HTTP 200: time, actions, readiness, fingerprint.
- Notes
- Preview is not publication or a saved plan. Supply an IANA time zone. Nonexistent DST wall times fail; repeated wall times require earlier/later or an unambiguous UTC choice. Retain the returned fingerprint and resolved scheduledAt for the reviewed save.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"localTime": {
"type": "string"
},
"timeZone": {
"type": "string"
},
"disambiguation": {
"type": "string",
"enum": [
"reject",
"earlier",
"later"
]
},
"scheduledAt": {
"type": "string",
"format": "date-time"
},
"actions": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"hidden"
]
},
"listPublicly": {
"type": "boolean"
},
"storefrontPlacement": {
"type": "string",
"enum": [
"none",
"visible",
"featured",
"hero",
"hidden"
]
},
"sale": {
"type": "object",
"properties": {
"salePrice": {
"type": [
"number",
"string"
]
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"title": {
"type": "string"
},
"currency": {
"type": "string"
},
"saleChannelScope": {
"type": "string",
"enum": [
"universal",
"website",
"marketplace"
]
}
},
"additionalProperties": true,
"required": [
"salePrice",
"endsAt"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true,
"required": [
"localTime",
"timeZone"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"time": {
"type": "object",
"properties": {
"scheduledAt": {
"type": "string",
"format": "date-time"
},
"timeZone": {
"type": "string"
},
"localTime": {
"type": "string"
},
"disambiguation": {
"type": "string"
},
"display": {
"type": "string"
}
},
"additionalProperties": true
},
"actions": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"hidden"
]
},
"listPublicly": {
"type": "boolean"
},
"storefrontPlacement": {
"type": "string",
"enum": [
"none",
"visible",
"featured",
"hero",
"hidden"
]
},
"sale": {
"type": "object",
"properties": {
"salePrice": {
"type": [
"number",
"string"
]
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"title": {
"type": "string"
},
"currency": {
"type": "string"
},
"saleChannelScope": {
"type": "string",
"enum": [
"universal",
"website",
"marketplace"
]
}
},
"additionalProperties": true,
"required": [
"salePrice",
"endsAt"
]
}
},
"additionalProperties": true
},
"readiness": {
"type": "object",
"properties": {
"ready": {
"type": "boolean"
},
"blockers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"setup": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"productDraft": {
"type": "boolean"
},
"selling": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
},
"fingerprint": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: RELEASE_STALE_VERSION, RELEASE_REVIEW_REQUIRED, RELEASE_NOT_READY, RELEASE_TIME_AMBIGUOUS, RELEASE_TIME_NONEXISTENT, RELEASE_PROCESSING.
PUT
/api/products/{id}/release
Save or reschedule a reviewed draft release
- Auth
- Account Bearer JWT
- Scope
- products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.
- Request fields
- localTime: string (required)
- timeZone: string (required)
- disambiguation: reject | earlier | later
- scheduledAt: string
- actions: object
- expectedVersion: integer (required)
- reviewedFingerprint: string (required)
- Returns
- HTTP 200: plan, readiness.
- Notes
- Use expectedVersion:0 for a new plan, otherwise the saved version. Scheduling requires an unarchived publishable draft and a matching reviewed fingerprint; saving does not publish early. Execution rechecks permissions, billing, product setup and approved actions. Publication can be delayed by polling, outages or provider preparation.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"localTime": {
"type": "string"
},
"timeZone": {
"type": "string"
},
"disambiguation": {
"type": "string",
"enum": [
"reject",
"earlier",
"later"
]
},
"scheduledAt": {
"type": "string",
"format": "date-time"
},
"actions": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"hidden"
]
},
"listPublicly": {
"type": "boolean"
},
"storefrontPlacement": {
"type": "string",
"enum": [
"none",
"visible",
"featured",
"hero",
"hidden"
]
},
"sale": {
"type": "object",
"properties": {
"salePrice": {
"type": [
"number",
"string"
]
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"title": {
"type": "string"
},
"currency": {
"type": "string"
},
"saleChannelScope": {
"type": "string",
"enum": [
"universal",
"website",
"marketplace"
]
}
},
"additionalProperties": true,
"required": [
"salePrice",
"endsAt"
]
}
},
"additionalProperties": true
},
"expectedVersion": {
"type": "integer",
"minimum": 0
},
"reviewedFingerprint": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"localTime",
"timeZone",
"expectedVersion",
"reviewedFingerprint"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"plan": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
},
"version": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"scheduledAt": {
"type": "string",
"format": "date-time"
},
"timeZone": {
"type": "string"
},
"localTime": {
"type": "string"
},
"disambiguation": {
"type": "string"
},
"actions": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"hidden"
]
},
"listPublicly": {
"type": "boolean"
},
"storefrontPlacement": {
"type": "string",
"enum": [
"none",
"visible",
"featured",
"hero",
"hidden"
]
},
"sale": {
"type": "object",
"properties": {
"salePrice": {
"type": [
"number",
"string"
]
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"title": {
"type": "string"
},
"currency": {
"type": "string"
},
"saleChannelScope": {
"type": "string",
"enum": [
"universal",
"website",
"marketplace"
]
}
},
"additionalProperties": true,
"required": [
"salePrice",
"endsAt"
]
}
},
"additionalProperties": true
},
"outcome": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"attempts": {
"type": "integer",
"minimum": 0
},
"nextAttemptAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"releasedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"authorUserId": {
"type": "integer",
"minimum": 1
},
"workspaceId": {
"type": "integer",
"minimum": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"readiness": {
"type": "object",
"properties": {
"ready": {
"type": "boolean"
},
"blockers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"setup": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"productDraft": {
"type": "boolean"
},
"selling": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: RELEASE_STALE_VERSION, RELEASE_REVIEW_REQUIRED, RELEASE_NOT_READY, RELEASE_TIME_AMBIGUOUS, RELEASE_TIME_NONEXISTENT, RELEASE_PROCESSING.
POST
/api/products/{id}/release/cancel
Cancel a pending release without deleting the product
- Auth
- Account Bearer JWT
- Scope
- products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.
- Request fields
- expectedVersion: integer (required)
- Returns
- HTTP 200: plan.
- Notes
- Cancellation competes under the product/plan lock. A completed release cannot be undone here; use ordinary product visibility controls. A processing release may already have started.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true,
"required": [
"expectedVersion"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"plan": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
},
"version": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"scheduledAt": {
"type": "string",
"format": "date-time"
},
"timeZone": {
"type": "string"
},
"localTime": {
"type": "string"
},
"disambiguation": {
"type": "string"
},
"actions": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"hidden"
]
},
"listPublicly": {
"type": "boolean"
},
"storefrontPlacement": {
"type": "string",
"enum": [
"none",
"visible",
"featured",
"hero",
"hidden"
]
},
"sale": {
"type": "object",
"properties": {
"salePrice": {
"type": [
"number",
"string"
]
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"title": {
"type": "string"
},
"currency": {
"type": "string"
},
"saleChannelScope": {
"type": "string",
"enum": [
"universal",
"website",
"marketplace"
]
}
},
"additionalProperties": true,
"required": [
"salePrice",
"endsAt"
]
}
},
"additionalProperties": true
},
"outcome": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"attempts": {
"type": "integer",
"minimum": 0
},
"nextAttemptAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"releasedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"authorUserId": {
"type": "integer",
"minimum": 1
},
"workspaceId": {
"type": "integer",
"minimum": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: RELEASE_STALE_VERSION, RELEASE_REVIEW_REQUIRED, RELEASE_NOT_READY, RELEASE_TIME_AMBIGUOUS, RELEASE_TIME_NONEXISTENT, RELEASE_PROCESSING.
POST
/api/products/{id}/release/retry
Retry an eligible blocked or failed release
- Auth
- Account Bearer JWT
- Scope
- products.publish and assigned product access; storefront placement also requires storefront.manage, hero replacement all-products scope, and sale settings products.edit.
- Request fields
- expectedVersion: integer (required)
- Returns
- HTTP 200: plan.
- Notes
- Only blocked/failed plans are retryable. Changed ownership, product configuration, review fingerprint or readiness requires a fresh reviewed schedule instead. Retry does not bypass launch gates.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true,
"required": [
"expectedVersion"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"plan": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"productId": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
},
"version": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"scheduledAt": {
"type": "string",
"format": "date-time"
},
"timeZone": {
"type": "string"
},
"localTime": {
"type": "string"
},
"disambiguation": {
"type": "string"
},
"actions": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"visible",
"hidden"
]
},
"listPublicly": {
"type": "boolean"
},
"storefrontPlacement": {
"type": "string",
"enum": [
"none",
"visible",
"featured",
"hero",
"hidden"
]
},
"sale": {
"type": "object",
"properties": {
"salePrice": {
"type": [
"number",
"string"
]
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"title": {
"type": "string"
},
"currency": {
"type": "string"
},
"saleChannelScope": {
"type": "string",
"enum": [
"universal",
"website",
"marketplace"
]
}
},
"additionalProperties": true,
"required": [
"salePrice",
"endsAt"
]
}
},
"additionalProperties": true
},
"outcome": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"attempts": {
"type": "integer",
"minimum": 0
},
"nextAttemptAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"releasedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"authorUserId": {
"type": "integer",
"minimum": 1
},
"workspaceId": {
"type": "integer",
"minimum": 1
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: RELEASE_STALE_VERSION, RELEASE_REVIEW_REQUIRED, RELEASE_NOT_READY, RELEASE_TIME_AMBIGUOUS, RELEASE_TIME_NONEXISTENT, RELEASE_PROCESSING.