Skip to main content

Content, Search, Leads & Site Content

This page covers the smaller storefront modules: sdk.content, sdk.search, sdk.leads, sdk.newsletter, sdk.usps and sdk.events, plus the instance-level contactSiteOwner helper. The last three read the site content a merchant manages centrally in the admin (the newsletter, the USPs and the agenda) — the same content the sitepack_newsletter_form(), sitepack_usps() and sitepack_events() theme functions render server-side.

Content​

The sdk.content module reads pages, the sitemap, and legal policies.

get(handle)​

Fetch a content item by its handle or slug.

const { content } = await sdk.content.get('about-us');

list(params?)​

Return the sitemap: pages, categories, and products.

const sitemap = await sdk.content.list();
// → { status, pages, categories, products }

getLegalPages()​

Fetch all legal policies (refund, shipping, privacy, terms), keyed by type.

const { policies } = await sdk.content.getLegalPages();

query(phrase, options?)​

Run a storefront search. Throws if the phrase is empty.

const { results } = await sdk.search.query('running shoes');
Debounce search-as-you-type

Wrap live search in a debounce (250–300 ms) so a fast typist doesn't burn through the rate-limit budget. See Security & Rate Limiting.

Leads​

leads.generate(leadData) / generateLead(leadData)​

Capture a lead. email is required. generateLead(...) on the instance is a convenience alias for leads.generate(...). The lead is persisted in the store's inbox (it appears under Leads in the admin).

await sdk.leads.generate({ email: 'jane@example.com', name: 'Jane' });
// or
await sdk.generateLead({ email: 'jane@example.com' });

Newsletter​

Subscribe or unsubscribe a visitor from the store's central newsletter. Every signup is stored as a subscriber (with a subscribe/unsubscribe lifecycle) and also captured as a lead. If you only need a ready-made form, use the sitepack_newsletter_form() theme function instead — it renders the whole form for you.

newsletter.subscribe(email, options?)​

Subscribe an email address. email is required; pass { name } in options if you collect it. When the merchant has double opt-in on, the response has pending: true and the visitor still has to confirm via email.

const result = await sdk.newsletter.subscribe('jane@example.com', { name: 'Jane' });
if (result.status === 'success') {
    // result.pending === true when a confirmation email was sent
    console.log(result.message);
}

newsletter.unsubscribe(token)​

Unsubscribe using the token from an unsubscribe link.

await sdk.newsletter.unsubscribe(token);

USPs​

usps.list()​

Fetch the site's USPs. USPs are global — the same ordered set everywhere — so the whole visible list is returned. Returns the same shape as the sitepack_usps() theme function (uuid, title, text, icon). A placement argument is still accepted for backwards compatibility but is ignored.

const { usps } = await sdk.usps.list();

Events​

events.list(limit?, scope?)​

Fetch the site's events (the agenda). limit defaults to 5. scope selects which events to return — 'upcoming' (default, soonest first), 'past' (most recent first) or 'all' (newest first). Each event includes a locale-formatted date and schema.org Event JSON-LD — the same shape as the sitepack_events() theme function.

const { events } = await sdk.events.list(6);            // upcoming
const { events: past } = await sdk.events.list(6, 'past');

Contacting the site owner​

contactSiteOwner(contactData)​

Send a contact request to the store owner. message is required; name, email, and subject are recommended.

await sdk.contactSiteOwner({
    name: 'Jane Doe',
    email: 'jane@example.com',
    subject: 'Question about my order',
    message: 'When will order #1234 ship?'
});
Spam protection is active

The contact endpoint is throttled (5 submissions / hour per visitor) and includes honeypot detection. Do not add a full_name field to your payload — it is treated as a spam signal.