Browse the docs ▾

Agent guides

Draft or live: what each change does

Most design work waits in a draft, but not everything does. Know which is which before you call a tool on a live site.

How changes go live explains the idea for owners. This page lists it by tool, so an agent can check before it acts.

Safe in the draft

These don't reach visitors until a publish. No token is needed.

Tool

What it changes

apply_site_ops

The design: pages, sections, forms, styles, theme and words on the page.

undo_site_change

Takes one batch back out of the draft.

open_in_builder

Copies a classic design to a draft. The first publish after it is permanent.

start_builder_site

Makes a builder draft for a new business.

set_brand_logo

Waits for the next publish on a live site. On a site never published, it applies at once.

create_item

A new draft item.

import_items, import_products

New drafts, and products off sale.

Live at once, with no token

Be careful with these on a live site.

Tool

What it changes

update_item

On a published item, the live page changes at once. Show the owner first. A draft stays a draft.
add_category_fields also has no token, but nothing on the site changes until a design shows the fields. Every product in the category gets them.

Live at once, with a token

The preview returns before-and-after and a publish_token. Save only after the owner's yes.

Area

What it changes, and the tools

Page settings

Page name, address and search text. preview_page_settings, then save_page_settings.

Business details

Contacts, legal details, social links and Pay on delivery. preview_business_details, then save_business_details.

Policies

Terms and Privacy, and approval of them. preview_policies, then save_policies.

Store lists

Menu, featured collections and product sections. preview_store_lists, then save_store_lists.

Collection order

A collection's products and order. preview_collection_order, then save_collection_order.

Product fields

A product's category field values. preview_product_fields, then save_product_fields.

Product changes

Name, description, tax, photos, collections, sizes and prices. preview_product_update, then save_product_update.

Stock

Stock counts and the low-stock level. preview_stock_adjustment, then save_stock_adjustment.

Product archive

Takes products off the shop, or restores them. preview_product_archive, then archive_products.

Library

A Library item, wherever it shows. preview_library_change, then save_library_change.

Content fields

A content type's fields, on all its items. preview_content_fields, then save_content_fields.

Custom types

A custom type, on every item using it. preview_custom_type, then save_custom_type.

Tag pages

A tag's address and words. preview_tag_pages, then save_tag_pages.

Order status

An order's status. The buyer is usually emailed. preview_order_action, then apply_order_action.
On a site that isn't live yet, these still need the owner's yes, though no visitor sees them.

Making the draft live

Preview, then act

What goes live

preview_site_publish, publish_site

The whole draft, from anyone who worked on it.

preview_item_publish, publish_item

One item, or everything from an import, including products going on sale.

preview_item_publish, unpublish_item

Takes an item off the site.

Tokens

A token works once, for that exact change, for 10 minutes. Saves must send the same arguments as their preview. publish_site, publish_item and unpublish_item take only org_id and the token. If it's refused, preview again and show the owner anything new.

Previews are always safe

Tools starting with get_, list_, search_ and preview_ change nothing. A preview may take the same arguments as the save, but no image is copied and no value is stored.

Before you call a tool

Will visitors see this at once?

  No  → the draft. Check, then carry on.

  Yes → show the owner the preview.
        Did they say yes in this
        conversation?

          No  → stop and ask.
          Yes → save, with the token.

Editing a published post

get_item
→ "status": "published", "revision": "…"

You: This post is live, so the change
     will show at once. Here's the new
     paragraph. Shall I save it?

Owner: Yes.

update_item { …, "base_revision": "…" }
→ the change, and the previous values