Subscription

Filter to include only records with a created_at on or after the given date.

Filter to include only records with a created_at on or before the given date.

Deprecated alias of created_at[gte]. When both arrive, created_at[gte] wins.

Deprecated alias of created_at[lte]. When both arrive, created_at[lte] wins.

Deprecated, 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.

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.

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.

Filter by the subscription active flag (0 or 1).

Possible values: 0, 1.

Filter by the subscription paused flag (0 or 1). Skipping until a date (skipping_until) does not set this flag.

Possible values: 0, 1.

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

A query parameter failed validation: page below 1, per_page outside 1 to 100, a customer_id, product_id, plan_ids[] or bundle_ids[] value that does not belong to the shop, plan_ids sent together with bundle_ids, an unknown statuses[] value, a non-boolean active or paused, a date not in 2022-02-24T04:00:00 format, or a non-array expand[].

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

Whether 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.

Subscription 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.

The customer's payment method, charged on every renewal. Must belong to the customer and support currency_code (see the payment method's currencies); an expired card is rejected. The subscription's test mode is derived from the payment method's gateway: a payment method on a test gateway creates a test subscription.

The customer's shipping address id. Required when any product on the subscription is physical; prohibited when every product is digital and none of them collects a shipping address. The products counted are those in items[] plus the gift products of the coupon in discounts, if any. A pickup point id is accepted instead of a street address only when a physical product is present, and then shipping_method_id must be a local pickup method.

The customer's billing address id. Defaults to shipping_address_id when omitted.

Shipping method id. Must be published in the shop and available for shipping_address_id and the subscription's products: a shipping option or local delivery method serving the address's country, region and zip, or a local pickup method serving the pickup point. A FlavorCloud method is accepted only for an address outside the shop's country. Rejected when sent without shipping_address_id. Required when any product on the subscription is physical; prohibited when every product is digital, even one that collects a shipping address. The gift products of the coupon in discounts count like items[] products.

Shipping carrier id. Required for (and only allowed with) dynamic shipping methods.

Shipping carrier service code. Required for (and only allowed with) dynamic shipping methods.

Marks 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.

The 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.

Format: date.

Number of successful charges after which the subscription expires. Defaults to the subscription product's setting when omitted; pass null for unlimited.

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.

Subscription items. The item type follows the key that names its product: plan_id items are subscription lines (all of them must share one billing cycle), variant_id items are one_time add-ons. At least one plan_id item is required. More than one plan_id item needs the multiple subscription products feature of the shop's plan, and a membership plan (a digital plan) takes no variant_id items.

The 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. The same holds for the gift card in discounts when a concurrent request redeemed it first (gift_card_already_redeemed, "The gift voucher was already redeemed."). Nothing is created.

Validation failed. customer_id is not a customer of the shop; currency_code is not a currency the shop sells in; payment_method_id does not belong to the customer ("The selected payment method does not belong to the customer."), is an expired card ("The selected payment method card has expired.") or cannot be charged in currency_code ("The payment method id field cannot be charged in EUR; it can be charged in USD."). items names no plan ("The items must contain at least one subscription plan."), plans on different billing cycles ("All subscription plans must share the same billing cycle."), a one-time item on a membership plan ("One-time items are not allowed on membership subscriptions.") or more than one plan while the shop's plan lacks the multiple subscription products feature ("Multiple subscription products are not available on your current plan."); an item sends neither or both of plan_id and variant_id, a product that is not available, a duration on a plan, a bundle that is missing for a configurable bundle, sent for another product or does not fit it, or preferences that do not answer the plan's survey. A shipping address or method is missing while a product is physical ("The shipping method id is required when the subscription contains a physical product.") or sent while no product needs it ("The shipping address id is prohibited for digital products."), the address is not the customer's, a pickup point comes without a local pickup method, the method does not serve the address, or the carrier fields are missing for a dynamic-rate method or sent for another one. gift is sent without recipient_email; starts_at is before today. discounts repeats a type ("Only one coupon discount is allowed per subscription."), names a coupon that is not redeemable or a gift card that is not valid ("The gift card is not valid.") or has expired ("The gift card has already expired."), or holds a discount entry without duration or without exactly one of percent_off and amount_off; items[].discounts holds more than one entry or a type other than discount.

Subscription ID

Format: integer.

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

The expand[] parameter is not an array.

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

Deprecated: use POST /subscriptions/{subscription_id}/change_plans with one pick for the subscription's only subscription item. Moves that item to the given subscription plan of this shop in the same transaction as the other keys. Rejected with 422 for subscriptions with multiple subscription items, for a plan on the other membership kind and for a configurable bundle other than the current one, whose contents must be picked through POST /subscriptions/{subscription_id}/items/{item_id}/change_plan.

Subscription-level quantity. Rejected for subscriptions with multiple subscription items; update the quantity per item via PATCH /subscriptions/{subscription_id}/items/{item_id}.

Next payment date in Y-m-d format. Must be after yesterday.

Format: date.

Email of the gift recipient. Send null to clear it.

Format: email.

Gift message. Send null to clear it.

The subscription is not active (bad_request). The write re-checks the product_id pick under the lock and refuses it when a subscription item added by a concurrent write since validation would stay on another billing cycle (plan_change_items_left_behind, Item 2 must also be moved to a plan with the same billing cycle.).

Validation failed, for example product_id is not a subscription plan of this shop on the subscription's membership kind (The selected plan is not available for this item.) or 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.), product_id or quantity is sent for a subscription with multiple subscription items (This subscription has multiple subscription items. Change the plans per item using POST subscriptions/{subscription}/change_plans.), next_payment_date is not a Y-m-d date after yesterday, a tags.delete ID is not a tag of this shop, or a metadata entry is invalid.

Cancellation 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.

type is not immediate, end_of_period or end_of_commitment; the subscription is already set to cancel at the end of the period (The subscription is already set to cancel at end of period.) or at the end of its commitment (The subscription is already set to cancel at the end of commitment.); type is end_of_commitment but the subscription has no commitment term; reason_id does not belong to the shop, or the shop has cancellation reasons turned off (A cancellation reason cannot be submitted because cancellation reasons are disabled for this shop.); extra_feedback is longer than 255 characters; or involuntary_churn is not a boolean.