Selling plans

Layers syncs each product’s Shopify selling plan groups into a single selling_plans attribute on the product. Use it to display subscription, pre-order, and try-before-you-buy offers alongside product data, and to filter or facet by the plans a product is enrolled in.

When to use it

Request selling_plans when you need to:

Show subscribe-and-save, pre-order, or try-before-you-buy badges on product tiles or PDPs.
Display billing intervals, discounts, and plan options next to a product’s price.
Restrict a search, browse, or block to products enrolled in a specific plan group or category.

The attribute is deferred — it is only included in API responses when you explicitly list it in the attributes array. See Available attributes for API requests.

Structure

selling_plans is an object with a top-level rollup and a groups array. Products with no selling plans return an empty block: {"max_discount_percentage": null, "categories": [], "groups": []}.

Field	Type	Description
`max_discount_percentage`	Number \| null	Highest percentage discount across all plans on the product. `null` when no plan uses a percentage adjustment.
`categories`	Array of Strings	Sorted, deduplicated list of humanized categories across every group (for example, `subscription`, `pre-order`, `try before you buy`).
`groups`	Array of Objects	One entry per selling plan group the product is enrolled in.

Group fields

Field	Type	Description
`id`	Integer	Numeric Shopify `SellingPlanGroup` id.
`name`	String	Merchant-facing group name.
`merchant_code`	String	Stable code merchants use to reference the group.
`app_id`	String \| null	Identifier of the Shopify app that owns the group (for example, `shopify_subscriptions`).
`summary`	String \| null	Short group summary.
`options`	Array of Strings	Option labels shown on the storefront (for example, `["Delivery every"]`).
`categories`	Array of Strings	Humanized categories present on the group’s plans.
`max_discount_percentage`	Number \| null	Highest percentage discount across the group’s plans.
`plans`	Array of Objects	Individual selling plans in the group.

Plan fields

Field	Type	Description
`id`	Integer	Numeric Shopify `SellingPlan` id.
`name`	String	Plan name shown to customers.
`description`	String \| null	Plan description.
`category`	String \| null	Humanized category (`subscription`, `pre-order`, `try before you buy`, or another humanized value).
`options`	Array of Strings	Option values shown on the storefront (for example, `["1 month"]`).
`billing`	Object \| null	Billing policy. See Billing and delivery policies.
`delivery`	Object \| null	Delivery policy. Same shape family as `billing`.
`pricing`	Object \| null	First pricing policy applied from the initial cycle: `{adjustment_type, adjustment_value}`. Later `afterCycle` adjustments are handled by Shopify at checkout and are not surfaced.
`inventory_reserve`	String \| null	Lowercased inventory reservation strategy from Shopify (for example, `on_sale`, `on_fulfillment`).

Billing and delivery policies

Each policy has a type of recurring or fixed. For recurring policies:

Field	Type	Description
`interval`	String	Lowercased interval (`day`, `week`, `month`, `year`).
`interval_count`	Integer	Number of intervals between cycles.
`min_cycles`	Integer \| null	Minimum cycles the customer must complete.
`max_cycles`	Integer \| null	Maximum cycles before the plan ends.
`cutoff`	Integer \| null	Cutoff, in intervals, for changing an upcoming cycle.

For fixed policies, Layers surfaces the fields Shopify returns for that policy shape, such as fulfillment_trigger, fulfillment_exact_time, cutoff, remaining_balance_charge_trigger, remaining_balance_charge_exact_time, remaining_balance_charge_time_after_checkout, and a checkout_charge object with {type, value}.

Requesting selling plans

Add selling_plans to the attributes array on any Search, Browse, Blocks, or Similar Products request. You can also request nested paths via field projection.

{
  "attributes": [
    "id",
    "title",
    "price_range",
    "selling_plans"
  ]
}

Return only the rollup and each group’s name and discount:

{
  "attributes": [
    "id",
    "title",
    "selling_plans.max_discount_percentage",
    "selling_plans.categories",
    "selling_plans.groups[].name",
    "selling_plans.groups[].max_discount_percentage"
  ]
}

Example response

{
  "id": 7003338965178,
  "title": "Premium Coffee Beans",
  "selling_plans": {
    "max_discount_percentage": 15.0,
    "categories": ["subscription"],
    "groups": [
      {
        "id": 78129334,
        "name": "Subscribe & Save",
        "merchant_code": "subscribe-and-save",
        "app_id": "shopify_subscriptions",
        "summary": "Save on every order",
        "options": ["Delivery every"],
        "categories": ["subscription"],
        "max_discount_percentage": 15.0,
        "plans": [
          {
            "id": 3941002,
            "name": "Deliver every month",
            "description": "Cancel any time",
            "category": "subscription",
            "options": ["1 month"],
            "billing": {
              "type": "recurring",
              "interval": "month",
              "interval_count": 1,
              "min_cycles": null,
              "max_cycles": null
            },
            "delivery": {
              "type": "recurring",
              "interval": "month",
              "interval_count": 1,
              "cutoff": null
            },
            "pricing": {
              "adjustment_type": "percentage",
              "adjustment_value": 15.0
            },
            "inventory_reserve": "on_sale"
          }
        ]
      }
    ]
  }
}

Filterable attributes

Every store is seeded with the following attributes so you can filter and facet by selling plans without any dashboard setup. Storefront faceting is disabled by default — enable it in the dashboard when you want to expose a plan filter to shoppers.

Attribute	Type	Description
`selling_plans.group`	String	Selling plan group `name`.
`selling_plans.category`	String	Humanized plan category (`subscription`, `pre-order`, `try before you buy`, or another humanized value).
`selling_plans.merchant_code`	String	Group `merchant_code`.
`variants.has_selling_plan`	Boolean	Variant is enrolled in at least one selling plan group. Set per variant.
`variants.requires_selling_plan`	Boolean	Variant can only be purchased through a selling plan. Set from the product-level `requiresSellingPlan` value on Shopify.

Filter example — return only products enrolled in a specific group:

{
  "filters": {
    "conditional": "and",
    "expressions": [
      {
        "property": "selling_plans.group",
        "operator": "eq",
        "values": ["Subscribe & Save"],
        "type": "string"
      }
    ]
  }
}

Sync behavior

Selling plan groups sync per product. When a product’s sellingPlanGroupsCount is greater than zero, or the product already has stored groups that need to be pruned, Layers pages through product.sellingPlanGroups and merges each page into the product’s selling_plans attribute.
Groups with more than one page of plans are followed to completion so the stored block is never truncated.
Existing stores pick up selling plan data on each product’s next sync — there is no one-time backfill.
variants.requires_selling_plan mirrors the product-level requiresSellingPlan value from Shopify. variants.has_selling_plan is written per variant from Shopify’s ProductVariant.sellingPlanGroupsCount, and is cleared when the product has no groups.

MCP access

The MCP product resource includes selling_plans for every product. Products with no plans return the empty block described above.

Overview

Metafields

When to use it

Structure

Group fields

Plan fields

Billing and delivery policies

Requesting selling plans

Example response

Filterable attributes

Sync behavior

MCP access

See also

​When to use it

​Structure

​Group fields

​Plan fields

​Billing and delivery policies

​Requesting selling plans

​Example response

​Filterable attributes

​Sync behavior

​MCP access

​See also

When to use it

Structure

Group fields

Plan fields

Billing and delivery policies

Requesting selling plans

Example response

Filterable attributes

Sync behavior

MCP access

See also