> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Review your subscription base with subscriptions reports

Generate a new subscriptions report to see the state and details of every subscription, so you can understand the shape of your subscription base and discover actionable patterns.

---

## What's new?

We've added a new subscriptions report to the Paddle platform. It provides current details for every subscription, helping you gain a deeper understanding of your subscription base and discover actionable patterns.

## How it works

[Reports](https://developer.paddle.com/build/reports.md) in Paddle let you export information from your account to import into accounting software, ERPs, and other business intelligence tools.

To complement the existing reports in Paddle Billing, we've added a new [subscriptions report](https://developer.paddle.com/build/reports/subscriptions.md) that gives you a row for every subscription, with contextual data for each one.

Use it to see how subscriptions break down by status, billing cadence, currency, and country, or to build segments you can act on, like trials that haven't converted and subscriptions with an overdue payment.

For this first release, you can filter subscriptions reports by:

- `subscription_status`: one or more status of `active`, `canceled`, `past_due`, `paused`, and `trialing`.
- `subscription_created_at`: the date range when subscriptions were created. If you don't pass this filter, the report includes every subscription ever created.
- `customer_country_code`: one or more customer countries, using two-letter ISO 3166-1 alpha-2 codes.

### Example

This example creates a subscriptions report for active and trialing subscriptions from customers in the United States and United Kingdom:

{% api-example method="POST" path="/reports" href="/api-reference/reports/create-report" %}

```json
{
  "type": "subscriptions",
  "filters": [
    {
      "name": "subscription_status",
      "value": ["active", "trialing"]
    },
    {
      "name": "customer_country_code",
      "value": ["US", "GB"]
    }
  ]
}
```

```json
{
  "data": {
    "id": "rep_01hkdmvwn3q7dg9zj8pt5xr4bc",
    "type": "subscriptions",
    "rows": null,
    "status": "pending",
    "filters": [
      {
        "name": "subscription_status",
        "value": ["active", "trialing"],
        "operator": null
      },
      {
        "name": "customer_country_code",
        "value": ["US", "GB"],
        "operator": null
      }
    ],
    "expires_at": null,
    "created_at": "2026-08-19T09:12:44.301Z",
    "updated_at": "2026-08-19T09:12:44.301Z"
  },
  "meta": {
    "request_id": "5c2f8d41-9ab3-4e7c-b6d2-3f81ea470c95"
  }
}
```

{% /api-example %}

## Next steps

The subscriptions report is available now in version `1` of the Paddle API and in the Paddle dashboard.

It's a non-breaking change, meaning it doesn't impact existing integrations.

Check out the [subscriptions report guide](https://developer.paddle.com/build/reports/subscriptions.md) and the [report entity overview](https://developer.paddle.com/api-reference/reports.md) in the API reference to get started.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `type` | Enum value | added | Report | subscriptions added. |
| `subscription_status` | Field | added | Reports | Filter subscriptions reports by subscription status. |
| `subscription_created_at` | Field | added | Reports | Filter subscriptions reports by the date a subscription was created. |
| `customer_country_code` | Field | added | Reports | Filter subscriptions reports by customer country, using two-letter ISO 3166-1 alpha-2 codes. |