Layout Deployment API

Layout Deployment API

This page documents the two HTTP endpoints Selldone CLI calls to deploy a Layout: the version check and the upload. Use it to understand CLI errors or to build your own deployment tooling (for example in CI).

Overview

The CLI checks that the requested version is available before uploading the built Layout. Both requests include Authorization: Bearer <access_token> and Accept: application/json.

Action	Endpoint	Content type	Required backend scope
Check version	POST https://api.selldone.com/developer/layouts/check-version	application/json	SCOPE_SELLDONE_DEVELOPER_READ
Upload deployment	POST https://api.selldone.com/developer/layouts/deploy	multipart/form-data	SCOPE_SELLDONE_DEVELOPER_WRITE

The access token comes from the CLI's OAuth2 login.

1. Check version

The request body contains:

Field	Type	Validation
package	string	Required; 12–64 characters; must match ^[A-Za-z0-9.-]+$
version	string	Required; 1–64 characters; must match ^[A-Za-z0-9.-]+$

{
  "package": "com.example.layout",
  "version": "1.0.0"
}

Example request:

curl -X POST "https://api.selldone.com/developer/layouts/check-version" \
     -H "Authorization: Bearer <access_token>" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"package":"com.example.layout","version":"1.0.0"}'

When the version is available, the HTTP 200 response is:

{
  "success": true,
  "version": "1.0.0",
  "layout": null
}

layout contains the existing Layout object when the package already exists, or null for a new package. A duplicate version returns an application-level error response:

{
  "error": true,
  "error_msg": "Version is duplicated! Please change the version in the 'manifest.json' and try again.",
  "layout": {}
}

The shown API implementation also returns the duplicate result with HTTP 200; consumers must therefore check success or error in the response body. Invalid parameters return HTTP 422 validation errors.

2. Upload deployment

The upload request is multipart/form-data. Let the HTTP client generate the multipart boundary.

Part	Type	Validation
manifest	text containing JSON	Required and must contain valid JSON
file	ZIP file	Required; ZIP MIME type; maximum 51,200 KiB (50 MiB); must pass the ClamAV scan

The decoded manifest JSON uses this schema:

Field	Type	Validation
package	string	Required; 12–64 characters; must match ^[A-Za-z0-9._-]+$
version	string	Required; 1–64 characters; must match ^[A-Za-z0-9._-]+$
name	string	Required; 8–255 characters
description	string or null	Optional; include it as null when there is no description
storefront	boolean	Required
backoffice	boolean	Required

{
  "package": "com.example.layout",
  "version": "1.0.0",
  "name": "Example Layout",
  "description": null,
  "storefront": true,
  "backoffice": false
}

Example request:

curl -X POST "https://api.selldone.com/developer/layouts/deploy" \
     -H "Authorization: Bearer <access_token>" \
     -H "Accept: application/json" \
     -F "file=@dist.zip;type=application/zip" \
     -F "manifest=<manifest.json"

For compatibility with the complete CLI flow, use lowercase letters, digits, dots, and hyphens in package and version. Although the upload validator accepts underscores, the version-check endpoint does not. The current CLI also requires at least one of storefront or backoffice to be true.

A successful upload returns HTTP 200:

{
  "success": true,
  "message": "Layout uploaded successfully!",
  "layout": {},
  "deploy": {
    "layout_id": 123
  }
}

layout and deploy are the serialized server-side model objects; their complete field sets may evolve. The CLI uses deploy.layout_id to print the Layout management URL. Before returning, the server creates or reuses the Layout, creates a new deployment, and sets the deployment version as layout.version_beta. Invalid multipart fields or manifest content return HTTP 422 validation errors. Decoded-manifest errors are returned as a field-keyed JSON error bag; the application's standard validation envelope is used for invalid top-level multipart fields.

Related endpoints

List Layouts

The CLI's Layouts action calls GET https://api.selldone.com/developer/layouts with the same bearer token and prints the layouts array (package, name, verified_at, penalty_at, version_stable, version_beta, created_at). The CLI exits with the error_msg when the response contains error.

Related shop Layout route

POST /shops/{shop_id}/layout is routed to ShopLayoutController::api_setShopLayout, with shop_id as a path parameter. It is not called by the current CLI. The route declaration alone does not define its authorization scope, request body, response schema, or API host, so those details are intentionally not inferred here.

Next steps

• Deployment Workflow
• Packaging Layouts
• Selldone API documents