---
title: Period Data Source
slug: experience/period-data-source
docTags: 
createdAt: 2026-05-11T15:54:57.274Z
---

## Overview

The `period` data source generates a list of time periods — years or months — derived from the publication dates of issues in the Catalog API. It enables archive navigation by letting users browse issues organized by when they were published.

## When to use this

Use `period` when building an archive or back-issue browser where users navigate by year or month. The list of periods is calculated dynamically from actual issue publication dates.

## Basic Example

```json
{
  "type": "period",
  "contextKey": "archiveYears",
  "interval": "YEAR",
  "issueFilter": {
    "publication": {
      "id": { "value": ":publicationId" }
    }
  }
}
```

## Configuration

### Type-specific properties

| Property    | Type                  | Default  | Description                                                                         |
| ----------- | --------------------- | -------- | ----------------------------------------------------------------------------------- |
| interval    | `'YEAR'` \| `'MONTH'` | `'YEAR'` | Granularity of the generated periods                                                |
| issueFilter | object                | —        | Filters which issues are used to derive the periods                                 |
| order       | `'ASC'` \| `'DESC'`   | `'DESC'` | Order in which periods are returned                                                 |
| startOffset | number                | `0`      | Subtract this many intervals from the current date to define the start of the range |
| format      | object                | —        | Customize display labels — `{ formatText, translateWithKeys? }`                     |

For common properties (`contextKey`, `limit`, `batchSize`, etc.) see [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)

### issueFilter properties

Scopes which issues are considered when generating periods. Uses StorefrontIssueFilter.

:::BlockQuote
**Deprecated type.** StorefrontIssueFilter is deprecated in favour of ContentFilter. The issueFilter property will be migrated to use contentFilter (same shape as the content data source) in a future release.
:::

| Filter key      | Type                          | Description                                          |
| --------------- | ----------------------------- | ---------------------------------------------------- |
| publication     | PublicationFilter             | Scope to a specific publication — use publication.id |
| publicationDate | DateFilter                    | Restrict to issues published within a date range     |
| age             | \{ amount, unit, operation? } | Restrict to issues of a certain age relative to now  |
| properties      | MapFilter                     | Filter by custom issue properties                    |
| purchasable     | \{ value: boolean }           | Filter to purchasable or non-purchasable issues      |
| purchased       | \{ value: boolean }           | Filter to purchased or non-purchased issues          |
| id              | StringFilter                  | Filter by specific issue ID                          |

Supports AND, OR, and condition.

### Item structure

Each generated item contains:

| Field | Type   | Description                                               |
| ----- | ------ | --------------------------------------------------------- |
| year  | number | The year of the period                                    |
| month | number | The month (1–12), only present when `interval` is `MONTH` |
| label | string | Human-readable label (e.g. `"2024"` or `"January 2024"`)  |

## Testing Notes / Edge Cases

- **No issues = no periods**: If a publication has no published issues the list is empty.
- `interval`** default is **`YEAR`: Omitting it generates year-level periods, not months.
- `order`** default is **`DESC`: Periods are newest-first. Set `"ASC"` to reverse.
- **Gaps in publishing**: Months/years without published issues do not appear in the list.

## Related Topics

- [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)
- [Content Data Source](docId\:dfdY32ZAnYtMHKUhzXOrb)