Set up and Manage a Subscription Plan
You create and manage a subscription plan using the Catalog API. After creating a plan, you add subscriptions using the Subscriptions API.
A subscription plan has a name and one or more phases. For example, a subscription plan for a gym membership might offer two phases:
Phase 1: A 6-week free membership.
Phase 2: A monthly price of $60, after the initial phase.
You define each phase using a cadence, recurring price, and period:
Cadence. Identifies the billing interval, such as weekly or monthly. Cadence is required. For more information, see
cadence
in SubscriptionPhase.Recurring price. The amount that is charged every billing interval while the phase is in effect. You set this amount by adding the
recurring_price_money
field. This is a required field. To offer a free initial phase, you set this field to 0. For more information about pricing-related limitations, see Requirements and limitations.Period. The number of cadences that the phase lasts. The period is required in all phases except the last phase. If not provided, the phase never ends (the subscription plan has no end date).
For the example gym membership plan, you define the phases as follows:
Phase 1 (6 weeks at no cost). For this phase, the
cadence
is weekly,recurring_price_money
is 0, andperiod
is 6.Phase 2 (never ends, $60 monthly). For this phase,
cadence
is monthly,recurring_price_money
is $60, and you do not specify theperiod
(to indicate the never ending phase).
Note
Be aware that after creating a subscription plan, you cannot add, remove, or reorder phases. To make any of these changes, you must create a new subscription plan. You have the option to disable a subscription plan, in which case you are not able to create new subscriptions for that plan.
For information about subscription billing, see Subscription billing and invoices.
The following UpsertCatalogObject request creates the preceding gym membership two-phase subscription plan:
The order in which you define the phases determines the order in which they appear in the subscription. The following is an example response fragment:
The following determine whether a subscription plan offers a free-trial phase:
The plan defines more than one phase.
The first phase in the plan has the price set to 0.
For example, the following subscription plans do not offer a free-trial phase:
The plan offers a phase with the price set to 0 and the plan offers only one phase.
The plan offers multiple phases but the first phase price is greater than zero.
You can list all the subscription plans in your account or retrieve a specific subscription plan:
List subscription plans. Call ListCatalog to retrieve subscription plans. In the request, set the
types
query parameter toSUBSCRIPTION_PLAN
as shown:Retrieve a specific subscription plan. If you know the ID of the plan, call RetrieveCatalogObject to retrieve it. The following example request specifies the ID of a subscription plan:
The following is an example response that shows an object of the
SUBSCRIPTION_PLAN
type:
You might need to rename a subscription plan after it is created (for example, if you need to correct a typo or give the plan a more descriptive title).
To rename a subscription plan, call the UpsertCatalogObject or BatchUpsertCatalogObjects endpoint, specifying the updated CatalogSubscriptionPlan object containing the new plan name.
Suppose you created a subscription plan named "Magic Powers". The following example shows how to call UpsertCatalogObject
to rename it as "30-Day Supply of Magic Powers" to provide more information:
When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.
Call UpsertCatalogObject to disable or enable a subscription plan. The plan ID and version number are required to disable a subscription plan. The following example disables a plan at all locations:
You can disable or enable the existing plan's availability at locations by setting the present_at_all_locations
field (along with absent_at_location_ids
and present_at_location_ids
) to manage subscription plan availability at specific locations.
In the current implementation, you cannot delete a subscription plan.
You can optionally disable the existing plan by setting the present_at_all_locations
field to false
by calling UpsertCatalogObject
. For more information, see Disable a subscription plan. When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.
Subscription plans you create do not appear as items in the Seller Dashboard. You can use the Catalog API to access the subscription plans. For more information, see Retrieve a subscription plan.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.