Admin API: subscriptions endpoints

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

limit

number

Number of results per page. Defaults to 20.

offset

number

Zero-based result offset for pagination.

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.

Show subscription properties

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.

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:

subscription

object

required

Show 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.

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

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

reason

string

Optional reason for the pause.

effective_at

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

resume_at

string

ISO datetime for when the subscription resumes. Optional.

preserve_billing_anchor

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

reason

string

Optional cancellation reason.

effective_at

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

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.

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

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.

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

​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

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