CmsService class (accessed via client.cms) reads a store’s editorial content — blog posts and shoppable lookbooks — and records views against the shopper’s session, so a sale can later be attributed to the content that led to it.
Blog Posts
listPosts
Retrieve a paginated list of published blog posts, newest first. This is ideal for building a
“News” or “Magazine” section on your storefront. Only published posts are returned — there is no
status filter. Filter by category with the category slug (category: 'buying-guides').
excerpt, featured_image, slug, and
product_count (how many products a shoppable post links to). For the full content, use getPost.
getPost
Retrieve the full content of a specific published blog post by its slug, including any linked
products for shoppable posts (each entry in the products array carries the product’s name,
sku, price, images, and display_type). Returns 404 if no published post matches the slug.
An embedded product also carries variant_id — pass that to client.cartWishlist.addToCart,
which is keyed by variant rather than product, so a shoppable post can add to a basket without a
second call. embed_id identifies the placement rather than the product, and block_id ties an embed
to the content block it sits beside. An embed whose product is no longer available is omitted, so a
post can return fewer products than were authored.
Response
Attributing content views
getPost and getLookbook both accept a visitor and a session identifier, and record the view
against them. That is what lets the merchant see which posts and lookbooks drive sales rather than
just traffic — and it is the first half of the content funnel: pass the same content_id (with
content_type) in the order’s attribution at checkout and the sale is credited back to the
content the shopper came from.
Both are optional. When you omit them the view still counts, but it is attributed to a coarse
fallback derived from the request, so repeat views by one shopper may not group together.
Lookbooks
Lookbooks are curated collections of lifestyle images linked to specific products, perfect for “Shop the Look” features.listLookbooks
Retrieve a list of published lookbooks, newest first. Only published lookbooks are returned —
there is no status filter.
getLookbook
Retrieve the full details of a published lookbook by its slug, including its ordered image gallery
and the shoppable hotspots placed on each image. Returns 404 if no published lookbook matches
the slug.
Each lookbook exposes status (always "published" from the public API) and collection_id — the
product collection that backs the lookbook, or null if it is standalone. The gallery lives under
images[], where each image has a url and a hotspots[] array tagging the products featured at
specific points in the photo (your “Shop the Look” markers).
A hotspot gives x and y as percentages of the image’s width and height from the top-left, so the
marker lands correctly at any display size, plus an optional label and the resolved product. The
product carries variant_id — pass that to client.cartWishlist.addToCart, which is keyed by
variant rather than product, so a marker can be added to a basket without a second call. Send a shopper
who wants a different size or colour to the product page instead. A hotspot whose product is no longer
available is omitted from the response, so an image can return fewer hotspots than were authored.
Response
status is always "published" from the public API. collection_id is the backing product
collection, or null when the lookbook is standalone (as above). Each images[] entry carries a
hotspots[] array — empty here, otherwise one marker per tagged product.Newsletter
subscribeNewsletter
Capture a newsletter signup from your storefront. The email address is the identity, so this works for both anonymous visitors and signed-in shoppers (a signed-in storefront prefills the email field). When the merchant has connected a marketing tool, subscribers are synced to their chosen list automatically.
Response
200 with already_subscribed: true and never creates a duplicate; a brand-new signup returns 201. This endpoint accepts both publishable and secret keys (it’s a storefront write, like cart), so you can call it directly from the browser.
Response Codes
The read endpoints (posts, lookbooks) areGET; subscribeNewsletter is a POST. All accept both publishable and secret keys. Slug validation is enforced — empty or whitespace-only slugs return 400 without hitting the database.