Skip to content

Feeds

Follow a blog in a feed reader, a podcast in a podcast app or an event in a calendar app, from its public feed or a customer's own private one.

Updated

Every blog has an RSS feed that feed readers accept. Its public feed lists the newest posts with their abstracts, and a customer who holds the blog can also get a private feed of their own, which carries the newest posts they may read in full and the rest with their abstracts. Everything here but the public feed needs a token (Authentication); the examples use the client from Your own front end.

Every podcast has one too, which podcast apps such as Apple Podcasts, Overcast and Pocket Casts accept: see Podcasts. Every event has an iCalendar file that calendar apps such as Google Calendar, Apple Calendar and Outlook accept, the store has a schedule of its events, and a ticket holder can get a private calendar feed: see Events.

On your Sherpo storefront this is already built in: a blog’s pages link its public feed, and feed readers find it from the page on their own. A signed-in customer holding the blog sees Your private feed beside it and in their library, where they copy its address, get a new one or turn it off. A podcast’s holder sees Listen in your app on the podcast’s page, under each episode’s player and in their library. An event’s page and its cards offer Add to calendar, with Google Calendar, Apple Calendar, Outlook and the event’s file for any other calendar. A ticket holder sees Calendar feed on the event’s card in their library. The rest of this page is for your own front end; Feeds covers them for sellers and customers.

The public feed

A blog’s public feed is at /feeds/<product id>.xml on your store’s host. It lists up to the 50 newest posts, each with its title, link, author, publish and update dates, its section and tags, its cover image and its abstract, which is the teaser you write for the post. It carries each listed post’s abstract and never a post in full, whatever the post’s access, so locked posts show their teaser as visitors see them. A post’s id is its GUID, which never changes. An unlisted blog has no public feed, and the public feed can’t be turned off. Every product read answers its public feed’s address as feed_url, with the store’s publishable key too, so a front end of your own links it from the product without another call: null while the product has no public feed or the store has no verified domain.

Read a product’s feeds

GET /v1/stores/{store}/products/{product}/feeds answers both, with read:

curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/my-blog/feeds' \
  --header 'Authorization: Bearer ctk_...'
getFeeds 200json
{
  "product_id": "<product id>",
  "public": {
    "path": "/feeds/<product id>.xml",
    "url": "https://<your store host>/feeds/<product id>.xml"
  },
  "private": {
    "available": true,
    "blocked": false,
    "feed": {
      "id": "<feed id>",
      "path": "/feeds/private/fd_....xml",
      "url": "https://<your store host>/feeds/private/fd_....xml",
      "created_at": "2026-11-10T14:30:00.000Z"
    }
  }
}
  • public is null while a blog or a podcast is unlisted. An event’s is its iCalendar file, /feeds/<product id>.ics, wherever its page opens, unlisted too.
  • private.available says whether the customer may hold a private feed: they hold the product, its seller hasn’t turned private feeds off, and sharing hasn’t turned theirs off. private.feed is theirs once they get one, else null.
  • private.blocked is true once sharing turned the customer’s private feed off (see Sharing); tell them to contact the store.
  • A private feed’s url is a secret: anyone who has it reads the customer’s posts. Show it to the customer alone and never put it in a page others see. Its path and url are null over MCP, to staff acting as the customer, and for a token without profile:write.

The private feed

POST /v1/stores/{store}/products/{product}/feeds/private gives the customer a private feed, or a new address for theirs, the old one stopping at once. It needs profile:write and answers the feed as private.feed above. It answers not_entitled when the customer holds nothing of the product, conflict on status (disabled) when its seller turned private feeds off, and conflict on status (blocked) when sharing turned the customer’s off.

curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/my-blog/feeds/private' \
  --header 'Authorization: Bearer ctk_...'

DELETE /v1/stores/{store}/products/{product}/feeds/private turns it off, with profile:write, and answers conflict on status (revoked) when there’s none. Getting a new address and turning a feed off are REST operations alone, never MCP tools.

A private feed lists the same posts as the public feed and carries what its customer may open, decided on every fetch: the 20 newest of those they may read come whole, the rest with their abstract. A post older than the 50 newest isn’t in it, even one they may read. When their access ends, the feed stops answering, and it answers again if they hold the product once more. Images inside a post are linked by addresses that work for an hour from each fetch, so a copied image link stops working soon after. Downloads, audio and video open from the post’s page.

Podcasts

A podcast’s feeds work as a blog’s do, at the same addresses and through the same operations, and carry the tags podcast apps read: the show’s artwork, author, category and explicit flag, and for each episode its audio as an enclosure with its length and type, its duration and artwork, and its transcript and chapters in the Podcasting 2.0 tags when it has them. An episode’s id is its GUID, which never changes. A feed lists only the episodes its reader may listen to, up to the 50 newest: the public feed those anyone may, a private feed those its customer may. Locked episodes are left out of both, so they never take a place among the 50.

An episode’s audio, transcript and chapters are served under its feed, at addresses that hold from one fetch to the next, so a podcast app can download an episode whenever it likes. The audio’s extension follows its type, and any extension reaches it:

Part Public feed Private feed
Audio /feeds/<product id>/<entry id>/audio.<ext> /feeds/private/fd_.../<entry id>/audio.<ext>
Transcript (WebVTT) /feeds/<product id>/<entry id>/transcript.vtt /feeds/private/fd_.../<entry id>/transcript.vtt
Chapters (JSON chapters) /feeds/<product id>/<entry id>/chapters.json /feeds/private/fd_.../<entry id>/chapters.json

Each is decided again on every fetch, so an episode a customer loses access to stops playing from their private feed at once, and fetching a private feed’s episodes counts its readers as fetching the feed does. The audio answers ranges, as players ask for them, and is never cached. A public feed’s transcript and chapters can be read from any web player. A private feed is marked for no directory to list it, and never names the owner email.

An episode is in a feed once its audio is an MP3, M4A or AAC file with a measured size, played in place and not protected; an audio file that’s still being converted joins once it is.

The seller sets what directories read on the podcast’s settings: its category, whether it’s explicit, and the owner email directories verify it with. The public feed’s address is the one to submit; its url is also the product’s feed_url, on the product reads here and in the merchant API.

Events

An event’s sessions open in calendar apps from three iCalendar addresses on your store’s host, each a feed a calendar app can subscribe to and fetch again about every hour:

Calendar Address Carries
The event’s file /feeds/<product id>.ics Every session of the event, for anyone its page opens to, unlisted events too.
The store’s schedule /feeds/schedule.ics The sessions of every listed event, upcoming ones first and ended ones for 30 days after, up to 50 an event and 500 in all.
A private calendar feed /feeds/private/fd_....ics Every session of the event, for one ticket holder, with its location.

Each session is an event of its own in the calendar, with the event’s title, its subtitle and page in the notes, and its start and end in UTC, so every calendar shows it in its own time zone. Its id stays the same from one fetch to the next, so a moved session moves in the calendar and a removed one leaves it. Its location is the session’s own venue, then the event’s venue and address, on one line, or its online_label when it has no place. When the seller keeps the location to ticket holders, the event’s file and the schedule leave it out, as the event’s page does; a private calendar feed always carries it. The event’s file and the schedule may be kept for up to 10 minutes, so a change to the event, a location the seller stops showing to everyone included, can take that long to leave them.

The event’s file is answered on the product read as event.ics, its path and its url on the store’s verified domain (null while it has none). Each of event.sessions also answers add_to_calendar: links that open the session, filled in, in Google Calendar (google), Outlook.com (outlook) and Outlook for work or school accounts (office). They carry the location only when the caller sees it.

getProduct 200 (part)json
{
  "event": {
    "ics": {
      "path": "/feeds/<product id>.ics",
      "url": "https://<your store host>/feeds/<product id>.ics"
    },
    "sessions": [
      {
        "id": "<session id>",
        "starts_at": "2026-12-03T18:00:00.000Z",
        "ends_at": "2026-12-03T20:00:00.000Z",
        "time_zone": "Europe/Rome",
        "add_to_calendar": {
          "google": "https://calendar.google.com/calendar/render?action=TEMPLATE&text=...",
          "outlook": "https://outlook.live.com/calendar/0/action/compose?rru=addevent&subject=...",
          "office": "https://outlook.office.com/calendar/0/action/compose?rru=addevent&subject=..."
        }
      }
    ]
  }
}

A ticket holder’s private calendar feed works as a blog’s private feed does, through the same operations under the event: read its feeds, get one or a new address and turn it off. It answers while they hold a ticket and stops once their ticket ends. It’s counted for sharing as any private feed is, its readers being calendar apps, and a new address or one turned off is emailed in the same way. The seller can turn private feeds off on the event’s settings (feeds.private), which stops every one at once.

Sharing

A private feed is for one person. Each fetch counts who read it: a feed reader, podcast app or calendar app on one network counts once, so a phone moving across its carrier’s addresses stays one reader, and services that fetch for many people at once, such as Feedly or Inoreader, count for the subscribers they report on each network they fetch from. When a feed serves more readers in 30 days than its limit, its address stops working, it moves to a new one, and the customer gets an email with the new address. The limit leaves room for a person’s own devices and a change of apps or networks; the API never tells it to the customer, so don’t show it.

After 3 new addresses in 30 days, a feed shared once more stops and none replaces it: the customer gets one email saying their private feed was turned off, private.blocked turns true, and they can’t get a new one until the seller turns it back on from the customer’s page, which counts sharing afresh. A seller can also change a customer’s limit, or revoke their feed, from there.

Type to search…

↑↓ navigate↵ selectEsc close