# List price migrations

> The subscriptions.migrations.list operation: GET /api/v1/subscriptions/migrations in the REST API and the subscriptions_migrations_list tool in the MCP server.

Lists the brand's price migrations in the request's mode, newest first, with their progress. Filter by
`fromPriceId`.

Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page).

## At a glance

- **REST:** `GET /api/v1/subscriptions/migrations`
- **MCP tool:** `subscriptions_migrations_list`
- **Operation ID:** `subscriptions.migrations.list`
- **Scope:** Brand
- **Permission:** `subscriptions:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `subscriptions:read` scope
- **Since:** M5

## Request

### Query parameters

| Field            | Type               | Required | Description                           |
| ---------------- | ------------------ | -------- | ------------------------------------- |
| `fromPriceId`    | `price_…` ID       | No       | Only migrations away from this price. |
| `limit`          | integer (1 to 100) | No       |                                       |
| `starting_after` | `smig_…` ID        | No       |                                       |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field                       | Type                                                                                                                 | Description                                                                                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`                    | `"list"`                                                                                                             |                                                                                                                                                         |
| `data`                      | array of object                                                                                                      |                                                                                                                                                         |
| `data[].id`                 | `smig_…` ID                                                                                                          |                                                                                                                                                         |
| `data[].object`             | `"subscription_migration"`                                                                                           |                                                                                                                                                         |
| `data[].livemode`           | boolean                                                                                                              |                                                                                                                                                         |
| `data[].brandId`            | `brd_…` ID                                                                                                           |                                                                                                                                                         |
| `data[].fromPriceId`        | `price_…` ID                                                                                                         |                                                                                                                                                         |
| `data[].toPriceId`          | `price_…` ID                                                                                                         |                                                                                                                                                         |
| `data[].currency`           | string                                                                                                               |                                                                                                                                                         |
| `data[].effective`          | one of `next_renewal`, `date`                                                                                        |                                                                                                                                                         |
| `data[].effectiveDate`      | date-time or null                                                                                                    |                                                                                                                                                         |
| `data[].noticeDays`         | integer                                                                                                              |                                                                                                                                                         |
| `data[].filter`             | object                                                                                                               |                                                                                                                                                         |
| `data[].filter.statuses`    | array of one of `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `unpaid`, `paused`, `canceled` |                                                                                                                                                         |
| `data[].filter.customerIds` | array of `cus_…` ID or null                                                                                          |                                                                                                                                                         |
| `data[].status`             | one of `scheduled`, `completed`                                                                                      | `scheduled` while changes are still waiting for their renewal; `completed` once none is.                                                                |
| `data[].counts`             | object                                                                                                               | Progress (spec §16.14).                                                                                                                                 |
| `data[].counts.matched`     | integer (at least 0)                                                                                                 | Subscriptions on the old price that the filter matched.                                                                                                 |
| `data[].counts.scheduled`   | integer (at least 0)                                                                                                 | Of those, the ones given the change.                                                                                                                    |
| `data[].counts.notified`    | integer (at least 0)                                                                                                 | Customers sent their notice.                                                                                                                            |
| `data[].counts.applied`     | integer (at least 0)                                                                                                 | Changes applied at a renewal.                                                                                                                           |
| `data[].counts.pending`     | integer (at least 0)                                                                                                 | Changes still waiting for their renewal.                                                                                                                |
| `data[].counts.skipped`     | integer (at least 0)                                                                                                 | Matched but not changed: skipped at once (`skippedAtCreation`), or dropped before their renewal because the subscription was canceled or changed again. |
| `data[].skippedAtCreation`  | object                                                                                                               | Why matching subscriptions weren't changed: `pending_update` (another change was already waiting), `cancel_scheduled` (set to end at its period end).   |
| `data[].revenue`            | object                                                                                                               | The monthly recurring amount of the changed items before and after (licensed items; metered items are billed from usage).                               |
| `data[].revenue.mrrBefore`  | money                                                                                                                |                                                                                                                                                         |
| `data[].revenue.mrrAfter`   | money                                                                                                                |                                                                                                                                                         |
| `data[].revenue.mrrDelta`   | money                                                                                                                |                                                                                                                                                         |
| `data[].firstChangeAt`      | date-time or null                                                                                                    | The first scheduled change.                                                                                                                             |
| `data[].lastChangeAt`       | date-time or null                                                                                                    | The last scheduled change.                                                                                                                              |
| `data[].version`            | integer                                                                                                              |                                                                                                                                                         |
| `data[].createdAt`          | date-time                                                                                                            |                                                                                                                                                         |
| `data[].updatedAt`          | date-time                                                                                                            |                                                                                                                                                         |
| `has_more`                  | boolean                                                                                                              |                                                                                                                                                         |
| `next_cursor`               | `smig_…` ID or null                                                                                                  |                                                                                                                                                         |

## Examples

### A price's migrations

```http
GET /api/v1/subscriptions/migrations?fromPriceId=price_01jacq4m3xf0v8w9zq2y7k5n6p
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "smig_01jacq4m3xf0v8w9zq2y7k5n6h",
      "object": "subscription_migration",
      "livemode": false,
      "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6b",
      "fromPriceId": "price_01jacq4m3xf0v8w9zq2y7k5n6p",
      "toPriceId": "price_01jacq4m3xf0v8w9zq2y7k5n6q",
      "currency": "EUR",
      "effective": "next_renewal",
      "effectiveDate": null,
      "noticeDays": 30,
      "filter": {
        "statuses": ["trialing", "active", "past_due"],
        "customerIds": null
      },
      "status": "scheduled",
      "counts": {
        "matched": 42,
        "scheduled": 40,
        "notified": 0,
        "applied": 0,
        "pending": 40,
        "skipped": 2
      },
      "skippedAtCreation": {
        "pending_update": 2,
        "cancel_scheduled": 0
      },
      "revenue": {
        "mrrBefore": {
          "amount": "400000000",
          "currency": "EUR"
        },
        "mrrAfter": {
          "amount": "480000000",
          "currency": "EUR"
        },
        "mrrDelta": {
          "amount": "80000000",
          "currency": "EUR"
        }
      },
      "firstChangeAt": "2026-11-20T10:00:00.000Z",
      "lastChangeAt": "2026-12-19T10:00:00.000Z",
      "version": 2,
      "createdAt": "2026-10-20T09:00:00.000Z",
      "updatedAt": "2026-10-20T09:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                   | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A filter or pagination value is malformed.             | Fix the fields listed in `details.issues` and send the request again.           |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | The credentials can't read this brand's subscriptions. | Ask an organization owner or admin for a role or scope that allows this action. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).