Executive summary
- What: Line items in Orders webhook payloads now carry a selling_plan_id value, on Admin API version 2026-10 and later.
- Why: Integrations can separate subscription lines from one-time purchases the moment the event arrives, with no follow-up Admin API call per order.
- Who: Teams running subscription programs, ERP or OMS order synchronization, and any middleware that enriches order events before passing them downstream.
What changed
Line items inside Orders webhook payloads now expose a selling_plan_id field. When a buyer purchases through a subscription or another selling plan, the field holds the identifier of the plan that was applied. When the line is an ordinary one-time purchase, the field is null. The change lands on API version 2026-10 and later. Earlier versions are untouched, nothing breaks, and no migration is required to keep existing apps running.
Before this, a webhook consumer that needed plan context had to treat the payload as incomplete. The common pattern was to receive the order event, then issue a separate Admin API query for the same order to read selling plan data on its line items. That is one extra round trip per order, on every order, whether or not any line was actually a subscription.
Why it matters
The saving looks trivial per event and compounds quickly at enterprise volume. A merchant processing 8,000 orders a day was issuing 8,000 supplementary queries to answer a yes or no question about plan membership. Those calls consume Admin API rate limit that the same integration needs for inventory writes, fulfillment updates, and customer record changes. Removing them frees headroom exactly when order volume peaks, which is when rate limit pressure actually causes damage.
There is a correctness benefit as well. A follow-up query reads the order as it exists at query time, not as it existed when the event fired. For orders edited within seconds of creation, the two can disagree. Reading plan membership from the payload itself removes that race condition entirely.
If you maintain ERP integrations on Shopify, this is worth folding into your next API version bump rather than scheduling as standalone work.
Role-specific impact
- Marketers: Recurring and one-time revenue can be split further upstream, so subscription reporting in downstream tools stops depending on an enrichment step that can fail quietly.
- Developers: One fewer call in the order ingestion path and one fewer failure mode. The field is additive, so adoption is a change to your selection and parsing logic, not a migration.
- Store admins: Fewer integration errors tied to throttling during peak periods, and clearer subscription flags on the records that reach finance and fulfillment systems.
Use-case example
Real-world scenario
A supplements brand on Shopify Plus runs roughly 35 percent of its order volume on subscriptions and syncs every order into NetSuite through middleware. Recurring and one-time revenue post to different accounts, so the pipeline fired one Admin API query per order purely to determine whether a line belonged to a selling plan. During a promotion week the store peaked near 14,000 orders a day, those supplementary queries pushed the integration into throttling, and order posting fell about 40 minutes behind. After moving the webhook subscriptions to API version 2026-10 and reading selling_plan_id from the payload, the pipeline shed roughly 14,000 calls a day at peak and posting latency held under two minutes.
Implementation checklist
- List the Orders webhook subscriptions your app holds and note the API version each one is registered against.
- Move the relevant subscriptions to API version 2026-10 in a development store and capture sample payloads for both subscription and one-time orders.
- Update payload parsing to read selling_plan_id per line item, treating null as a confirmed one-time purchase rather than as missing data.
- Remove the supplementary Admin API lookup once the payload path is verified, keeping it behind a feature flag for one release if your rollout policy requires a fallback.
- Re-check downstream field mappings in your ERP, OMS, or warehouse so the plan identifier lands where finance expects it.
- Record Admin API call volume before and after the change to confirm the reduction.
FAQ
Q: Do we need to change anything to keep our current integration working?
A: No. The field is purely additive and earlier API versions behave exactly as before. You act only when you want the benefit.
Q: Does selling_plan_id give us the full subscription contract details?
A: It identifies the selling plan applied to that line. Contract level data such as billing cadence, delivery schedule, and contract status still comes from the subscription contract objects in the Admin API.
Resources
Orders webhook payload reference
Need guidance? Talk to Makro.