The edit, push and preview loop
Every upload creates a new draft version; nothing you upload changes what customers see until someone publishes it. So the loop is safe to run as often as you like.
Edit
Work in a folder laid out as the package format says. Keep it in version control: the theme's own version in manifest.json is yours to set, and Truly shows it next to each version in the library.
Pack
Zip the folder's contents, with manifest.json at the top of the archive. Leave out anything that is not part of the format (.git, .DS_Store, README.md): an unknown file fails the check. For example:
cd my-theme && zip -r -X ../my-theme.zip manifest.json layout templates snippets assets locales
Push
Upload the zip in Settings > Brand & Apps > Theme, or push it from a script with a personal push token. Either way, the same file again while it is being checked, or after it passed, returns the same upload instead of a new version, so a retried push is safe. Each push makes a new draft version; it never overwrites one.
A push token
A theme developer, or anyone with the push token permission, creates a token under Push tokens on the same page. Creating one asks for a code from your authenticator app or your passkey; a password is not enough, so add one of them under Profile first. The token is shown once: copy it into your password manager or your CI's secrets. It expires after 90 days, the page shows when it was last used, and you can revoke it there at any time. It also stops working when your user is deactivated, loses the upload permission or the theme module is turned off.
A token can do two things: push a zip and make a preview link. It cannot publish, roll back, delete or turn the theme off; those stay in the library, behind your sign-in.
Push
Send the zip as the archive field of a form upload to https://app.truly.dk/<tenant>/api/themes/pushes, with the token in the Authorization header (never in the address or a cookie):
curl -sS -H "Authorization: Bearer $TRULY_THEME_TOKEN" -F archive=@my-theme.zip https://app.truly.dk/<tenant>/api/themes/pushes
The answer is the upload, a job you poll for the check report:
{ "id": 42, "status": "pending", "filename": "my-theme.zip", "report": [], "versionId": null, "createdAt": "…", "url": "/<tenant>/api/themes/pushes/42" }
202 means a new upload; 200 means this archive was already pushed, and you get that upload back. Poll GET https://app.truly.dk followed by url, with the same header, every few seconds until status is succeeded (with the new version's id in versionId, and its warnings in report) or failed (with the errors in report).
Errors come back as { "error": { "code": "…" } }: unauthenticated (401: no token, or an unknown, expired or revoked one), forbidden (403: your user lacks the permission), missing (422: no archive field), too_large (413), too_many_requests (429: 20 pushes per token and 40 per tenant an hour). A tenant without the theme module answers 404.
Check
The page shows the check report when the check is done. Errors block the version; warnings (an English string missing, a CSS rule left out) are kept on it. See The check report.
Preview
Preview a version on the tenant's custom domain before publishing it: choose Preview on your domain in the version's menu in the library, or ask for a link with your push token:
curl -sS -X POST -H "Authorization: Bearer $TRULY_THEME_TOKEN" https://app.truly.dk/<tenant>/api/themes/versions/<versionId>/preview
which answers 201 with { "url": "…" } (or 422 no_domain while the tenant has no connected domain). You need the preview permission, and the domain must be verified and connected. The link opens
https://<custom domain>/_preview/<route>/<state>?preview_token=<token>
with the version drawn against sample data for that route and state (the same data the check renders with), and Truly's own parts (the pickers, forms and footer) as labelled placeholders. Change <route> and <state> in the address to see any other page and state of the routes; a route or state that does not exist answers 404. Links between preview pages keep the link; any other link leaves the preview. A page without a template of yours shows the default theme, as it would live.
The link works for 4 hours, for the version, domain and user it was made for. It stops working sooner if the version is deleted, the theme module or the theme switch is turned off, the domain stops being live, or the user loses the preview permission. Treat it as a password for the draft: anyone holding it sees the draft until it expires. While a link is live the version cannot be deleted by hand, but the library's automatic clean-up may still delete it to make room for a new upload, which ends the link. Previews set no cookies, load no tracking, and are never cached.
Publish and roll back
Publishing, rolling back, duplicating, downloading and deleting versions, and the switch that turns the theme off, are in the theme library. The library keeps a limited number of versions: when it is full, a new upload deletes the oldest draft, never the published version.
When a page fails
A page that fails to render (a Liquid error, a missing required slot, a time limit, a filter result over 64 KB) does not break the booking: that page falls back to the default theme, and the failure is counted per version and day with its reason, template and line, without any customer data. Fix it, upload a new version and publish it.