Admin API: plans and offers endpoints

Plan offer endpoints let you configure which subscription frequencies and discounts are available for each product or variant. You can list all offers, fetch a single offer’s full detail including the effective configuration resolved from variant-to-product fallback semantics, create or upsert offers, update existing records, and toggle enabled state without touching other fields. 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.

Domain values

Domain	Supported values
Status	`enabled`, `disabled`
Scope	`product`, `variant`
Frequency interval	`week`, `month`, `year`
Discount type	`percentage`, `fixed`
Stacking policy	`allowed`, `disallow_all`, `disallow_subscription_discounts`

GET /admin/subscription-offers

Returns the paginated plan offer list 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 name and product/variant titles.

order

string

Field to sort by. Database-backed: name, scope, is_enabled, created_at, updated_at. In-memory: status, product_title, variant_title.

direction

string

Sort direction. One of asc or desc.

is_enabled

boolean

Filter by enabled/disabled state.

scope

string

Filter by target scope. One of product or variant.

product_id

string

Filter by product ID.

variant_id

string

Filter by variant ID.

frequency

string

Filter by frequency interval. One of week, month, or year.

discount_min

number

Minimum discount value filter.

discount_max

number

Maximum discount value filter.

Response

plan_offers

object[]

required

Array of plan offer list items.

Show plan offer properties

string

Plan offer ID.

name

string

Offer name.

status

string

Human-readable status label.

is_enabled

boolean

Whether the offer is enabled.

target

object

Scoped target with scope, product_id, product_title, and optionally variant_id, variant_title, sku.

allowed_frequencies

object[]

Array of allowed cadences with interval, value, and label.

discounts

object[]

Array of per-frequency discount definitions.

rules_summary

string

Human-readable rules summary.

effective_config_summary

object

Resolved effective configuration including source scope, allowed frequencies, discounts, and rules.

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

{
  "plan_offers": [
    {
      "id": "po_123",
      "name": "Coffee Monthly Variant Offer",
      "status": "enabled",
      "is_enabled": true,
      "target": {
        "scope": "variant",
        "product_id": "prod_123",
        "product_title": "Coffee Subscription",
        "variant_id": "variant_123",
        "variant_title": "1 kg",
        "sku": "COFFEE-1KG"
      },
      "allowed_frequencies": [
        { "interval": "month", "value": 1, "label": "Every month" }
      ],
      "discounts": [
        { "interval": "month", "frequency_value": 1, "type": "percentage", "value": 10, "label": "10% off" }
      ],
      "rules_summary": "Min 1 cycles · Stacking allowed",
      "effective_config_summary": {
        "source_scope": "variant",
        "source_offer_id": "po_123",
        "allowed_frequencies": [{ "interval": "month", "value": 1, "label": "Every month" }],
        "discounts": [{ "interval": "month", "frequency_value": 1, "type": "percentage", "value": 10, "label": "10% off" }],
        "rules": {
          "minimum_cycles": 1,
          "trial_enabled": false,
          "trial_days": null,
          "stacking_policy": "allowed"
        }
      },
      "updated_at": "2026-03-29T12: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/subscription-offers/:id

Returns the full detail payload for a single plan offer.

Path parameters

string

required

Plan offer ID.

Response

Returns a plan_offer object with all list fields plus:

plan_offer

object

required

Show additional detail fields

rules

object

Full rules object with minimum_cycles, trial_enabled, trial_days, and stacking_policy.

metadata

object | null

Arbitrary metadata.

created_at

string

Creation timestamp.

Response example

{
  "plan_offer": {
    "id": "po_123",
    "name": "Coffee Monthly Variant Offer",
    "status": "enabled",
    "is_enabled": true,
    "target": {
      "scope": "variant",
      "product_id": "prod_123",
      "product_title": "Coffee Subscription",
      "variant_id": "variant_123",
      "variant_title": "1 kg",
      "sku": "COFFEE-1KG"
    },
    "allowed_frequencies": [{ "interval": "month", "value": 1, "label": "Every month" }],
    "discounts": [
      { "interval": "month", "frequency_value": 1, "type": "percentage", "value": 10, "label": "10% off" }
    ],
    "rules_summary": "Min 1 cycles · Stacking allowed",
    "effective_config_summary": {
      "source_scope": "variant",
      "source_offer_id": "po_123",
      "allowed_frequencies": [{ "interval": "month", "value": 1, "label": "Every month" }],
      "discounts": [{ "interval": "month", "frequency_value": 1, "type": "percentage", "value": 10, "label": "10% off" }],
      "rules": {
        "minimum_cycles": 1,
        "trial_enabled": false,
        "trial_days": null,
        "stacking_policy": "allowed"
      }
    },
    "created_at": "2026-03-29T10:00:00.000Z",
    "updated_at": "2026-03-29T12:00:00.000Z",
    "rules": {
      "minimum_cycles": 1,
      "trial_enabled": false,
      "trial_days": null,
      "stacking_policy": "allowed"
    },
    "metadata": { "source": "admin" }
  }
}

Errors

Code	Error	Meaning
`404`	`not_found`	Plan offer does not exist

POST /admin/subscription-offers

Creates a new plan offer, or updates an existing one for the same target (create-or-upsert semantics).

Body parameters

name

string

required

Offer name. Trimmed.

scope

string

required

Target scope. One of product or variant.

product_id

string

required

Target product ID.

variant_id

string

Target variant ID. Required for variant-scoped offers; must be omitted or null for product-scoped offers.

is_enabled

boolean

required

Whether the offer is active.

allowed_frequencies

object[]

required

Array of allowed cadences. Each entry requires interval (week, month, or year) and a positive integer value. Must contain at least one entry.

discounts

object[]

Per-frequency discount definitions. Each entry requires interval, frequency_value, type (percentage or fixed), and value. Optional.

rules

object

Rules object with minimum_cycles, trial_enabled, trial_days, and stacking_policy. Optional.

metadata

object

Arbitrary metadata. Optional.

Request example

{
  "name": "Coffee Monthly Variant Offer",
  "scope": "variant",
  "product_id": "prod_123",
  "variant_id": "variant_123",
  "is_enabled": true,
  "allowed_frequencies": [{ "interval": "month", "value": 1 }],
  "discounts": [{ "interval": "month", "frequency_value": 1, "type": "percentage", "value": 10 }],
  "rules": {
    "minimum_cycles": 1,
    "trial_enabled": false,
    "trial_days": null,
    "stacking_policy": "allowed"
  },
  "metadata": { "source": "admin" }
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid request shape
`400`	`invalid_data`	Product-scoped offer specifies `variant_id`, or variant-scoped offer omits it
`400`	`invalid_data`	Product does not exist, or variant does not belong to the product
`400`	`invalid_data`	Duplicate or invalid frequency definitions
`400`	`invalid_data`	Discount defined for a frequency not in `allowed_frequencies`, invalid discount range, or invalid trial configuration
`409`	`conflict`	Conflicting override configuration from an inconsistent persisted state

POST /admin/subscription-offers/:id

Updates an existing plan offer source record. At least one field must be provided.

Path parameters

string

required

Plan offer ID.

Body parameters

All fields are optional; omit any field you do not want to change.

name

string

Updated offer name.

is_enabled

boolean

Updated enabled state.

allowed_frequencies

object[]

Replacement list of allowed cadences.

discounts

object[]

Replacement list of per-frequency discounts.

rules

object

Updated rules object.

metadata

object

Updated metadata.

Request example

{
  "name": "Coffee Monthly Variant Offer Updated",
  "is_enabled": true,
  "allowed_frequencies": [
    { "interval": "month", "value": 2 },
    { "interval": "year", "value": 1 }
  ],
  "discounts": [
    { "interval": "month", "frequency_value": 2, "type": "percentage", "value": 12 }
  ],
  "rules": {
    "minimum_cycles": 2,
    "trial_enabled": true,
    "trial_days": 14,
    "stacking_policy": "disallow_subscription_discounts"
  },
  "metadata": { "revision": 2 }
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Empty body with no fields, invalid request shape, or invalid frequency/discount/rules configuration
`404`	`not_found`	Plan offer does not exist

POST /admin/subscription-offers/:id/toggle

Enables or disables a plan offer without modifying any other fields.

Path parameters

string

required

Plan offer ID.

Body parameters

is_enabled

boolean

required

Target enabled state.

Request example

{
  "is_enabled": false
}

Errors

Code	Error	Meaning
`400`	`invalid_data`	Invalid request shape
`404`	`not_found`	Plan offer does not exist

Admin API

Store API

​Domain values

​GET /admin/subscription-offers

​Query parameters

​Response

​Errors

​GET /admin/subscription-offers/:id

​Path parameters

​Response

​Errors

​POST /admin/subscription-offers

​Body parameters

​Errors

​POST /admin/subscription-offers/:id

​Path parameters

​Body parameters

​Errors

​POST /admin/subscription-offers/:id/toggle

​Path parameters

​Body parameters

​Errors

Domain values

GET /admin/subscription-offers

Query parameters

Response

Errors

GET /admin/subscription-offers/:id

Path parameters

Response

Errors

POST /admin/subscription-offers

Body parameters

Errors

POST /admin/subscription-offers/:id

Path parameters

Body parameters

Errors

POST /admin/subscription-offers/:id/toggle

Path parameters

Body parameters

Errors