Subscriptions

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, or update the shipping address snapshot. All routes require an authenticated Medusa Admin user.

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

number

Number of results per page. Defaults to 20.

number

Zero-based result offset for pagination.

string

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

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.

string

Sort direction. One of asc or desc.

string | string[]

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

string

Filter by customer ID.

string

Filter by product ID.

string

Filter by variant ID.

string

ISO datetime lower bound for next_renewal_at.

string

ISO datetime upper bound for next_renewal_at.

boolean

Filter to trial subscriptions only.

boolean

Filter by whether the next cycle is skipped.

Response

object[]

required

Array of subscription list items.

Show subscription properties

string

Subscription ID.

string

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

string

Current subscription status.

object

Customer summary including id, full_name, and email.

object

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

object

Cadence with interval, value, and label.

string

Technical billing anchor date.

string

Projected next renewal shown in Admin when skip_next_cycle is enabled.

object

Trial info with is_trial and trial_ends_at.

object

Applied discount with type, value, and label.

boolean

Whether the next billing cycle is skipped.

string

Last update timestamp.

number

required

Total matching records.

number

required

Page size used.

number

required

Result offset used.

Response example

{
  "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

string

required

Subscription ID.

Response

Returns a subscription object with all list fields plus:

object

required

Show additional detail fields

string

Creation timestamp.

string

When the subscription became active.

string | null

When the subscription was paused, or null.

string | null

When the subscription was cancelled, or null.

string | null

Last successful renewal timestamp.

object

Full shipping address snapshot.

object | null

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

Response example

{
  "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"
    }
  }
}

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

string

required

Medusa order ID.

Response

boolean

required

Whether the order is linked to a 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

Response example

{
  "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"
    }
  }
}

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

string

required

Subscription ID.

Body parameters

string

Optional reason for the pause.

string

ISO datetime for when the pause takes effect. Optional.

Request example

{
  "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

string

required

Subscription ID.

Body parameters

string

ISO datetime for when the subscription resumes. Optional.

boolean

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

Request example

{
  "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

string

required

Subscription ID.

Body parameters

string

Optional cancellation reason.

string

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

Request example

{
  "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

string

required

Subscription ID.

Body parameters

string

required

Target variant ID for the plan change.

string

required

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

number

required

New billing cadence as a positive integer.

string

ISO datetime when the change becomes effective. Optional.

Request example

{
  "variant_id": "variant_456",
  "frequency_interval": "month",
  "frequency_value": 2,
  "effective_at": "2026-05-01T00:00:00.000Z"
}

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

string

required

Subscription ID.

Body parameters

string

required

First name.

string

required

Last name.

string

required

Primary address line.

string

required

City.

string

required

Postal or ZIP code.

string

required

Two-letter ISO country code.

string

Company name. Optional.

string

Secondary address line. Optional.

string

Province or state. Optional.

string

Phone number. Optional.

Request example

{
  "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

Admin API

Store API

Status values

GET /admin/subscriptions

Query parameters

Response

Errors

GET /admin/subscriptions/:id

Path parameters

Response

Errors

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

Path parameters

Response

POST /admin/subscriptions/:id/pause

Path parameters

Body parameters

Errors

POST /admin/subscriptions/:id/resume

Path parameters

Body parameters

Errors

POST /admin/subscriptions/:id/cancel

Path parameters

Body parameters

Errors

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

Path parameters

Body parameters

Errors

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

Path parameters

Body parameters

Errors

​Status values

​GET /admin/subscriptions

​Query parameters

​Response

​Errors

​GET /admin/subscriptions/:id

​Path parameters

​Response

​Errors

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

​Path parameters

​Response

​POST /admin/subscriptions/:id/pause

​Path parameters

​Body parameters

​Errors

​POST /admin/subscriptions/:id/resume

​Path parameters

​Body parameters

​Errors

​POST /admin/subscriptions/:id/cancel

​Path parameters

​Body parameters

​Errors

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

​Path parameters

​Body parameters

​Errors

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

​Path parameters

​Body parameters

​Errors

Status values

GET /admin/subscriptions

Query parameters

Response

Errors

GET /admin/subscriptions/:id

Path parameters

Response

Errors

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

Path parameters

Response

POST /admin/subscriptions/:id/pause

Path parameters

Body parameters

Errors

POST /admin/subscriptions/:id/resume

Path parameters

Body parameters

Errors

POST /admin/subscriptions/:id/cancel

Path parameters

Body parameters

Errors

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

Path parameters

Body parameters

Errors

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

Path parameters

Body parameters

Errors