Dunning

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

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

string

Sort direction. One of asc or desc.

string | string[]

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

string

Filter to cases for a specific subscription.

string

Filter by the originating renewal cycle ID.

string

Filter by the renewal order ID.

string

Filter by payment provider ID.

string

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

number

Minimum number of attempts filter.

number

Maximum number of attempts filter.

string

ISO datetime lower bound for next_retry_at.

string

ISO datetime upper bound for next_retry_at.

string | string[]

Filter by the status of the most recent attempt.

Response

object[]

required

Array of dunning case list items.

Show dunning case properties

string

Dunning case ID.

string

Current case status.

object

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

object

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

object | null

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

number

Number of retry attempts made so far.

number

Maximum allowed retry attempts.

string | null

Scheduled timestamp for the next automatic retry.

string | null

Timestamp of the most recent attempt.

string | null

Error code from the last payment attempt.

string

Last update timestamp.

number

required

Total matching records.

number

required

Page size used.

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:

object

required

Show additional detail fields

object

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

string | null

Human-readable error message from the last payment attempt.

string | null

Timestamp when the case was marked recovered.

string | null

Timestamp when the case was closed.

string | null

Reason recorded when the case was closed.

object[]

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

object

Operational metadata such as origin.

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

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

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

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

number[]

required

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

number

required

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

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

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