Admin API: dunning case endpoints

The dunning case endpoints expose the Admin dunning queue and let you manage individual payment recovery cases. You can list open or scheduled cases for DataTable views, fetch a full detail payload including attempt history and retry schedule, trigger an immediate retry, close a case manually as recovered or unrecovered, and override the retry schedule for a single case. 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
`open`	Case is newly opened
`retry_scheduled`	Last retry failed with a retryable error; next retry is scheduled
`retrying`	Retry is currently in flight
`awaiting_manual_resolution`	Automatic retries are exhausted; manual action required
`recovered`	Payment was collected; case is closed
`unrecovered`	Case is closed as permanently unrecoverable

Attempt status values: processing, succeeded, failed.

GET /admin/dunning

Returns the paginated dunning queue for Admin DataTable views.

Query parameters

limit

number

Number of results per page.

offset

number

Zero-based result offset for pagination.

string

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

order

string

Field to sort by. Database-backed: updated_at, status, next_retry_at, attempt_count, max_attempts, last_attempt_at. In-memory: last_attempt_status, subscription_reference, customer_name, product_title, order_display_id.

direction

string

Sort direction. One of asc or desc.

status

string | string[]

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

subscription_id

string

Filter to cases for a specific subscription.

renewal_cycle_id

string

Filter by the originating renewal cycle ID.

renewal_order_id

string

Filter by the renewal order ID.

payment_provider_id

string

Filter by payment provider ID.

last_payment_error_code

string

Filter by the last payment error code (e.g. card_declined).

attempt_count_min

number

Minimum number of attempts filter.

attempt_count_max

number

Maximum number of attempts filter.

next_retry_from

string

ISO datetime lower bound for next_retry_at.

next_retry_to

string

ISO datetime upper bound for next_retry_at.

last_attempt_status

string | string[]

Filter by the status of the most recent attempt.

Response

dunning_cases

object[]

required

Array of dunning case list items.

Show dunning case properties

string

Dunning case ID.

status

string

Current case status.

subscription

object

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

renewal

object

Linked renewal cycle summary with renewal_cycle_id, status, scheduled_for, and generated_order_id.

order

object | null

Order summary with order_id, display_id, and status, or null if not yet generated.

attempt_count

number

Number of retry attempts made so far.

max_attempts

number

Maximum allowed retry attempts.

next_retry_at

string | null

Scheduled timestamp for the next automatic retry.

last_attempt_at

string | null

Timestamp of the most recent attempt.

last_payment_error_code

string | null

Error code from the last payment attempt.

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

{
  "dunning_cases": [
    {
      "id": "dc_123",
      "status": "retry_scheduled",
      "subscription": {
        "subscription_id": "sub_123",
        "reference": "SUB-001",
        "status": "past_due",
        "customer_name": "Jane Doe",
        "product_title": "Coffee Subscription",
        "variant_title": "1 kg",
        "sku": "COFFEE-1KG",
        "payment_provider_id": "pp_stripe_stripe"
      },
      "renewal": {
        "renewal_cycle_id": "re_123",
        "status": "failed",
        "scheduled_for": "2026-04-15T10:00:00.000Z",
        "generated_order_id": "order_123"
      },
      "order": {
        "order_id": "order_123",
        "display_id": 1001,
        "status": "pending"
      },
      "attempt_count": 1,
      "max_attempts": 3,
      "next_retry_at": "2026-04-16T10:00:00.000Z",
      "last_attempt_at": "2026-04-15T10:02:00.000Z",
      "last_payment_error_code": "card_declined",
      "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/dunning/:id

Returns the full detail payload for a single dunning case, including the full attempt history and retry schedule.

Path parameters

string

required

Dunning case ID.

Response

Returns a dunning_case object with all list fields plus:

dunning_case

object

required

Show additional detail fields

retry_schedule

object

Active retry policy with strategy, intervals (array of minutes), timezone, and source.

last_payment_error_message

string | null

Human-readable error message from the last payment attempt.

recovered_at

string | null

Timestamp when the case was marked recovered.

closed_at

string | null

Timestamp when the case was closed.

recovery_reason

string | null

Reason recorded when the case was closed.

attempts

object[]

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

metadata

object

Operational metadata such as origin.

created_at

string

Creation timestamp.

Response example

{
  "dunning_case": {
    "id": "dc_123",
    "status": "retry_scheduled",
    "subscription": {
      "subscription_id": "sub_123",
      "reference": "SUB-001",
      "status": "past_due",
      "customer_name": "Jane Doe",
      "product_title": "Coffee Subscription",
      "variant_title": "1 kg",
      "sku": "COFFEE-1KG",
      "payment_provider_id": "pp_stripe_stripe"
    },
    "renewal": {
      "renewal_cycle_id": "re_123",
      "status": "failed",
      "scheduled_for": "2026-04-15T10:00:00.000Z",
      "generated_order_id": "order_123"
    },
    "order": {
      "order_id": "order_123",
      "display_id": 1001,
      "status": "pending"
    },
    "attempt_count": 1,
    "max_attempts": 3,
    "retry_schedule": {
      "strategy": "fixed_intervals",
      "intervals": [1440, 4320, 10080],
      "timezone": "UTC",
      "source": "default_policy"
    },
    "next_retry_at": "2026-04-16T10:00:00.000Z",
    "last_payment_error_code": "card_declined",
    "last_payment_error_message": "Declined",
    "last_attempt_at": "2026-04-15T10:02:00.000Z",
    "recovered_at": null,
    "closed_at": null,
    "recovery_reason": null,
    "attempts": [
      {
        "id": "da_123",
        "attempt_no": 1,
        "status": "failed",
        "started_at": "2026-04-15T10:00:00.000Z",
        "finished_at": "2026-04-15T10:02:00.000Z",
        "error_code": "card_declined",
        "error_message": "Declined",
        "payment_reference": null,
        "metadata": null
      }
    ],
    "metadata": {
      "origin": "renewal_payment_failure"
    },
    "created_at": "2026-04-15T10:00:00.000Z",
    "updated_at": "2026-04-15T10:02:00.000Z"
  }
}

Errors

Code	Error	Meaning
`404`	`not_found`	Dunning case does not exist

POST /admin/dunning/:id/retry-now

Immediately runs the dunning payment retry workflow for a case, ignoring its scheduled next_retry_at. Retryable failures keep the case in retry_scheduled; permanent failures close it as unrecovered.

Path parameters

string

required

Dunning case ID.

Body parameters

reason

string

Optional reason for the manual retry.

Request example

{
  "reason": "manual retry from admin"
}

Errors

Code	Error	Meaning
`404`	`not_found`	Dunning case does not exist
`409`	`conflict`	Retry is already processing, the case is terminal, or the transition is otherwise illegal

POST /admin/dunning/:id/mark-recovered

Closes a dunning case as recovered through a manual operator action. Use this when payment was collected outside the normal retry flow.

Path parameters

string

required

Dunning case ID.

Body parameters

reason

string

Optional reason for the manual recovery.

Request example

{
  "reason": "paid outside normal retry flow"
}

Errors

Code	Error	Meaning
`404`	`not_found`	Dunning case does not exist
`409`	`conflict`	Case is already recovered, already unrecovered, or a retry is in flight

POST /admin/dunning/:id/mark-unrecovered

Closes a dunning case as permanently unrecovered through a manual operator action. reason is required for this action.

Path parameters

string

required

Dunning case ID.

Body parameters

reason

string

required

Reason for closing the case as unrecovered. Required.

Request example

{
  "reason": "customer refused to update payment method"
}

Errors

Code	Error	Meaning
`404`	`not_found`	Dunning case does not exist
`409`	`conflict`	Case is already recovered, already unrecovered, or a retry is in flight

POST /admin/dunning/:id/retry-schedule

Overrides the retry policy for a single dunning case and updates future automatic retries. max_attempts must equal the number of entries in intervals.

Path parameters

string

required

Dunning case ID.

Body parameters

intervals

number[]

required

Array of retry intervals in minutes. Each value must be a positive integer.

max_attempts

number

required

Maximum number of retry attempts. Must be a positive integer equal to the length of intervals.

reason

string

Optional reason for the schedule override.

Request example

{
  "reason": "short manual retry schedule",
  "intervals": [60, 120],
  "max_attempts": 2
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid payload shape, non-positive interval values, or `max_attempts` does not match the number of intervals
`404`	`not_found`	Dunning case does not exist
`409`	`conflict`	Case is terminal, a retry is in flight, or the override would create an illegal transition

Admin API

Store API

​Status values

​GET /admin/dunning

​Query parameters

​Response

​Errors

​GET /admin/dunning/:id

​Path parameters

​Response

​Errors

​POST /admin/dunning/:id/retry-now

​Path parameters

​Body parameters

​Errors

​POST /admin/dunning/:id/mark-recovered

​Path parameters

​Body parameters

​Errors

​POST /admin/dunning/:id/mark-unrecovered

​Path parameters

​Body parameters

​Errors

​POST /admin/dunning/:id/retry-schedule

​Path parameters

​Body parameters

​Errors

Status values

GET /admin/dunning

Query parameters

Response

Errors

GET /admin/dunning/:id

Path parameters

Response

Errors

POST /admin/dunning/:id/retry-now

Path parameters

Body parameters

Errors

POST /admin/dunning/:id/mark-recovered

Path parameters

Body parameters

Errors

POST /admin/dunning/:id/mark-unrecovered

Path parameters

Body parameters

Errors

POST /admin/dunning/:id/retry-schedule

Path parameters

Body parameters

Errors