---
title: "Feeds"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Feeds

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](/customer-api/authentication)); the examples use the client from [Your own front end](/customer-api/self-hosted#a-minimal-client).

Every podcast has one too, which podcast apps such as Apple Podcasts, Overcast and Pocket Casts accept: see [Podcasts](#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](#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](/overview/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`](/customer-api/reference/get-feeds) answers both, with `read`:

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

```json title="getFeeds 200"
{
  "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](#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`](/customer-api/reference/rotate-feed) 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.

```bash
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`](/customer-api/reference/revoke-feed) 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](/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.

```json title="getProduct 200 (part)"
{
  "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](#read-a-products-feeds), [get one or a new address](#the-private-feed) and turn it off. It answers while they hold a ticket and stops once their ticket ends. It's counted for [sharing](#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.

Source: https://docs.sherpo.io/customer-api/feeds/index.mdx
