Overview
Manage recurring subscriptions programmatically with cancellation, pause, resume, payment-method, plan-change, and renewal-date actions.
Subscriptions represent recurring product purchases made through your store. The v2 subscriptions API exposes a legacy cancellation route plus lifecycle action endpoints for supported subscription management flows.
Note
New lifecycle action endpoints use the SellApp subscription record ID in
productSubscription. The legacy cancel route can still resolve compatible
order IDs.
Endpoints
- Cancel a subscription
- Cancel a subscription immediately with a refund
- View subscription capabilities
- Cancel at period end
- Cancel immediately
- Pause a subscription
- Resume a subscription
- Update payment method
- Preview a plan change
- Confirm a plan change
- Preview a renewal date change
- Confirm a renewal date change
Lifecycle actions support idempotency. Send an Idempotency-Key header, or include idempotency_key in the JSON body, when retrying a request safely.
Capability responses explain which actions are available for the current actor and provider. Some actions may be customer_only, seller_only, require a redirect, or be unsupported by the payment provider.
The subscription model
The subscription model contains the key billing and customer details associated with a recurring subscription.
Properties
- Name
idinteger- Description
(read-only) The unique identifier for the subscription record.
- Name
invoice_idinteger | null- Description
(read-only) The original invoice ID linked to this subscription, if available.
- Name
providerstring- Description
(read-only) The billing provider handling the subscription, such as
stripeorpaypal.- Name
subscription_idstring- Description
(read-only) The provider subscription identifier.
- Name
customer_idstring- Description
(read-only) The provider customer identifier.
- Name
customer_emailstring- Description
(read-only) The customer email associated with the subscription.
- Name
statusstring- Description
(read-only) The current subscription status, such as
ACTIVEorCANCELED.- Name
current_period_starttimestamp | null- Description
(read-only) When the current billing period started.
- Name
current_period_endtimestamp | null- Description
(read-only) When the current billing period ends or ended.
- Name
cancel_at_period_endboolean- Description
(read-only) Whether the subscription is scheduled to cancel at the end of the current billing period.
- Name
cancellation_in_progressboolean- Description
(read-only) Whether an immediate cancellation request has been accepted and is still waiting on provider webhook sync.
- Name
store_idinteger- Description
(read-only) The ID of the store this subscription belongs to.
- Name
product_variant_idinteger | null- Description
(read-only) The ID of the subscribed product variant.
- Name
created_attimestamp- Description
(read-only) Time at which the subscription record was created.
- Name
updated_attimestamp- Description
(read-only) Time at which the subscription record was last updated.