Settings

The subscription settings endpoints manage the global configuration singleton used by the Reorder plugin at runtime. You can read the effective settings — which fall back to hardcoded defaults if no record has been persisted yet — and write a new or updated singleton through the dedicated workflow. All routes require an authenticated Medusa Admin user. The POST route uses optimistic locking via expected_version.

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

Field reference

Field	Type	Description
`settings_key`	`string`	Always `global` in MVP.
`default_trial_days`	`number`	Default trial length in days. Must be `>= 0`.
`dunning_retry_intervals`	`number[]`	Retry schedule in minutes. Must be strictly increasing positive integers.
`max_dunning_attempts`	`number`	Maximum retry attempts. Must equal the number of intervals.
`default_renewal_behavior`	`string`	`process_immediately` or `require_review_for_pending_changes`.
`default_cancellation_behavior`	`string`	`recommend_retention_first` or `allow_direct_cancellation`.
`version`	`number`	Monotonic version for optimistic locking.
`is_persisted`	`boolean`	`false` when the response uses fallback defaults; `true` when a stored record exists.

GET /admin/subscription-settings

Returns the effective settings payload. When no record has been saved yet the response uses hardcoded fallback defaults and is_persisted is false. This route never returns 404.

Response

object

required

Show settings fields

string

Always global.

number

Trial length in days.

number[]

Retry intervals in minutes.

number

Maximum retry attempts.

string

Global renewal policy.

string

Global cancellation policy.

number

Current version number.

string | null

Actor ID of the last update, or null when using defaults.

string | null

Timestamp of the last update, or null when using defaults.

object | null

Audit metadata including audit_log and last_update.

boolean

false when returning fallback defaults.

Fallback response example

{
  "subscription_settings": {
    "settings_key": "global",
    "default_trial_days": 0,
    "dunning_retry_intervals": [1440, 4320, 10080],
    "max_dunning_attempts": 3,
    "default_renewal_behavior": "process_immediately",
    "default_cancellation_behavior": "recommend_retention_first",
    "version": 0,
    "updated_by": null,
    "updated_at": null,
    "metadata": null,
    "is_persisted": false
  }
}

Persisted response example

{
  "subscription_settings": {
    "settings_key": "global",
    "default_trial_days": 21,
    "dunning_retry_intervals": [45, 180, 720],
    "max_dunning_attempts": 3,
    "default_renewal_behavior": "require_review_for_pending_changes",
    "default_cancellation_behavior": "allow_direct_cancellation",
    "version": 1,
    "updated_by": "user_01ABC",
    "updated_at": "2026-04-03T14:00:00.000Z",
    "metadata": {
      "audit_log": [],
      "last_update": null
    },
    "is_persisted": true
  }
}

POST /admin/subscription-settings

Persists a new or updated settings singleton through the dedicated workflow. The first successful POST creates the record. Omitted fields retain their current effective value.

Body parameters

number

Default trial length in days. Must be >= 0.

number[]

Retry intervals in minutes. Must be strictly increasing positive integers. Length must equal max_dunning_attempts.

number

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

string

Global renewal policy. One of process_immediately or require_review_for_pending_changes.

string

Global cancellation policy. One of recommend_retention_first or allow_direct_cancellation.

number

Current version for optimistic locking. Use 0 on the first write.

string

Optional reason for the update, recorded in the audit log.

Request example

{
  "default_trial_days": 21,
  "dunning_retry_intervals": [45, 180, 720],
  "max_dunning_attempts": 3,
  "default_renewal_behavior": "require_review_for_pending_changes",
  "default_cancellation_behavior": "allow_direct_cancellation",
  "expected_version": 0,
  "reason": "admin_save"
}

Response

Returns the updated subscription_settings object. The metadata.audit_log and metadata.last_update fields record the change summary.

Response example

{
  "subscription_settings": {
    "settings_key": "global",
    "default_trial_days": 21,
    "dunning_retry_intervals": [45, 180, 720],
    "max_dunning_attempts": 3,
    "default_renewal_behavior": "require_review_for_pending_changes",
    "default_cancellation_behavior": "allow_direct_cancellation",
    "version": 1,
    "updated_by": "user_01ABC",
    "updated_at": "2026-04-03T14:00:00.000Z",
    "metadata": {
      "audit_log": [
        {
          "action": "update_settings",
          "who": "user_01ABC",
          "when": "2026-04-03T14:00:00.000Z",
          "reason": "admin_save",
          "previous_version": 0,
          "next_version": 1,
          "change_summary": [
            {
              "field": "default_trial_days",
              "from": 0,
              "to": 21
            }
          ]
        }
      ],
      "last_update": {
        "action": "update_settings",
        "who": "user_01ABC",
        "when": "2026-04-03T14:00:00.000Z",
        "reason": "admin_save",
        "previous_version": 0,
        "next_version": 1,
        "change_summary": [
          {
            "field": "default_trial_days",
            "from": 0,
            "to": 21
          }
        ]
      }
    },
    "is_persisted": true
  }
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid scalar ranges, invalid enum values, invalid retry interval list, or mismatched `max_dunning_attempts`
`409`	`conflict`	Stale `expected_version` — optimistic locking mismatch
`500`	`unexpected_state`	Unexpected workflow or persistence failure

Admin API

Store API

Field reference

GET /admin/subscription-settings

Response

POST /admin/subscription-settings

Body parameters

Response

Errors

​Field reference

​GET /admin/subscription-settings

​Response

​POST /admin/subscription-settings

​Body parameters

​Response

​Errors

Field reference

GET /admin/subscription-settings

Response

POST /admin/subscription-settings

Body parameters

Response

Errors