Subscription
Storefront Subscription API endpoints
- GET/subscriptions
- GET/subscriptions/{subscription_id}
- PATCH/subscriptions/{subscription_id}
- PATCH/subscriptions/{subscription_id}/preferences
- PATCH/subscriptions/{subscription_id}/bundle
- POST/subscriptions/{subscription_id}/cancel
- DELETE/subscriptions/{subscription_id}/undo_cancellation
- POST/subscriptions/{subscription_id}/undo_set_to_cancel
- POST/subscriptions/{subscription_id}/cancellation_request
- POST/subscriptions/{subscription_id}/undo_cancellation_request
- POST/subscriptions/{subscription_id}/skip
- POST/subscriptions/{subscription_id}/pause
- POST/subscriptions/{subscription_id}/resume
- POST/subscriptions/{subscription_id}/prolong_skipping
- POST/subscriptions/{subscription_id}/reactivate
- PATCH/subscriptions/{subscription_id}/address
- PATCH/subscriptions/{subscription_id}/payment_method
- GET/subscriptions/{subscription_id}/shipping_methods
- GET/subscriptions/{subscription_id}/local_pickups
- GET/subscriptions/{subscription_id}/billing_dates
- GET/subscriptions/{subscription_id}/skipping_dates
- GET/subscriptions/{subscription_id}/resume_dates
- POST/subscriptions/{subscription_id}/change_plans
- GET/subscriptions/{subscription_id}/plans
- POST/subscriptions/{subscription_id}/items
- GET/subscriptions/{subscription_id}/items/{item_id}
- PATCH/subscriptions/{subscription_id}/items/{item_id}
- DELETE/subscriptions/{subscription_id}/items/{item_id}
- PATCH/subscriptions/{subscription_id}/items/{item_id}/preferences
- PATCH/subscriptions/{subscription_id}/items/{item_id}/bundle
- POST/subscriptions/{subscription_id}/items/{item_id}/change_plan
- POST/subscriptions/{subscription_id}/items/{item_id}/change_variant
An API endpoint to get list of subscriptions.
Query parameters
pageoptionalintegerPage
per_pageoptionalintegerEntities per page
statusesoptionalstring[]Filter by subscription status
pausedoptionalintegerFilter by the subscription paused flag (0 or 1). Skipping until a date (skipping_until) does not set this flag.
Possible values: 0, 1.
expandoptionalstring[]Expandable relations
Returnsobject
Subscriptions list response
Error responses
401objectMissing or invalid customer token.
422objectpage is not a positive integer, per_page is outside 1-100, statuses is not an array or holds an unknown or duplicate status, paused is not 0 or 1, or expand is not an array.
An api call to show the subscription.
Path parameters
subscription_idRequiredintegerSubscription ID
Query parameters
expandoptionalstring[]Expandable relations
ReturnsSubscription
Subscription object response
Error responses
401objectMissing or invalid customer token.
404objectNo subscription with this ID exists, or it belongs to another customer.
422objectexpand is not an array.
An api call to update the subscription. product_id is deprecated: it runs as POST /subscriptions/{subscription_id}/change_plans with one pick for the subscription's only subscription item, in the same request as the other fields.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Update subscription
product_idoptionalintegerDeprecatedDeprecated: use POST /subscriptions/{subscription_id}/change_plans. Runs as one pick for the subscription's only subscription item. The plan must be a published, non-archived subscription plan of the shop, and either share the current plan's parent product or sit in the current product's change-product collection. Configurable bundles are not allowed through the collection, and a sibling on another configurable bundle needs its contents picked through POST /subscriptions/{subscription_id}/items/{item_id}/change_plan. Rejected for subscriptions with multiple subscription items — change the plans per item via POST /subscriptions/{subscription_id}/change_plans.
gift_recipient_emailoptionalstring | nullEmail of the gift recipient. Send null to clear it.
Format: email.
gift_messageoptionalstring | nullGift message. Send null to clear it.
quantityoptionalintegerDeprecatedSubscription-level quantity. Rejected for subscriptions with multiple subscription items — update the quantity per item via PATCH /subscriptions/{subscription_id}/items/{item_id}.
metadataoptionalobject[] | nullList of metadata and their values
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active). With product_id, the guards of POST /subscriptions/{subscription_id}/change_plans apply as well: the subscription is paused (subscription_paused) or skipping (already_skipping), or the shop does not allow plan changes (plan_change_disabled). The write refuses the pick when it re-checks it under the lock: another subscription item is on another billing cycle (plan_change_items_left_behind, "Item 2 must also be moved to a plan with the same billing cycle.").
401objectMissing or invalid customer token.
404objectNo subscription with this ID exists, or it belongs to another customer.
422objectproduct_id is not a published subscription variant of the shop, is not a valid product change for this subscription (not a sibling variant and not in the change-product collection, a configurable bundle, or on the other membership kind: "The selected plan is not available for this item."), is a configurable bundle other than the current one ("The selected plan needs new bundle contents. Pick it with its contents using POST subscriptions/{subscription}/items/{item}/change_plan."), or the subscription has several subscription items ("This subscription has multiple subscription items. Change the plans per item using POST subscriptions/{subscription}/change_plans."); quantity is below 1, above 1 when the shop turns off the subscription quantity selector, or the subscription has several subscription items ("This subscription has multiple subscription items. Update quantity per item using PATCH subscriptions/{subscription}/items/{item}."); metadata holds an unknown, duplicate or wrongly typed metadata entry, or adds, changes or removes a non-editable one; gift_recipient_email is not a valid email; or gift_message is longer than 255 characters.
Update subscription survey preferences by Subscription ID
Deprecated. Do not use it in new integrations.
Update the subscription survey preferences.
Deprecated. This endpoint operates on the subscription as a whole and is not available for subscriptions that have multiple subscription items — for those it responds with 410 Gone (error code endpoint_deprecated). Use PATCH /subscriptions/{subscription_id}/items/{item_id}/preferences instead.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Update subscription survey preferences
preferencesRequiredobject[]update_ordersoptionalbooleanUpdate order preferences in the awaiting_delivery and future_shipment status. Allowed when the survey appearance type is after checkout, or when the sync_orders_preferences_on_subscription_update shop setting is enabled.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), or a chosen answer is out of stock (out_of_stock).
404objectNo subscription with this ID exists, or it belongs to another customer.
410objectEndpoint deprecated for this subscription. Returned when the subscription has multiple subscription items — use the per-item preferences endpoint.
Deprecated. Do not use it in new integrations.
Deprecated: use POST /subscriptions/{subscription_id}/change_plans with a pick that carries bundle. This route runs as that pick for the subscription's only subscription item (plan_id = product_id when sent, else the current plan), with quantity written to the item in the same request. Only applicable when the subscription has exactly one subscription item; for subscriptions with multiple subscription items update each item's bundle via PATCH /subscriptions/{subscription_id}/items/{item_id}/bundle.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Update subscription bundle data for a single-item subscription. Only applicable when the subscription has exactly one subscription item.
bundleRequiredSubscriptionBundleBodyBundle payload for the subscription's single subscription item. Rejected for subscriptions that have multiple subscription items — update each item's bundle via PATCH /subscriptions/{subscription_id}/items/{item_id}/bundle.
quantityoptionalinteger | nullSubscription item quantity. Rejected for subscriptions with multiple subscription items — set the quantity per item instead.
product_idoptionalinteger | nullTarget subscription product (a product change). Must share the current product's bundle or belong to its change-product collection.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active). The route runs as POST /subscriptions/{subscription_id}/change_plans and takes its guards as well: the subscription is paused (subscription_paused) or skipping (already_skipping), or the shop does not allow plan changes (plan_change_disabled). The write refuses the pick when it re-checks it under the lock: another subscription item is on another billing cycle (plan_change_items_left_behind, "Item 2 must also be moved to a plan with the same billing cycle.").
404objectNo subscription with this ID exists, or it belongs to another customer.
422objectbundle is missing or lacks the items key; the product is not a configurable bundle ("The selected product must have a configurable bundle."); bundle.preferences or bundle.items do not fit the bundle; the subscription has several subscription items ("This subscription has multiple subscription items. Update each item's bundle using PATCH subscriptions/{subscription}/items/{item}/bundle."); product_id is missing while the current product is not a configurable bundle, or is not a published subscription variant that shares the bundle or sits in the change-product collection, or is on the other membership kind ("The selected plan is not available for this item."); or quantity is below 1, above 1 when the shop turns off the subscription quantity selector, or the subscription has several subscription items.
Cancels a subscription for a given reason.
Path parameters
subscription_idRequiredintegerThe ID of the subscription to cancel
Request body
Cancellation Reasons Body
reason_idoptionalinteger | nullThe ID of one of the shop's cancellation reasons (GET /cancellation/reasons); any other ID answers 422. Stored only when the shop's plan includes cancellation reasons, and silently dropped otherwise.
extra_feedbackoptionalstring | nullAdditional feedback from the customer
typeoptionalstring | nullOptional cancellation type. Only 'end_of_period' is accepted; any other value responds with 400 (error code cancellation_type_not_allowed). When omitted, committed subscriptions default to cancel at end of commitment; non-committed subscriptions cancel immediately.
Possible values: end_of_period.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), is already scheduled for cancellation or has a pending cancellation request (cancellation_scheduled), the shop has cancellation requests enabled so the customer must request a cancellation instead (cancellation_request_required), or type is a value other than end_of_period (cancellation_type_not_allowed).
404objectNo subscription with this ID exists, or it belongs to another customer.
422objectreason_id is not a cancellation reason of the shop; extra_feedback is not a string or is longer than 255 characters; or expand is not an array.
429objectAnother rate-limited request from the same customer (or from the same IP when no customer token is sent) is still in progress.
Clears a cancellation scheduled for the end of the current billing period. A cancellation scheduled for the end of the commitment term is cleared through POST undo_set_to_cancel.
Path parameters
subscription_idRequiredintegerThe ID of the subscription
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), or no period-end cancellation is scheduled (no_cancellation_scheduled).
404objectNo subscription with this ID exists, or it belongs to another customer.
Clears a cancellation scheduled for the end of the commitment term. A cancellation scheduled for the end of the current billing period is cleared through DELETE undo_cancellation.
Path parameters
subscription_idRequiredintegerSubscription ID
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), or no end-of-commitment cancellation is scheduled (no_cancellation_scheduled).
404objectThe subscription does not exist or does not belong to the customer.
Flags the subscription as having a pending cancellation request for the merchant to review. Available only when the shop has cancellation requests enabled.
Path parameters
subscription_idRequiredintegerSubscription ID
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), the shop has cancellation requests disabled (cancellation_request_disabled), or a cancellation request is already pending (cancellation_already_requested).
404objectThe subscription does not exist or does not belong to the customer.
Clears a pending cancellation request.
Path parameters
subscription_idRequiredintegerSubscription ID
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), or it has no pending cancellation request (no_cancellation_request).
404objectThe subscription does not exist or does not belong to the customer.
Skips the subscription until the given date. skip_until must be one of the dates returned by GET /subscriptions/{subscription_id}/skipping_dates.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Skip subscription
skip_untilRequiredstringDate (Y-m-d, after today) to skip until. Must be one of the dates from GET /subscriptions/{subscription_id}/skipping_dates.
Format: date.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), paused (subscription_paused), scheduled for cancellation or has a pending cancellation request (cancellation_scheduled), already skipping (already_skipping), waiting to start (subscription_waiting), the shop has skipping disabled (skipping_disabled), the subscription has fewer paid invoices than the shop's skipping minimum term (skipping_min_term_not_reached), or it is within its commitment term, meaning fewer paid invoices than the commitment's total payments or the shop auto-extends commitments (subscription_committed), or skip_until is not one of the allowed skipping dates (skip_date_not_allowed).
404objectThe subscription does not exist or does not belong to the customer.
422objectValidation failed: skip_until is missing, not a Y-m-d date, or not after today.
Pauses the subscription until it is resumed. Pausing needs everything skipping needs (the shop allows skipping, the minimum term is reached, the subscription is active, not committed, not paused, skipping or waiting, and no cancellation is scheduled or requested), plus the shop's and the product's pause setting. Read actions.pause to know whether it is allowed.
Path parameters
subscription_idRequiredintegerSubscription ID
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), paused (subscription_paused), scheduled for cancellation or has a pending cancellation request (cancellation_scheduled), already skipping (already_skipping), waiting to start (subscription_waiting), the shop has skipping disabled (skipping_disabled), the subscription has fewer paid invoices than the shop's skipping minimum term (skipping_min_term_not_reached), or it is within its commitment term, meaning fewer paid invoices than the commitment's total payments or the shop auto-extends commitments (subscription_committed), the shop has customer pausing disabled (pause_disabled), or the product does not allow pausing (pause_disabled_for_product).
404objectThe subscription does not exist or does not belong to the customer.
Resumes a paused or skipping subscription. When the shop allows choosing a resume date, next_payment_date selects the next renewal from the dates returned by GET /subscriptions/{subscription_id}/resume_dates.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Resume subscription
next_payment_dateoptionalstring | nullOptional next renewal date (Y-m-d, today or later). Accepted only when the shop allows choosing a resume date; must be one of the dates from GET /subscriptions/{subscription_id}/resume_dates.
Format: date.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), neither paused nor skipping (not_paused_or_skipping), next_payment_date was sent but the shop does not allow choosing a resume date (resume_date_not_allowed), or it is not one of the allowed resume dates (next_payment_date_not_allowed).
404objectThe subscription does not exist or does not belong to the customer.
422objectValidation failed: next_payment_date is not a Y-m-d date or is in the past.
Extends the current skipping period of a subscription that is already skipping. Each skip can be prolonged once, and only when the shop allows it.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Prolong subscription skipping
skip_untilRequiredstringNew date (Y-m-d, after today) to skip until. Must be a valid billing date after the current skipping period.
Format: date.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), not currently skipping (not_skipping), its skip was already prolonged (skipping_already_prolonged), or the shop does not allow prolonging (prolong_skipping_disabled).
404objectThe subscription does not exist or does not belong to the customer.
422objectValidation failed: skip_until is missing, not a Y-m-d date, not after today, or not a valid billing date.
Reactivates a cancelled or expired subscription. When the shop reactivates with an immediate charge, renewal_date is ignored and the subscription renews right away; otherwise it is required and picks the next renewal from the next three billing dates.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Reactivate subscription
renewal_dateoptionalstring | nullNext renewal date (Y-m-d, today or later), one of the next three billing dates. Required when the shop does not reactivate with an immediate charge; ignored when it does (a malformed value still answers 422).
Format: date.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is neither cancelled nor expired (subscription_not_reactivatable), its product is unpublished or archived (product_not_available), the shop has reactivation disabled (reactivation_disabled), renewal_date is missing for a shop that does not reactivate with an immediate charge (renewal_date_required), or it is not one of the next three billing dates (renewal_date_not_allowed).
404objectThe subscription does not exist or does not belong to the customer.
422objectValidation failed: renewal_date is not a Y-m-d date or is in the past.
Changes the subscription's shipping address, shipping method and, for dynamic-rate methods, the carrier and service. Optionally applies the new address to open orders when the shop allows it and the method is not dynamic; otherwise update_orders_address is ignored.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Update subscription shipping address and method
shipping_address_idoptionalinteger | nullID of one of the customer's addresses. Required when the product collects a shipping address and not accepted otherwise.
shipping_method_idoptionalinteger | nullID of a published shipping method of the shop that is available for the address. Required for shippable products and not accepted for digital or gift-card products.
shipping_carrier_idoptionalinteger | nullCarrier ID. Required with shipping_carrier_service for dynamic-rate shipping methods and not accepted otherwise.
shipping_carrier_serviceoptionalstring | nullCarrier service code. Required with shipping_carrier_id for dynamic-rate shipping methods and not accepted otherwise.
update_orders_addressoptionalintegerAlso apply the new address to the subscription's open orders. Honoured only when the shop allows updating order addresses and the shipping method is not dynamic; ignored otherwise.
Possible values: 0, 1.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), or its product neither collects a shipping address nor can carry a shipping method, so there is nothing to update (shipping_not_applicable); a shipping address was sent for a product that does not collect one (shipping_address_not_allowed), is missing for one that does (shipping_address_required), or does not belong to the customer (shipping_address_not_found); a shipping method was sent for a digital or gift-card product (shipping_method_not_allowed), is missing for a shippable one (shipping_method_required), or is not a published method of the shop (shipping_method_not_found); carrier fields were sent for a non-dynamic method (shipping_carrier_not_allowed) or are missing for a dynamic one (shipping_carrier_required).
404objectThe subscription does not exist or does not belong to the customer.
422objectValidation failed: a field has the wrong type, the address type does not fit the shipping method, the shipping method is not available for the address, or the carrier or service is not offered by the method.
An api call to change the payment method the subscription is billed with. Only active subscriptions can be updated.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
Update subscription payment method
payment_method_idRequiredintegerID of one of the customer payment methods. It has to belong to a gateway matching the live mode of the subscription.
currency_codeRequiredstringCurrency ISO code.
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), the payment method does not exist or does not belong to the customer (payment_method_not_found), or its gateway's live mode does not match the subscription (payment_method_livemode_mismatch).
404objectNo subscription with this ID exists, or it belongs to another customer.
422objectpayment_method_id is missing, is not an integer, or is a card that has expired ("The selected payment method card has expired."); or currency_code is missing or unknown.
Available shipping methods for the subscription when shipped to the given address. Dynamic carrier-rated methods are not returned, so service, carrier_id and carrier are always empty here and customs_fee and future_customs_fee are always 0. shipping_fee is priced from the subscription's current items, while future_shipping_fee is priced with no chargeable items, because the items of an existing subscription are billed by its renewal invoice.
Path parameters
subscription_idRequiredintegerSubscription ID
Query parameters
address_idRequiredintegerID of one of the customer addresses the subscription would ship to. Returns an empty array when a pickup info ID is passed.
expand[]optionalstring[]Expandable relations (e.g. carrier)
ReturnsCartShippingMethod[]
Array of shipping methods objects
Error responses
401objectMissing or invalid customer token.
404objectThe subscription does not exist or does not belong to the customer.
422objectaddress_id is missing or is not one of the customer's addresses.
Available local pickups for the subscription. As on shipping_methods, service, carrier_id and carrier are always empty and customs_fee and future_customs_fee are always 0.
Path parameters
subscription_idRequiredintegerSubscription ID
Query parameters
expand[]optionalstring[]Expandable relations (e.g. carrier)
ReturnsCartShippingMethod[]
Array of local pickup objects
Error responses
401objectMissing or invalid customer token.
404objectThe subscription does not exist or does not belong to the customer.
Returns the subscription's upcoming billing dates starting from its next payment date, either as an explicit list or as a range.
Path parameters
subscription_idRequiredintegerSubscription ID
ReturnsSubscriptionBillingDates
Billing dates response
Error responses
404objectThe subscription does not exist or does not belong to the customer.
Returns the dates a skip may run until, as accepted by POST /subscriptions/{subscription_id}/skip.
Path parameters
subscription_idRequiredintegerSubscription ID
ReturnsSubscriptionBillingDates
Billing dates response
Error responses
404objectThe subscription does not exist or does not belong to the customer.
Returns the next renewal dates a customer may pick when resuming, as accepted by POST /subscriptions/{subscription_id}/resume.
Path parameters
subscription_idRequiredintegerSubscription ID
ReturnsSubscriptionBillingDates
Billing dates response
Error responses
404objectThe subscription does not exist or does not belong to the customer.
Moves the named subscription items to other plans in one write: a plan change, a product change or a billing cycle change. The picks are laid over the current items and every subscription item must end on one billing cycle (plan hash); an item that is not named is never written, so a cycle change names every subscription item. A pick may be a sibling plan of the item's product or a subscription plan of a product in its change collection, published, not archived and on the subscription's membership kind; GET subscriptions/{subscription_id}/plans lists them. The item's current plan only needs the membership kind, so its contents stay changeable after the shop stops selling it. One-time items are never picks. A pick's bundle is accepted only when the target plan is a configurable bundle, required when that bundle is not the item's current bundle, and replaces the contents when sent; on the same bundle the contents are kept without it, while any other bundle, or none, drops them. A pick equal to the current plan is a no-op without bundle and a contents change with it. Survey answers reset unless the target plan's active survey is the one they answer; send the new answers with PATCH subscriptions/{subscription_id}/items/{item_id}/preferences. The subscription's product_id follows the plan of its first (lowest-id) subscription item. Nothing else is written: the renewal date, the commitment, discounts and upcoming orders stay as they are and the change takes effect at the next renewal. Read actions.change_billing_cycle and the items' actions.change_plan to know what is allowed. One subscription item moves on its own with POST subscriptions/{subscription_id}/items/{item_id}/change_plan.
Path parameters
subscription_idRequiredintegerSubscription ID
Query parameters
expand[]optionalstring[]List of relations to expand on the subscription (e.g. items.product, product)
Request body
itemsRequiredobject[]The picks, one per subscription item to move.
ReturnsSubscription
The subscription with its items on their new plans
Error responses
400objectThe subscription is not active (subscription_not_active), paused (subscription_paused) or skipping (already_skipping), or the shop does not allow plan changes (plan_change_disabled). The write re-checks the picks under the lock and refuses one that another write made invalid while the change waited for the subscription: a named item was removed (plan_change_item_not_found, "Item 2 is not a subscription item of this subscription."), or an unnamed item is on another billing cycle (plan_change_items_left_behind, "Item 2 must also be moved to a plan with the same billing cycle.").
404objectThe subscription does not exist or does not belong to the customer. A request without a valid customer token runs as a guest and gets this response too.
422objectitems is missing, empty or not a list; an id is not an item of this subscription ("The item does not belong to this subscription."), is a one-time item ("The item is not a subscription item.") or is named twice ("The item is picked more than once."); a plan_id is not a sibling or change-collection plan available to the item ("The selected plan is not available for this item."); the picks name plans on different cycles ("All picked plans must share one billing cycle." on items.N.plan_id) or leave an unnamed item on another cycle ("Item 2 must also be moved to a plan with the same billing cycle." on items); bundle is sent for a plan that is not a configurable bundle ("The bundle field is not accepted for this plan."), missing while the target's bundle is not the item's current bundle ("The bundle field is required for this plan."), lacks preferences or items ("The bundle field must contain entries for: preferences, items."), or its items or preferences do not fit the target's bundle; or expand is not an array.
429objectAnother rate-limited request from the same customer (or from the same IP when no customer token is sent) is still in progress.
Lists the plans each subscription item can move to with POST subscriptions/{subscription_id}/change_plans: its product's other plans, then the plans of its change collection in the collection's order, at most 500 per item. current_billing_cycle is the subscription's billing cycle with each item's plans on it; send only the items you change. available_billing_cycles are the other billing cycles every subscription item can reach, shortest period first; a cycle change names every subscription item with a plan from the same row. Only published, unarchived plans on the subscription's membership kind are listed, never an item's own plan; one-time items have no entry. Plans are priced in the subscription's currency. The read has no state guard: it answers for paused or cancelled subscriptions too.
Path parameters
subscription_idRequiredintegerSubscription ID
Query parameters
expand[]optionalstring[]List of plan relations to expand (e.g. product, bundle_plan, surveys, shippings)
ReturnsSubscriptionPlanOptions
The current cycle and the available cycles
Error responses
404objectThe subscription does not exist or does not belong to the customer.
422objectexpand is not an array.
Add a new item to a subscription. For subscription items the product must share the subscription's billing cycle. The item is not charged immediately — it is billed on the next renewal.
Path parameters
subscription_idRequiredintegerSubscription ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)
Request body
Create a subscription item
typeRequiredstringThe item type. subscription adds another concurrent subscription line; one_time adds a one-time add-on product.
Possible values: one_time, subscription.
product_idRequiredintegerThe item's product id. For one_time items any valid one-time product is accepted. For subscription items the product must share the subscription's billing cycle.
durationoptionalinteger | nullOptional add-on duration. Only valid when type is one_time; prohibited when type is subscription.
Possible values: 1.
quantityoptionalintegerItem quantity. Defaults to 1. For subscription items the value is ignored, leaving the quantity at 1, unless the shop has the subscription quantity selector enabled; one-time items are not capped.
bundleoptionalSubscriptionBundleBodyBundle configuration. Required when type is subscription and the item's product is a configurable bundle; must be omitted otherwise.
metadataoptionalobject[] | nullList of metadata and their values
ReturnsSubscriptionItem
Subscription item object response
Error responses
400objectThe subscription is not active (subscription_not_active), the shop does not allow one-time items (addons_disabled), a one-time item was requested for a membership subscription without a shipping address and shipping method (membership_subscription), or a subscription item was requested while the shop's plan does not include multiple subscription products (feature_not_available).
404objectNo subscription with this ID exists, or it belongs to another customer.
422objecttype is missing or unknown; product_id is missing or is not valid for the item's kind ("The selected product is not a valid one-time product for this shop.", "The selected product must share this subscription's billing cycle."); duration is not 1 or is sent for a subscription item; quantity is not an integer or is below 1 (a subscription item ignores it unless the shop enables the subscription quantity selector); bundle is missing while the product is a configurable bundle, sent while it is not, or its preferences or items do not fit the bundle; metadata holds an unknown, duplicate or wrongly typed metadata entry, or adds, changes or removes a non-editable one; or expand is not an array.
Show a single subscription item.
Path parameters
subscription_idRequiredintegerSubscription ID
item_idRequiredintegerSubscription item ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)
ReturnsSubscriptionItem
Subscription item object response
Error responses
404objectNo subscription or no subscription item with this ID exists, or it belongs to another customer or subscription.
422objectexpand is not an array.
Update a subscription item's quantity, duration, product and/or metadata. duration only applies to one_time items. product_id is deprecated: on a subscription item it runs as POST /subscriptions/{subscription_id}/items/{item_id}/change_plan, on a one_time item as POST /subscriptions/{subscription_id}/items/{item_id}/change_variant. For one_time items any one-time product is accepted; for subscription items the product must be another plan of the same parent product or be listed in the current product's change-product collection, must share the subscription's billing cycle unless the item is the subscription's only subscription item, and must not be a configurable bundle. Quantity, duration and product cannot be changed on a coupon-issued item.
Path parameters
subscription_idRequiredintegerSubscription ID
item_idRequiredintegerSubscription item ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)
Request body
Update a subscription item
quantityoptionalinteger | nullItem quantity. When omitted the current quantity is kept. On a subscription item a value above 1 is ignored, keeping the current quantity, when the shop's subscription quantity selector is disabled; 1 is always accepted. Cannot be changed on a coupon-issued item.
durationoptionalinteger | nullAdd-on duration. Only valid for one_time items; prohibited for subscription items. Set to 1 for a single shipment, or null to recur. Cannot be changed on a coupon-issued item.
Possible values: 1.
product_idoptionalintegerDeprecatedDeprecated: use POST /subscriptions/{subscription_id}/items/{item_id}/change_plan for a subscription item and POST /subscriptions/{subscription_id}/items/{item_id}/change_variant for a one_time item. For one_time items any valid one-time product is accepted. For subscription items the product must be another plan of the same parent product or be listed in the current product's change-product collection, must share the subscription's billing cycle unless the item is the subscription's only subscription item, and must not be a configurable bundle. Cannot be changed on a coupon-issued item.
metadataoptionalobject[] | nullList of metadata and their values
ReturnsSubscriptionItem
Subscription item object response
Error responses
400objectThe subscription is not active (subscription_not_active), the item is a one-time item while the shop does not allow one-time items (addons_disabled) or the subscription is a membership without a shipping address and shipping method (membership_subscription), or a quantity was sent for a coupon-issued item (coupon_item_quantity_locked). With product_id, the guards of the write it runs as apply as well: for a subscription item those of POST /subscriptions/{subscription_id}/change_plans, the subscription is paused (subscription_paused) or skipping (already_skipping), or the shop does not allow plan changes (plan_change_disabled); for a one-time item those of POST /subscriptions/{subscription_id}/items/{item_id}/change_variant, a coupon added the item (coupon_item_product_locked). The write refuses the pick when it re-checks it under the lock: another subscription item is on another billing cycle (plan_change_items_left_behind, "Item 2 must also be moved to a plan with the same billing cycle."), or the variant is not a one-time variant of the shop (variant_change_variant_not_allowed).
404objectNo subscription or no subscription item with this ID exists, or it belongs to another customer or subscription.
422objectquantity is not an integer or is below 1 (on a subscription item a quantity above 1 is dropped when the shop turns off the subscription quantity selector, and an item that a coupon added answers 400 coupon_item_quantity_locked); duration is sent for a subscription item or changed on a coupon-issued item; product_id is not a valid product for the item's kind ("The selected plan is not available for this item.", "The selected plan is on another billing cycle. Move every subscription item at once with POST subscriptions/{subscription}/change_plans.", "The selected product has a configurable bundle. Pick it with its contents using POST subscriptions/{subscription}/items/{item}/change_plan.", "The selected product is not a valid one-time product for this shop."), or is changed on a coupon-issued item; metadata holds an unknown, duplicate or wrongly typed metadata entry, or adds, changes or removes a non-editable one; or expand is not an array.
Remove a subscription item. The last remaining subscription item cannot be removed — the request responds with 400 (error code last_subscription_item); cancel the subscription instead. The subscription's product_id follows the plan of its first (lowest-id) remaining subscription item.
This endpoint is concurrency limited to a single in-flight request per customer. Overlapping requests respond with 429 (error code too_many_requests) instead of queueing.
Path parameters
subscription_idRequiredintegerSubscription ID
item_idRequiredintegerSubscription item ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, items, discounts, metadata)
ReturnsSubscription
Subscription object response
Error responses
400objectThe subscription is not active (subscription_not_active), or the last remaining subscription item cannot be removed — cancel the subscription instead (last_subscription_item).
404objectNo subscription or no subscription item with this ID exists, or it belongs to another customer or subscription.
429objectToo many concurrent requests. Only one removal may be in flight per customer at a time; retry once the previous request has completed.
Update a subscription item's preferences
Update the survey preferences (answers) for a single subscription item.
Path parameters
subscription_idRequiredintegerSubscription ID
item_idRequiredintegerSubscription item ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)
Request body
Update a subscription item's survey preferences
preferencesRequiredobject[] | nullupdate_ordersoptionalbooleanUpdate order preferences in the awaiting_delivery and future_shipment status. Honoured only when the sync_orders_preferences_on_subscription_update shop setting is enabled (otherwise 400 order_sync_disabled), and not allowed when the subscription uses dynamic shipping.
ReturnsSubscriptionItem
Subscription item object response
Error responses
400objectThe subscription is not active (subscription_not_active), the item is a one-time item (item_not_editable), update_orders is true while the shop's order preference sync is disabled (order_sync_disabled), or a chosen answer is out of stock (out_of_stock).
404objectNo subscription or no subscription item with this ID exists, or it belongs to another customer or subscription.
422objectpreferences is missing (send null to clear it), is not an array, or does not match the active survey of the item's product ("The preferences are invalid"); a question lacks question_id or answers; update_orders is not a boolean, or the subscription uses dynamic shipping; or expand is not an array.
Deprecated. Do not use it in new integrations.
Deprecated: use POST /subscriptions/{subscription_id}/items/{item_id}/change_plan with plan_id and bundle, or POST /subscriptions/{subscription_id}/change_plans with a pick that carries bundle. This route runs as that pick for the item (plan_id = product_id when sent, else the current plan), with quantity written to the item in the same request. The target product must be a configurable bundle. Works for subscriptions with any number of subscription items.
Path parameters
subscription_idRequiredintegerSubscription ID
item_idRequiredintegerSubscription item ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, bundle, bundle.items, discounts, metadata)
Request body
Update a single subscription item's configurable bundle. The item's product must be a configurable bundle.
bundleRequiredSubscriptionBundleBodyBundle payload (preferences + items) for this subscription item.
quantityoptionalintegerItem quantity. When omitted the current quantity is kept. A value above 1 answers 422 when the shop turns off the quantity selector, and any value answers 422 for an item added by a coupon.
product_idoptionalinteger | nullOptional target plan for this item: a configurable bundle that is a sibling of the item's product or sits in its change-product collection, on the subscription's billing cycle unless the item is its only subscription item. When omitted the item keeps its current product.
ReturnsSubscriptionItem
Subscription item object response
Error responses
400objectThe subscription is not active (subscription_not_active), the item is a one-time item (item_not_editable), the target product (product_id when sent, otherwise the item's product) is unknown or not a configurable bundle (bundle_not_configurable), or the bundle items and preferences do not satisfy the bundle plan (bundle_items_not_valid). The route runs as POST /subscriptions/{subscription_id}/change_plans and takes its guards as well: the subscription is paused (subscription_paused) or skipping (already_skipping), or the shop does not allow plan changes (plan_change_disabled). The write refuses the pick when it re-checks it under the lock: another subscription item is on another billing cycle (plan_change_items_left_behind, "Item 2 must also be moved to a plan with the same billing cycle.").
404objectNo subscription or no subscription item with this ID exists, or it belongs to another customer or subscription.
422objectbundle is missing or lacks the items key; bundle.preferences do not fit the bundle; product_id is neither the item's current plan nor a published subscription plan that is a sibling or sits in the change-product collection ("The selected plan is not available for this item."), or is on another billing cycle while the subscription has other subscription items ("The selected plan is on another billing cycle. Move every subscription item at once with POST subscriptions/{subscription}/change_plans."); quantity is below 1, above 1 when the shop turns off the subscription quantity selector, or is sent for an item that a coupon added; or expand is not an array.
Change the plan of a subscription item
Moves one subscription item to another plan: a pick of POST subscriptions/{subscription_id}/change_plans on its own route, with that route's targets (GET subscriptions/{subscription_id}/plans lists them), bundle rules and effects. The plan must share the subscription's billing cycle unless the item is its only subscription item, which may change the cycle alone (one-time items do not count); with other subscription items, move them all at once with change_plans. Read the item's actions.change_plan.
Path parameters
subscription_idRequiredintegerSubscription ID
item_idRequiredintegerSubscription item ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, discounts, metadata)
Request body
plan_idRequiredintegerThe plan the item moves to.
bundleoptionalobject | nullThe contents for a configurable bundle plan: items (product_id, quantity) and preferences (attribute_id or metafield_id, values). Both keys are required, as on a change_plans pick. null is the same as leaving bundle out.
ReturnsSubscriptionItem
The subscription item on its new plan
Error responses
400objectThe subscription is not active (subscription_not_active), paused (subscription_paused) or skipping (already_skipping), the shop does not allow plan changes (plan_change_disabled), or the item is a one-time item (item_not_subscription). The write re-checks the pick under the lock and refuses one that another write made invalid while the change waited for the subscription: the item was removed (plan_change_item_not_found), or another subscription item is on another billing cycle (plan_change_items_left_behind).
404objectNo subscription or no subscription item with this ID exists, or it belongs to another customer or subscription. A request without a valid customer token runs as a guest and gets this response too.
422objectplan_id is missing, not an integer, or not a plan the item may move to ("The selected plan is not available for this item."), or is on another billing cycle while the subscription has other subscription items ("The selected plan is on another billing cycle. Move every subscription item at once with POST subscriptions/{subscription}/change_plans."); bundle is sent for a plan without a configurable bundle ("The bundle field is not accepted for this plan."), missing while the plan's bundle is not the item's current bundle ("The bundle field is required for this plan."), lacks preferences or items, or holds preferences or items the bundle does not allow; or expand is not an array.
429objectAnother rate-limited request from the same customer (or from the same IP when no customer token is sent) is still in progress.
Change the variant of a one-time item
Moves a one-time item of the subscription to another one-time variant of the shop. The change takes effect at the next renewal; quantity and duration stay as they are (change them with PATCH subscriptions/{subscription_id}/items/{item_id}). Sending the item's current variant is a no-op. Subscription items change their plan with POST subscriptions/{subscription_id}/items/{item_id}/change_plan or POST subscriptions/{subscription_id}/change_plans.
Path parameters
subscription_idRequiredintegerSubscription ID
item_idRequiredintegerSubscription item ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, discounts, metadata)
Request body
variant_idRequiredintegerThe one-time variant the item moves to.
ReturnsSubscriptionItem
Subscription item object response
Error responses
400objectThe subscription is not active (subscription_not_active), the shop does not allow one-time items (addons_disabled), the subscription is a membership without a shipping address and shipping method (membership_subscription), the item is a subscription item (item_not_one_time), or a coupon added the item (coupon_item_product_locked).
404objectNo subscription or no subscription item with this ID exists, or it belongs to another customer or subscription.
422objectvariant_id is missing, not an integer, or not a one-time variant of the shop that is published, not archived, not a gift card, a leaf and not a configurable bundle; or expand is not an array.
429objectAnother rate-limited request from the same customer (or from the same IP when no customer token is sent) is still in progress.