Subscription
Private Subscription API endpoints
- GET/subscriptions
- POST/subscriptions
- GET/subscriptions/{subscription_id}
- POST/subscriptions/{subscription_id}/cancel
- DELETE/subscriptions/{subscription_id}/undo_cancellation
- 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}/discounts
- DELETE/subscriptions/{subscription_id}/discounts/{discount_id}
An API endpoint to get list of subscriptions
Query parameters
pageoptionalintegerPage number
per_pageoptionalintegerItems per page
statusesoptionalstring[]Filter by subscription statuses
created_at[gte]optionalstringFilter to include only records with a created_at on or after the given date.
Format: date-time.
created_at[lte]optionalstringFilter to include only records with a created_at on or before the given date.
Format: date-time.
start_created_atoptionalstringDeprecatedDeprecated alias of created_at[gte]. When both arrive, created_at[gte] wins.
Format: date-time.
end_created_atoptionalstringDeprecatedDeprecated alias of created_at[lte]. When both arrive, created_at[lte] wins.
Format: date-time.
customer_idoptionalintegerFilter by customer ID
product_idoptionalintegerDeprecatedDeprecated, use plan_ids or bundle_ids instead. Filter by product ID. Accepts a parent product ID or a plan (child product) ID; a parent is expanded to itself plus all of its plans. Matches subscriptions whose primary product or any line item is in the resulting set.
plan_idsoptionalinteger[]Filter by exact plan IDs. Matches subscriptions whose primary product or any line item is one of the given plans. Cannot be combined with bundle_ids.
bundle_idsoptionalinteger[]Filter by bundle IDs. Matches subscriptions whose primary product or any line item belongs to one of the bundles' products. Cannot be combined with plan_ids.
activeoptionalintegerFilter by the subscription active flag (0 or 1).
Possible values: 0, 1.
expand[]optionalstring[]List of relations to expand in the response.
Returnsobject
Subscriptions list response
Create a subscription directly, without a checkout. No invoice is issued at creation time: an auto-collecting subscription is billed by the renewals engine once its starts_at date is due, while one with auto_collecting: false waits for manually issued invoices.
A subscription created with a future starts_at is returned with status: active and a future next_payment_date — there is no distinct "scheduled" status. Only gifts are distinguished, as gift_waiting_to_start. To tell whether a subscription has started yet, compare starts_at to the current time rather than reading status.
Query parameters
expand[]optionalstring[]List of relations to expand in the response.
Request body
Create a subscription
auto_collectingoptionalbooleanWhether renewals are collected automatically. When true the subscription is charged by the renewals engine when the next payment date is due; when false it is never charged automatically and waits for manually issued invoices.
The renewals engine skips non-auto-collecting subscriptions entirely, so starts_at is recorded but nothing is billed on that date. It takes effect only once auto_collecting is switched back to true.
Defaults to true.
customer_idRequiredintegerThe customer the subscription belongs to.
currency_codeRequiredstringSubscription currency. Must be enabled for the shop and, when a payment method is given, one of that payment method's currencies — the shop currencies attached to its gateway.
payment_method_idRequiredintegerThe customer's payment method, charged on every renewal. Must belong to the customer and support currency_code (see the payment method's currencies). The subscription's test mode is derived from the payment method's gateway: a payment method on a test gateway creates a test subscription.
shipping_address_idoptionalinteger | nullThe customer's shipping address id.
billing_address_idoptionalinteger | nullThe customer's billing address id. Defaults to shipping_address_id when omitted.
shipping_method_idoptionalinteger | nullShipping method id. Must be published in the shop.
shipping_carrier_idoptionalinteger | nullShipping carrier id. Required for (and only allowed with) dynamic shipping methods.
shipping_carrier_serviceoptionalstring | nullShipping carrier service code. Required for (and only allowed with) dynamic shipping methods.
giftoptionalobject | nullMarks the subscription as a gift. With a future starts_at the subscription is created in the gift_waiting_to_start status and activates on that date.
starts_atoptionalstring | nullThe day the first charge should land, as a Y-m-d date in the shop's timezone. It is stored at the shop's renewal time, exactly like next_payment_date on the update endpoint, and doubles as the gift start date. Must be today or later, where "today" is evaluated against the server's UTC clock — not the shop's timezone.
Omit the field (or send null) to bill the subscription as soon as the renewals engine next runs. That is not the same as passing today's date: today resolves to today at the shop's renewal time, which may still be hours away.
Only meaningful for auto-collecting subscriptions — see auto_collecting. A future date does not put the subscription in a distinct status; see the endpoint description.
Format: date.
charges_limitoptionalinteger | nullNumber of successful charges after which the subscription expires. Defaults to the subscription product's setting when omitted; pass null for unlimited.
discountsoptionalobject[]Subscription-level discounts. At most one entry per type is allowed: a coupon, a gift_card and a custom discount may be combined. The coupon becomes the subscription discount (and its gift products, if any, are added as coupon items); the gift card is redeemed to the customer and its balance is consumed by upcoming invoices; a discount becomes a single subscription-scoped discount, visible via expand=discounts, applied once per invoice across all items — including items added after creation. Items may still carry their own per-item discounts via items[].discounts. At billing time discounts stack in a fixed order — per-item discounts first, then the subscription discount, then the coupon (each computed on the already-discounted total), then the gift card against the remainder — and can never exceed the invoice total.
metadataoptionalobject[] | nullList of metadata and their values
itemsRequiredobject[]Subscription items. Item types are derived from the products: subscription products create subscription items (all of them must share one billing plan), one-time products create one_time add-on items. At least one subscription product is required.
ReturnsSubscription
Subscription object response
Error responses
400objectThe coupon in discounts was redeemable when the request was validated but reached its redemption limit, expired or was deactivated before the subscription was written (coupon_not_redeemable) - typically because a concurrent request took the last redemption. Redemptions are serialised per coupon, so exactly one of the competing requests succeeds. Nothing is created.
A detailed description of the subscription.
Path parameters
subscription_idRequiredintegerSubscription ID
Format: integer.
ReturnsSubscription
Subscription object response
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 the cancellation reason (available if cancellation reasons are enabled)
extra_feedbackoptionalstring | nullAdditional feedback from the customer
involuntary_churnoptionalboolean | nullInvoluntary churn occurs when a subscription ends due to issues like payment failures. Pass false to clear the past due status and prevent involuntary churn event. Pass true to keep the subscription in its current past due state, which may lead to involuntary churn.
typeoptionalstring | nullCancellation type. Defaults to 'immediate'. For committed subscriptions 'end_of_commitment' sets cancellation after commitment fulfillment. 'end_of_period' schedules cancellation at the end of the current billing period.
Possible values: immediate, end_of_period, end_of_commitment.
ReturnsSubscription
Subscription object response
Undo the cancellation of a subscription.
Path parameters
subscription_idRequiredintegerThe ID of the subscription
ReturnsSubscription
Subscription object response
Add an item to a subscription. A subscription item adds another concurrent subscription line (its product must share the subscription's billing plan); a one_time item adds a one-time add-on product. It is billed on the next renewal, not immediately.
Path parameters
subscription_idRequiredintegerSubscription ID
Query parameters
expand[]optionalstring[]List of relations to expand (e.g. product, bundle, discounts, metadata)
Request body
Create a subscription item
ReturnsSubscriptionItem
Subscription item object response
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, discounts, metadata)
ReturnsSubscriptionItem
Subscription item object response
Update a subscription item's quantity, duration and/or product. duration is only valid for one-time items. plan_id switches the item's product (product_id is the deprecated name of the same field): for one_time items any one-time product is accepted; for subscription items the product must share the subscription's billing plan and must not be a configurable bundle (use the item bundle endpoint for configurable bundles). Quantity 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, discounts, metadata)
Request body
Update a subscription item
quantityoptionalintegerItem quantity. Cannot be changed on a coupon-issued item.
durationoptionalinteger | nullAdd-on duration. Only valid for one-time items; prohibited for subscription items.
Possible values: 1.
plan_idoptionalintegerSwitch the item's product, and the current name of this field. For one_time items any valid one-time product is accepted. For subscription items the product must share the subscription's billing plan and must not be a configurable bundle. Send at most one of plan_id or the deprecated product_id; a payload carrying both is rejected.
product_idoptionalintegerDeprecatedDeprecated alias of plan_id, still accepted. Send plan_id instead.
ReturnsSubscriptionItem
Subscription item object response
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.
This endpoint is concurrency limited to a single in-flight request per API key. 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, discounts, metadata)
ReturnsSubscription
Subscription object response
Error responses
400objectThe last remaining subscription item cannot be removed. Cancel the subscription instead.
429objectToo many concurrent requests. Only one removal may be in flight per API key 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, discounts, metadata)
Request body
Update a subscription item's survey preferences
preferencesRequiredobject[] | nullupdate_ordersoptionalbooleanUpdate order preferences in the awaiting_delivery and future_shipment status. Allowed when the survey appearance type is after checkout.
ReturnsSubscriptionItem
Subscription item object response
Update the configurable-bundle configuration (preferences, items, quantity and optionally the product) of a single subscription item. The item's 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, 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. Cannot be changed on a coupon-issued item.
product_idoptionalintegerOptional target product for this item. Must share the subscription's billing plan and be a configurable bundle. When omitted the item keeps its current product.
ReturnsSubscriptionItem
Subscription item object response
Applies a subscription-level discount to an active subscription. Two kinds are supported and one of each may be applied at the same time: a coupon discount, which redeems a coupon and takes its duration from the coupon itself, and a custom discount, whose amount and duration you set directly. Applying a second discount of the same kind is rejected — remove the existing one first. The discount is applied to upcoming invoices, not to invoices that already exist.
Path parameters
subscription_idRequiredintegerSubscription ID
Request body
The discount to apply to the subscription
typeoptionalstringThe kind of discount to apply. Defaults to coupon when omitted, so a body carrying only coupon_id keeps working.
Possible values: coupon, discount.
Defaults to "coupon".
coupon_idoptionalintegerID of the coupon to redeem. Required for the coupon type and prohibited for discount. The coupon must belong to the shop and still be redeemable; how long the discount lasts is taken from the coupon's own duration.
percent_offoptionalnumberPercentage taken off the invoice total. Only valid for the discount type; exactly one of percent_off or amount_off must be provided.
amount_offoptionalintegerFixed amount taken off the invoice total, in the minor units of the shop's base currency — the same convention coupons use. It is converted to the subscription's currency at billing time, so a subscription billed in another currency is discounted by the converted equivalent. Only valid for the discount type; exactly one of percent_off or amount_off must be provided.
durationoptionalstringHow long the custom discount lasts. once applies it to the next invoice only and is then discarded; forever re-applies it on every renewal. Required for the discount type and prohibited for coupon.
Possible values: once, forever.
ReturnsSubscription
Subscription object response, with discounts expanded
Error responses
400objectThe subscription is not active (subscription_not_active), or it already carries a discount of the requested type (discount_already_applied) — remove the existing one first. The message names the type that is already applied.
422objectThe payload does not match the requested discount type. Every message
names both the offending field and the type in play, so the response
alone is enough to correct the request. amount_off is validated the
same way as percent_off, with the counterpart field named in its
place; a coupon that does not belong to the shop, or is no longer
redeemable, fails with The selected coupon does not exist. or The selected coupon is not valid., and an unsupported type with The selected type is invalid.
The coupon_id field is required for discounts of type "coupon".The coupon_id field is only allowed for discounts of type "coupon", the requested discount type is "discount".The duration field is required for discounts of type "discount".The duration field is only allowed for discounts of type "discount", the requested discount type is "coupon".The percent_off field is required for discounts of type "discount" when amount_off is not provided.The percent_off field cannot be combined with amount_off, a discount of type "discount" takes either an amount off or a percent off.The code field is not accepted here. Apply a coupon by its coupon_id.
Removes a subscription-level discount — either the coupon-backed one or the custom one. A coupon that was redeemed to create the discount is not credited back. Invoices that were already discounted are left untouched; upcoming invoices are billed without the discount.
Path parameters
subscription_idRequiredintegerSubscription ID
discount_idRequiredintegerID of the discount to remove, as returned by expand=discounts
ReturnsSubscription
Subscription object response, with discounts expanded