Renewals

The renewal cycle endpoints expose the Admin renewal queue and let you act on individual cycles. You can list scheduled or failed cycles for DataTable views, fetch a full detail payload including attempt history and approval state, force-run a cycle manually, and approve or reject pending subscription changes before a cycle executes. All routes require an authenticated Medusa Admin user. All mutations are workflow-backed and return the refreshed detail payload.

All routes require an authenticated Medusa Admin user. Unauthenticated requests return 401.

Status values

Value	Meaning
`scheduled`	Cycle is queued for its scheduled date
`processing`	Cycle execution is in progress
`succeeded`	Cycle completed successfully
`failed`	Cycle failed; attempt history is available in detail

Approval status values: pending, approved, rejected. When approval is not required, the approval object returns status: null. Attempt status values: processing, succeeded, failed.

GET /admin/renewals

Returns the paginated renewal queue for Admin DataTable views.

Query parameters

number

Number of results per page.

number

Zero-based result offset for pagination.

string

Free-text search across subscription reference, customer name, and product title.

string

Field to sort by. Database-backed: scheduled_for, updated_at, created_at, status, approval_status, processed_at. In-memory: last_attempt_status, subscription_reference, customer_name, product_title, order_display_id.

string

Sort direction. One of asc or desc.

string | string[]

Filter by cycle status.

string | string[]

Filter by approval status.

string

ISO datetime lower bound for scheduled_for.

string

ISO datetime upper bound for scheduled_for.

string | string[]

Filter by the status of the most recent attempt.

string

Filter to renewals for a specific subscription.

string

Filter by the ID of the order generated by a renewal.

Response

object[]

required

Array of renewal cycle list items.

Show renewal properties

string

Renewal cycle ID.

string

Cycle status.

object

Subscription summary including reference, status, customer name, and product info.

string

Operational renewal date stored on the cycle.

string

Projected delivery date when the linked subscription has a skipped next cycle.

string | null

Status of the most recent attempt.

string | null

Timestamp of the most recent attempt.

object

Approval summary with required, status, decided_at, decided_by, and reason.

object | null

Generated order summary, or null if no order has been created.

string

Last update timestamp.

number

required

Total matching records.

number

required

Page size used.

number

required

Result offset used.

Response example

{
  "renewals": [
    {
      "id": "re_123",
      "status": "scheduled",
      "subscription": {
        "subscription_id": "sub_123",
        "reference": "SUB-001",
        "status": "active",
        "customer_name": "Jane Doe",
        "product_title": "Coffee Subscription",
        "variant_title": "1 kg",
        "sku": "COFFEE-1KG"
      },
      "scheduled_for": "2026-04-15T10:00:00.000Z",
      "effective_scheduled_for": "2026-04-15T10:00:00.000Z",
      "last_attempt_status": "failed",
      "last_attempt_at": "2026-04-15T10:02:00.000Z",
      "approval": {
        "required": true,
        "status": "pending",
        "decided_at": null,
        "decided_by": null,
        "reason": null
      },
      "generated_order": null,
      "updated_at": "2026-04-15T10:02: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/renewals/:id

Returns the full detail payload for a single renewal cycle, including the full attempt history and operational metadata.

Path parameters

string

required

Renewal cycle ID.

Response

Returns a renewal object with all list fields plus:

object

required

Show additional detail fields

string

Creation timestamp.

string | null

When the cycle finished processing.

string | null

Last error message, if any.

object | null

Subscription plan changes pending approval for this cycle.

object[]

Full attempt history with attempt number, status, timestamps, error code, error message, payment reference, and order ID.

object

Operational metadata including last_trigger_type and last_correlation_id.

Response example

{
  "renewal": {
    "id": "re_123",
    "status": "failed",
    "subscription": {
      "subscription_id": "sub_123",
      "reference": "SUB-001",
      "status": "active",
      "customer_name": "Jane Doe",
      "product_title": "Coffee Subscription",
      "variant_title": "1 kg",
      "sku": "COFFEE-1KG"
    },
    "scheduled_for": "2026-04-15T10:00:00.000Z",
    "effective_scheduled_for": "2026-04-15T10:00:00.000Z",
    "last_attempt_status": "failed",
    "last_attempt_at": "2026-04-15T10:02:00.000Z",
    "approval": {
      "required": true,
      "status": "approved",
      "decided_at": "2026-04-15T09:55:00.000Z",
      "decided_by": "user_123",
      "reason": "approved for processing"
    },
    "generated_order": {
      "order_id": "order_123",
      "display_id": 1001,
      "status": "pending"
    },
    "updated_at": "2026-04-15T10:03:00.000Z",
    "created_at": "2026-04-10T10:00:00.000Z",
    "processed_at": "2026-04-15T10:03:00.000Z",
    "last_error": null,
    "pending_changes": {
      "variant_id": "variant_456",
      "variant_title": "2 kg",
      "frequency_interval": "month",
      "frequency_value": 2,
      "effective_at": null
    },
    "attempts": [
      {
        "id": "reatt_123",
        "attempt_no": 1,
        "status": "failed",
        "started_at": "2026-04-15T10:00:00.000Z",
        "finished_at": "2026-04-15T10:02:00.000Z",
        "error_code": "renewal_failed",
        "error_message": "payment failed",
        "payment_reference": null,
        "order_id": null
      }
    ],
    "metadata": {
      "last_trigger_type": "manual",
      "last_correlation_id": "renewal-admin-force-uuid"
    }
  }
}

Errors

Code	Error	Meaning
`404`	`not_found`	Renewal cycle does not exist

POST /admin/renewals/:id/force

Manually triggers execution for a renewal cycle, ignoring its scheduled date.

Path parameters

string

required

Renewal cycle ID.

Body parameters

string

Optional reason for the manual trigger.

Request example

{
  "reason": "manual retry after review"
}

Errors

Code	Error	Meaning
`404`	`not_found`	Renewal cycle does not exist
`409`	`conflict`	Cycle is already processing
`409`	`conflict`	Cycle already succeeded; duplicate execution is blocked
`409`	`conflict`	Cycle is not in a forceable state
`409`	`conflict`	Cycle requires approved changes before force-run
`409`	`conflict`	Linked subscription is not eligible for renewal
`400`	`invalid_data`	Current Plans & Offers policy blocks the pending change

POST /admin/renewals/:id/approve-changes

Approves pending subscription changes for a renewal cycle that requires approval before execution.

Path parameters

string

required

Renewal cycle ID.

Body parameters

string

Optional approval reason.

Request example

{
  "reason": "approved after review"
}

Errors

Code	Error	Meaning
`404`	`not_found`	Renewal cycle does not exist
`409`	`conflict`	Approval is not required for this cycle
`409`	`conflict`	Approval was already decided for this cycle

POST /admin/renewals/:id/reject-changes

Rejects pending subscription changes for a renewal cycle. reason is required for rejections.

Path parameters

string

required

Renewal cycle ID.

Body parameters

string

required

Reason for rejection. Required.

Request example

{
  "reason": "pending changes are not valid for this cycle"
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Missing or invalid `reason`
`404`	`not_found`	Renewal cycle does not exist
`409`	`conflict`	Approval is not required for this cycle
`409`	`conflict`	Approval was already decided for this cycle

Admin API

Store API

Status values

GET /admin/renewals

Query parameters

Response

Errors

GET /admin/renewals/:id

Path parameters

Response

Errors

POST /admin/renewals/:id/force

Path parameters

Body parameters

Errors

POST /admin/renewals/:id/approve-changes

Path parameters

Body parameters

Errors

POST /admin/renewals/:id/reject-changes

Path parameters

Body parameters

Errors

​Status values

​GET /admin/renewals

​Query parameters

​Response

​Errors

​GET /admin/renewals/:id

​Path parameters

​Response

​Errors

​POST /admin/renewals/:id/force

​Path parameters

​Body parameters

​Errors

​POST /admin/renewals/:id/approve-changes

​Path parameters

​Body parameters

​Errors

​POST /admin/renewals/:id/reject-changes

​Path parameters

​Body parameters

​Errors

Status values

GET /admin/renewals

Query parameters

Response

Errors

GET /admin/renewals/:id

Path parameters

Response

Errors

POST /admin/renewals/:id/force

Path parameters

Body parameters

Errors

POST /admin/renewals/:id/approve-changes

Path parameters

Body parameters

Errors

POST /admin/renewals/:id/reject-changes

Path parameters

Body parameters

Errors