Subscription plans on order items

What's new

Order items in create_order take a new optional subscription object that controls which plans of a subscription SKU the checkout page offers, and lets you override a plan's price for that order. It replaces selected_plan_key and selected_plan_locked, which are now deprecated.

Impact

subscription has two optional fields:

• default_plan_key: the plan to pre-select on the checkout page. When plans is set, it must be one of them. When omitted, the first listed plan is pre-selected.
• plans: from 1 to 50 plans to offer, each identified by plan_key. Catalog plans that aren't listed aren't offered, and the player can't switch to them. When omitted, every catalog plan is offered. Requires the item's sku.

Each plan takes the same settings as the subscription upgrade request (amount, currency, recurring_amount, discounted_cycles, cycle_period, grace_period, account_lock_duration, renewal_type, and the is_*_allowed / is_downgrade_supported flags). Any setting you leave out comes from the catalog plan. For now only the pricing settings (amount, currency, recurring_amount, discounted_cycles) are supported.

A plan with custom pricing must be the only plan listed. It's charged exactly the given amounts in the given currency, so local pricing and price templates don't apply to it. It can't be combined with discount_percent, coupon_code, a custom order price, or a second item, and coupons are disabled on the resulting order.

Changes

Resource	Change
create_order	Added optional subscription to order items
create_order	Deprecated selected_plan_key on order items in favor of subscription.default_plan_key
create_order	Deprecated selected_plan_locked on order items in favor of subscription.plans

Upgrade

• No action is required right away. selected_plan_key and selected_plan_locked still work.
• To migrate, move selected_plan_key to subscription.default_plan_key. To lock the checkout to one plan, which selected_plan_locked: true did before, list only that plan in subscription.plans.
• subscription can't be combined with selected_plan_key or selected_plan_locked on the same item, so drop the old fields when you switch.

Need help?
Contact our integration team at [email protected]