Overview

A workspace can run several blogs, each published to the channels it should appear on. The Storefront API returns the blogs published to your channel and their live articles.

What the API does and doesn’t do

The merchant writes, publishes and moderates everything in the Papertracc app, under Marketing → Blog. The Storefront API is for the shopper’s side. It can:

• read blogs, articles, tags and approved comments
• submit a comment
• count an article view

The API has no endpoints for creating, editing or deleting blogs or articles, and none for moderating comments. Neither the Storefront API nor the Core API does this.

Blogs

List Blogs returns the blogs published to your channel, ordered by title. A new blog is published to every Online Store and Store API channel unless the merchant chooses otherwise. articles_count counts live articles only.

A blog that isn’t published to your channel returns 404, and so do its articles.

Live articles

An article is live when it is published and its publish date has passed. Scheduled articles appear on their own when the date arrives. Drafts are never returned.

Article handles are unique across the workspace, so an article can be fetched without naming its blog.

Get Article returns 404 once an article stops being live. That happens when the merchant:

• saves a live article as a draft or unpublishes it. Republishing keeps the original publish date unless the merchant reschedules it.
• deletes the article.
• changes the article’s handle. The old handle doesn’t redirect.
• takes the article’s blog off your channel.

Treat 404 as “no longer available” and drop the page or link.

Listing and search

List Articles returns the newest first. Use sort_by to order by oldest first, title, or most-viewed. Filters combine, so blog=journal&tag=care returns articles that match both.

q searches titles, excerpts, tags and article bodies using English word forms, so caring also finds care. It accepts quoted phrases ("silk scarf"), or, and - to leave a word out. A title containing the text also matches. Results are ranked by relevance, with title matches first. If you also send sort_by, that order is used instead.

List Article Tags returns up to 100 tags, the most used first, each with the number of live articles carrying it. An article can have up to 20 tags.

List Related Articles returns other live articles from the same blog or sharing at least one tag, newest first.

Article content

Comments

Each blog decides how comments work, reported on the article as comments:

Create Comment returns the new comment’s status, PENDING or APPROVED, so you can tell the shopper whether it is waiting for approval. A comment caught by the merchant’s blocklist also returns PENDING, so the sender can’t tell it was blocked.

List Comments returns approved comments only, oldest first. Each comment carries the commenter’s name, the text and the date. If the merchant has replied, the reply is in reply and the time it was saved in replied_at; both are null otherwise. Show the reply under the comment. The commenter’s email address is never returned.

Comment rules:

• The name can be up to 100 characters and the comment up to 2,000. Longer ones fail with 400.
• Comments are plain text, and markup is removed. An invalid email address, or a comment left empty once markup is removed, fails with 422.
• Each comment is stored with the shopper’s IP address so the merchant can block it. Send Client-Ip when you call with a secret key, or every comment carries your server’s address.

When the merchant changes a blog’s setting:

• Turning comments off hides the comments already there: List Comments returns an empty list and the article’s comments.count is 0. Nothing is deleted, so turning comments back on shows them again.
• Switching from moderated to open doesn’t approve comments that are already waiting.

Rate limits

Over either limit, Create Comment returns 429 with the wait in the message. If your server calls the API with a secret key on behalf of shoppers, send each shopper’s IP address in Client-Ip. Without it, every shopper shares your server’s limit.

Moderating comments

The merchant moderates comments in the Papertracc app, under Marketing → Blog → Comments. In the app the merchant can:

An approved comment can be taken down at any time by moving it to pending, marking it as spam or deleting it. The change shows on the next request to List Comments, and the article’s comments.count follows it.

Nobody can edit what a commenter wrote, neither the merchant nor the commenter.

Blocklist

The merchant can block words and phrases, email addresses or whole email domains, and IP addresses or ranges. A new comment that matches goes straight to spam and is never listed. Comments already posted are not affected.

There is no other spam filter.

Alerts

When a comment is waiting for approval, members who can manage the blog get a notification in the app and by email. Each member can turn either one off under Blog comments in their notification settings. Alerts go out at most once every 15 minutes per workspace and give the number of comments waiting.

View counts

Call Count Article View when a shopper opens an article. Repeat calls from the same shopper for the same article within 6 hours are counted once. Shoppers are told apart by IP address, so a server using a secret key should send Client-Ip here too. The count appears as view_count and drives sort_by=most-viewed.