---
title: Subscription Data Source
slug: experience/subscription-data-source
docTags: 
createdAt: 2026-05-11T15:20:15.660Z
---

## Overview

The `subscription` data source fetches the subscription plans available for purchase from the Catalog API. It drives subscription walls, plan pickers, and upgrade flows.

## When to use this

Use `subscription` when you need to display a list of purchasable subscription plans. 

## Basic Example

```json
{
  "type": "subscription",
  "contextKey": "plans",
  "filter": {
    "publication": {
      "id": { "value": ":publicationId" }
    }
  }
}
```

## Configuration

### Type-specific properties

| Property              | Type    | Default | Description                                               |
| --------------------- | ------- | ------- | --------------------------------------------------------- |
| filter                | object  | —       | Narrows which plans are returned from the API             |
| localSort             | object  | —       | Client-side sort applied after fetching                   |
| excludePurchased      | boolean | `false` | Exclude plans the user has already purchased              |
| excludeSmaller        | boolean | `false` | Exclude plans shorter than the user's active subscription |
| excludeHidden         | boolean | `true`  | Exclude plans marked as hidden                            |
| onlyAdditionalUnlocks | boolean | `false` | Return only plans that unlock additional past issues      |
| fetchOptions          | object  | —       | Optional fetch options (e.g. `totalCount: false`)         |

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

### Filter properties

| Filter key  | Type                 | Description                                                     |
| ----------- | -------------------- | --------------------------------------------------------------- |
| publication | PublicationFilter    | Restrict plans to a specific publication — use `publication.id` |
| properties  | MapFilter            | Filter by custom plan properties                                |
| purchased   | `{ value: boolean }` | Filter to purchased or non-purchased plans                      |
| productId   | StringFilter         | Filter by product ID                                            |

Supports `AND`, `OR`, and `condition`.

### localSort properties

Applied client-side after fetching. Interacts with pagination — use with care.

| Property  | Values                | Default   |
| --------- | --------------------- | --------- |
| criteria  | `DEFAULT`, `DURATION` | `DEFAULT` |
| direction | `ASC`, `DESC`         | `ASC`     |

## Testing Notes / Edge Cases

- **Entitlement check**: This data source returns available plans, not the user's current subscription status.

## Related Topics

- [TODO insert link to Data Sources Overview](#)