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

# Subscriptions

> Manage subscription lifecycle from the Medusa Admin: list, inspect, pause, resume, cancel, schedule plan changes, update shipping addresses, and manage payment methods.

The subscriptions endpoints give you full control over individual subscription records. You can query the paginated list for DataTable views, fetch a full detail payload for a specific subscription, and trigger lifecycle mutations — pause, resume, cancel, schedule a future plan change, update the shipping address snapshot, or change the renewal payment method. All routes require an authenticated Medusa Admin user.

> [!NOTE]
>
> All routes require an authenticated Medusa Admin user. Unauthenticated requests return `401`.

## Status values

| Value | Meaning |
| - | - |
| `active` | Subscription is billing normally |
| `paused` | Subscription is on hold |
| `cancelled` | Subscription has been terminated |
| `past_due` | Last renewal failed; dunning may be active |

***

## GET /admin/subscriptions

Returns the paginated subscription list for Admin DataTable views.

### Query parameters

**limit** `number`

Number of results per page. Defaults to 20.

**offset** `number`

Zero-based result offset for pagination.

**q** `string`

Free-text search across customer name, email, and reference.

**order** `string`

Field to sort by. Supported database-backed fields: `created_at`, `updated_at`, `status`, `frequency_interval`, `frequency_value`, `next_renewal_at`, `trial_ends_at`, `skip_next_cycle`. Supported in-memory fields: `customer_name`, `customer_email`, `product_title`, `variant_title`, `discount_value`.

**direction** `string`

Sort direction. One of `asc` or `desc`.

**status** `string | string[]`

Filter by subscription status. Accepts a single value or an array.

**customer\_id** `string`

Filter by customer ID.

**product\_id** `string`

Filter by product ID.

**variant\_id** `string`

Filter by variant ID.

**next\_renewal\_from** `string`

ISO datetime lower bound for `next_renewal_at`.

**next\_renewal\_to** `string`

ISO datetime upper bound for `next_renewal_at`.

**is\_trial** `boolean`

Filter to trial subscriptions only.

**skip\_next\_cycle** `boolean`

Filter by whether the next cycle is skipped.

### Response

**subscriptions** `object[]` *required*

Array of subscription list items.

**subscription properties**

**id** `string`

Subscription ID.

**reference** `string`

Human-readable reference (e.g. `SUB-001`).

**status** `string`

Current subscription status.

**customer** `object`

Customer summary including `id`, `full_name`, and `email`.

**product** `object`

Product summary including `product_id`, `product_title`, `variant_id`, `variant_title`, and `sku`.

**frequency** `object`

Cadence with `interval`, `value`, and `label`.

**next\_renewal\_at** `string`

Technical billing anchor date.

**effective\_next\_renewal\_at** `string`

Projected next renewal shown in Admin when `skip_next_cycle` is enabled.

**trial** `object`

Trial info with `is_trial` and `trial_ends_at`.

**discount** `object`

Applied discount with `type`, `value`, and `label`.

**skip\_next\_cycle** `boolean`

Whether the next billing cycle is skipped.

**updated\_at** `string`

Last update timestamp.

**count** `number` *required*

Total matching records.

**limit** `number` *required*

Page size used.

**offset** `number` *required*

Result offset used.

```json Response example theme={null}
{
  "subscriptions": [
    {
      "id": "sub_123",
      "reference": "SUB-001",
      "status": "active",
      "customer": {
        "id": "cus_123",
        "full_name": "Jane Doe",
        "email": "jane@example.com"
      },
      "product": {
        "product_id": "prod_123",
        "product_title": "Coffee Subscription",
        "variant_id": "variant_123",
        "variant_title": "1 kg",
        "sku": "COFFEE-1KG"
      },
      "frequency": {
        "interval": "month",
        "value": 1,
        "label": "Every month"
      },
      "next_renewal_at": "2026-04-15T10:00:00.000Z",
      "effective_next_renewal_at": "2026-04-15T10:00:00.000Z",
      "trial": {
        "is_trial": false,
        "trial_ends_at": null
      },
      "discount": {
        "type": "percentage",
        "value": 10,
        "label": "10% off"
      },
      "skip_next_cycle": false,
      "updated_at": "2026-03-28T12:00:00.000Z"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid query parameter shape, unsupported query value, or unsupported sort field |

***

## GET /admin/subscriptions/:id

Returns the full detail payload for a single subscription.

### Path parameters

**id** `string` *required*

Subscription ID.

### Response

Returns a `subscription` object with all list fields plus:

**subscription** `object` *required*

**additional detail fields**

**created\_at** `string`

Creation timestamp.

**started\_at** `string`

When the subscription became active.

**paused\_at** `string | null`

When the subscription was paused, or `null`.

**cancelled\_at** `string | null`

When the subscription was cancelled, or `null`.

**last\_renewal\_at** `string | null`

Last successful renewal timestamp.

**shipping\_address** `object`

Full shipping address snapshot.

**pending\_update\_data** `object | null`

Scheduled plan change data, or `null` when none is pending.

**payment\_provider\_id** `string | null`

Configured payment provider identifier, or `null`.

**payment\_method** `object | null`

Resolved summary of the current saved payment method, or `null`.

```json Response example theme={null}
{
  "subscription": {
    "id": "sub_123",
    "reference": "SUB-001",
    "status": "active",
    "customer": { "id": "cus_123", "full_name": "Jane Doe", "email": "jane@example.com" },
    "product": {
      "product_id": "prod_123",
      "product_title": "Coffee Subscription",
      "variant_id": "variant_123",
      "variant_title": "1 kg",
      "sku": "COFFEE-1KG"
    },
    "frequency": { "interval": "month", "value": 1, "label": "Every month" },
    "next_renewal_at": "2026-04-15T10:00:00.000Z",
    "effective_next_renewal_at": "2026-04-15T10:00:00.000Z",
    "trial": { "is_trial": false, "trial_ends_at": null },
    "discount": { "type": "percentage", "value": 10, "label": "10% off" },
    "skip_next_cycle": false,
    "updated_at": "2026-03-28T12:00:00.000Z",
    "created_at": "2026-03-01T10:00:00.000Z",
    "started_at": "2026-03-01T10:00:00.000Z",
    "paused_at": null,
    "cancelled_at": null,
    "last_renewal_at": "2026-03-15T10:00:00.000Z",
    "shipping_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "company": null,
      "address_1": "Main Street 1",
      "address_2": null,
      "city": "Warsaw",
      "postal_code": "00-001",
      "province": "Mazowieckie",
      "country_code": "PL",
      "phone": "+48123123123"
    },
    "pending_update_data": {
      "variant_id": "variant_456",
      "variant_title": "2 kg",
      "frequency_interval": "month",
      "frequency_value": 2,
      "effective_at": "2026-05-01T00:00:00.000Z"
    },
    "payment_provider_id": "pp_stripe_stripe",
    "payment_method": {
      "id": "pm_123",
      "provider_id": "pp_stripe_stripe",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 4,
      "exp_year": 2030,
      "created_at": 1700000000,
      "is_current": true
    }
  }
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `404` | `not_found` | Subscription does not exist |

***

## GET /admin/orders/:id/subscription-summary

Returns the lightweight subscription context used by the custom `Subscription` widget on the native Medusa order detail page.

### Path parameters

**id** `string` *required*

Medusa order ID.

### Response

**summary.is\_subscription\_order** `boolean` *required*

Whether the order is linked to a subscription.

**summary.subscription** `object | null`

Subscription widget payload, or `null` for one-time orders.

When linked, `summary.subscription` includes:

* `id`
* `reference`
* `status`
* `frequency_label`
* `discount`
* `next_renewal_at`
* `effective_next_renewal_at`

```json Response example theme={null}
{
  "summary": {
    "is_subscription_order": true,
    "subscription": {
      "id": "sub_123",
      "reference": "SUB-001",
      "status": "active",
      "frequency_label": "Every 2 weeks",
      "discount": {
        "type": "percentage",
        "value": 5,
        "label": "5% off"
      },
      "next_renewal_at": "2026-05-07T10:00:00.000Z",
      "effective_next_renewal_at": "2026-05-07T10:00:00.000Z"
    }
  }
}
```

> [!NOTE]
>
> The `discount` field is derived from the subscription's `pricing_snapshot`, not from Medusa's built-in order summary rows.

***

## POST /admin/subscriptions/:id/pause

Pauses an active subscription. All mutation routes return the refreshed full detail payload.

### Path parameters

**id** `string` *required*

Subscription ID.

### Body parameters

**reason** `string`

Optional reason for the pause.

**effective\_at** `string`

ISO datetime for when the pause takes effect. Optional.

```json Request example theme={null}
{
  "reason": "customer requested temporary stop",
  "effective_at": "2026-04-01T00:00:00.000Z"
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid body payload |
| `404` | `not_found` | Subscription does not exist |
| `409` | `conflict` | Subscription cannot be paused from its current state |

***

## POST /admin/subscriptions/:id/resume

Resumes a paused subscription.

### Path parameters

**id** `string` *required*

Subscription ID.

### Body parameters

**resume\_at** `string`

ISO datetime for when the subscription resumes. Optional.

**preserve\_billing\_anchor** `boolean`

When `true`, keeps the original billing anchor date. Optional.

```json Request example theme={null}
{
  "resume_at": "2026-04-15T00:00:00.000Z",
  "preserve_billing_anchor": true
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid body payload |
| `404` | `not_found` | Subscription does not exist |
| `409` | `conflict` | Subscription cannot be resumed from its current state |

***

## POST /admin/subscriptions/:id/cancel

Cancels a subscription immediately or at end of cycle.

### Path parameters

**id** `string` *required*

Subscription ID.

### Body parameters

**reason** `string`

Optional cancellation reason.

**effective\_at** `string`

When to apply the cancellation. One of `immediately` or `end_of_cycle`. Optional.

```json Request example theme={null}
{
  "reason": "retention flow failed",
  "effective_at": "end_of_cycle"
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid body payload |
| `404` | `not_found` | Subscription does not exist |
| `409` | `conflict` | Subscription cannot be cancelled from its current state |

***

## POST /admin/subscriptions/:id/schedule-plan-change

Stores a future plan or cadence update in `pending_update_data`. The change is applied at the next renewal or at the specified `effective_at` date.

### Path parameters

**id** `string` *required*

Subscription ID.

### Body parameters

**variant\_id** `string` *required*

Target variant ID for the plan change.

**frequency\_interval** `string` *required*

New billing interval. One of `week`, `month`, or `year`.

**frequency\_value** `number` *required*

New billing cadence as a positive integer.

**effective\_at** `string`

ISO datetime when the change becomes effective. Optional.

```json Request example theme={null}
{
  "variant_id": "variant_456",
  "frequency_interval": "month",
  "frequency_value": 2,
  "effective_at": "2026-05-01T00:00:00.000Z"
}
```

> [!NOTE]
>
> `pending_update_data` is returned inside the refreshed subscription detail payload after the change is scheduled.

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid body payload |
| `404` | `not_found` | Subscription does not exist |
| `409` | `conflict` | Plan change is not allowed for the current subscription state |

***

## POST /admin/subscriptions/:id/update-shipping-address

Updates the subscription shipping address snapshot used by Admin and future operational flows.

### Path parameters

**id** `string` *required*

Subscription ID.

### Body parameters

**first\_name** `string` *required*

First name.

**last\_name** `string` *required*

Last name.

**address\_1** `string` *required*

Primary address line.

**city** `string` *required*

City.

**postal\_code** `string` *required*

Postal or ZIP code.

**country\_code** `string` *required*

Two-letter ISO country code.

**company** `string`

Company name. Optional.

**address\_2** `string`

Secondary address line. Optional.

**province** `string`

Province or state. Optional.

**phone** `string`

Phone number. Optional.

```json Request example theme={null}
{
  "first_name": "Anna",
  "last_name": "Nowak",
  "company": "ACME",
  "address_1": "Nowa 2",
  "address_2": "lok. 4",
  "city": "Krakow",
  "postal_code": "30-001",
  "province": "Malopolskie",
  "country_code": "PL",
  "phone": "+48111111111"
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid body payload |
| `404` | `not_found` | Subscription does not exist |

***

## GET /admin/subscriptions/:id/payment-methods

Lists the saved payment methods of the subscription's customer for the subscription's payment provider.

### Path parameters

**id** `string` *required*

Subscription ID.

### Response

**payment\_provider\_id** `string | null`

The payment provider ID associated with the subscription, or `null` if none is configured.

**payment\_methods** `object[]` *required*

**payment method fields**

**id** `string`

Payment method identifier.

**provider\_id** `string`

Payment provider identifier.

**type** `string`

Type of payment method (e.g. `card`).

**brand** `string | null`

Card brand (e.g. `visa`, `mastercard`).

**last4** `string | null`

Last 4 digits of the card number.

**exp\_month** `number | null`

Card expiration month.

**exp\_year** `number | null`

Card expiration year.

**is\_current** `boolean`

Whether this is the payment method currently assigned to the subscription.

```json Response example theme={null}
{
  "payment_provider_id": "pp_stripe_stripe",
  "payment_methods": [
    {
      "id": "pm_123",
      "provider_id": "pp_stripe_stripe",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 4,
      "exp_year": 2030,
      "created_at": 1700000000,
      "is_current": true
    }
  ]
}
```

### Errors

| Code | Error | Meaning |
| - | - | - |
| `404` | `not_found` | Subscription does not exist |

***

## POST /admin/subscriptions/:id/payment-method

Changes the payment method the subscription renews with.

### Path parameters

**id** `string` *required*

Subscription ID.

### Body parameters

**payment\_method\_id** `string` *required*

Identifier of the saved payment method.

**provider\_id** `string`

Payment provider identifier. Optional if the subscription already has a configured provider.

```json Request example theme={null}
{
  "payment_method_id": "pm_123",
  "provider_id": "pp_stripe_stripe"
}
```

### Response

Returns the full subscription detail payload (`SubscriptionAdminDetailResponse`).

### Errors

| Code | Error | Meaning |
| - | - | - |
| `400` | `invalid_data` | Invalid body payload, unknown payment method, or payment method not owned by the customer |
| `404` | `not_found` | Subscription does not exist |
| `409` | `conflict` | Subscription status does not allow updating the payment method |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.