Skip to main content
The built-in themes Nightfall, Ship, Circuit, Arsenal, MarketPro and Vanguard stay exactly as they are. The code layer lets you add your own code on top of them and keep editing visually.

​
Theme code package

Each store gets one theme code package per built-in theme. You open it in the code editor like any theme copy. A package holds only: Theme JavaScript never loads on checkout, sign-in or account pages.

​
Code sections in the visual editor

Every sections/<name>.liquid with a {% schema %} block appears in the visual editor’s Add section list, under Theme code. Its settings form comes from the schema, so a code section stays fully editable without code. Reorder, hide, duplicate and delete work like built-in sections. When you change the schema in code, the form updates right away. New settings get their defaults; removed settings are ignored and their values kept.

​
Section ids in CSS

In a code section section.id is code:<name>. The : breaks CSS selectors (#{{ section.id }}-yearly:checked is dropped silently) and #id lookups. Use section.css_id (code-<name>) in {% style %} and in id= / for= attributes, or {{ value | css_id }}. The code editor and MCP validate / save_draft warn about a raw section.id there; the editor’s quick fix is Use section.css_id. Labels, radio/checkbox toggles, <details> and selects work in the visual editor canvas. To click links and buttons, turn on Interact in the top bar (or press I, or hold Alt).

​
Edit code of a built-in section

Choose Edit code on a built-in section to eject it. Its Liquid twin is copied into your package with the same markup and class names, so it looks identical and keeps its settings. Revert to built-in brings the original section back.

​
Commerce and checkout

Code sections sell with app blocks. They need no script:
  • buy_now and checkout_button go to the checkout page by default. mode: 'embed' opens the checkout popup over your page.
  • add_to_cart and cart_count open the platform cart drawer. The theme’s cart badge stays in sync.
  • reviews_widget and powered_by do not work in code sections. currency_selector needs currencies: 'USD,EUR'.
  • Code sections have shop, collections, all_products, request and localization. They have no product, collection or routes.
  • window.PapelShip loads after the page has loaded, on pages whose code sections contain an app block or a data-ps binding. In assets/theme.js, wait for papelship:sdk-ready.
See Commerce and checkout and App blocks.

​
Publish

Live pages show the package’s published version. Saved files show in the visual editor and the code editor previews only.
  1. Edit and save files in the code editor, or let an AI agent save drafts.
  2. Check the preview.
  3. Press Publish in the code editor or the visual editor. It is the same button and shows how many changes are unpublished.
Publishing validates every package file first. If anything fails, nothing changes on the live store.
AI agents connected through MCP can save package files but never publish them. See AI agents (MCP).

​
Security

Package files are scanned like designs, on the source and on the rendered output. Rich text and HTML settings are sanitised on the server.