Browse the docs ▾

Agent guides

Publish safely

You prepare, the owner decides. Show them exactly what will go live, and publish only after a clear yes.

What counts as a yes

The owner should agree in the conversation, after seeing this specific change. A general "go ahead and build it" at the start isn't approval to publish. "Publish whenever you're done" is a decision only they can make, so confirm it once you've shown them the result. The same goes for products going on sale, even before the site is live.

The first publish of a new site

A site that's never been published goes live all at once, after some checks. get_business_details lists each check with the tool that settles it.

1

Contacts. A real email address and phone number, through preview_business_details and save_business_details.

2

Legal details. A legal name and registered address, for a site that sells. A business counts as selling unless its settings say otherwise.

3

Terms and Privacy. Written and approved. See below.

4

Plan. A site can go live on the free trial. After the trial ends, preview_site_publish is refused with a checkout_url, and the owner pays in the browser.

Terms and Privacy

These are legal texts, and approval belongs to the owner.

1

Read what exists with get_policies.

2

Use preview_policies with starter: true for starter text from the business details, or send your own terms and privacy as HTML.

3

Show the owner both in full, and ask them to check that they suit the business.

4

Only after they say they have read them, call the preview again with the same starter, terms or privacy plus approve: true, then save_policies with the same fields. If the text is already saved, send approve: true alone.
Never approve for them. A text changed later needs approving again.

The publish itself

1

Call preview_site_publish. It lists every change that would go live, from you, other agents and the dashboard. A first publish lists the pages, checks and warnings instead.

2

On a first publish, check the warnings: sample content, placeholder images, and no way for buyers to pay. Later previews don't give these, so check for them yourself.

3

Show the owner the changes in plain words, with screenshots. Include anything you didn't do yourself.

4

Wait for their yes.

5

Call publish_site with the token, within 10 minutes. If you took longer, preview again.

6

Check the result with get_page_screenshot and source: "live", and give the owner the address.

When it's refused

A required check is open

The error's checks name the tool for each.

A broken shop link

The error lists every link to a missing, archived or off-sale product, with its ref. Fix the link, or put the product back on sale.

The trial has ended

Give the owner checkout_url.

The token was refused

Something changed. Preview again, and show the owner what's new.

Publishing items

Items publish on their own, separately from the site: preview_item_publish, then publish_item. A new content type also needs its page design published. Show the owner the item's address, and any required fields still empty. With an import_id, one token covers every item from that import, so tell them how many.

After a classic site's first publish

For a site opened with open_in_builder, the first publish moves the live site to the builder for good. preview_site_publish says so. Make sure the owner understands before they agree.
Don't promise that a design "looks the same on every device" or that a site "is ready for customers" until you've checked. Say what you checked and what you didn't.

What to show the owner

Ready to publish. This will go live:

 · Home: new headline and hero picture
 · Services: new page
 · Footer: new phone number
 · 1 change made by someone else in
   the dashboard: About, new text

Shall I publish?

The calls

preview_site_publish { "org_id": 1042 }
→ changes, or first_publish with pages
  and warnings,
  "publish_token": "pub_…"

(after a yes)

publish_site {
  "org_id": 1042,
  "publish_token": "pub_…" }

get_page_screenshot {
  "org_id": 1042,
  "source": "live" }