Is specifying the "period" mandatory when creating a subscription with the Catalog API?

Questions
1

When creating a subscription with the Catalog API, is specifying the period mandatory?

Hello. I am developing a membership platform service using Square. I am creating a subscription plan with the following code.

client.catalog.upsert_catalog_object(
        body: {
          idempotency_key: generate_idempotency_key,
          object: {
            id: item_id,
            type: 'SUBSCRIPTION_PLAN',
            subscription_plan_data: {
              name:,
              phases: [
                {
                  cadence: 'MONTHLY',
                  recurring_price_money: {
                    amount: price,
                    currency: 'JPY',
                  },
                },
              ],
            },
          },
        },
      )

When I retrieve this subscription plan, I receive an object like the following. I would like to point out that data[:subscription_plan_data][:subscription_plan_variations][0][:subscription_plan_variation_data][:phases][0][:periods] is set to 1.

{:type=>"SUBSCRIPTION_PLAN",
 :id=>"xxx",
 :updated_at=>"2024-09-16T04:39:24.755Z",
 :created_at=>"2024-09-16T04:39:24.789Z",
 :version=>1726461564755,
 :is_deleted=>false,
 :present_at_all_locations=>true,
 :subscription_plan_data=>
  {:name=>"xxx",
   :subscription_plan_variations=>
    [{:type=>"SUBSCRIPTION_PLAN_VARIATION",
      :id=>"xxx",
      :updated_at=>"2024-09-16T04:39:24.995Z",
      :created_at=>"2024-09-16T04:39:25.035Z",
      :version=>1726461564995,
      :is_deleted=>false,
      :present_at_all_locations=>true,
      :subscription_plan_variation_data=>
       {:name=>"xxx", :phases=>[{:uid=>"xxx", :cadence=>"MONTHLY", :periods=>1, :ordinal=>0, :pricing=>{:type=>"STATIC", :price=>{:amount=>300, :currency=>"JPY"}, :price_money=>{:amount=>300, :currency=>"JPY"}}}], :subscription_plan_id=>"xxx"}}]}}

According to the documentation at Subscription Plans and Variations, it states:

If no periods are provided, the phase never ends and the subscription plan has no end date.

I would like users to continue subscribing until the subscription plan is stopped, but in reality, only the first month is being charged. What should I specify for the period?

2

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:
https://developer.squareup.com/docs/app-marketplace/requirements/subscriptions-api

Additional Documentation

Common Square API Patterns
Update Catalog Objects
Catalog API

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

When creating a subscription plan, if you want the subscription to continue indefinitely until it’s manually stopped, you should not specify the periods field in the phases array. By omitting the periods field, the phase will continue indefinitely and the subscription plan will have no end date.

In your case, it seems like the periods field is automatically being set to 1, which is why the subscription is only being charged for the first month. To have the subscription continue until it’s manually stopped, you should omit the periods field when creating the subscription plan.

This answer was reviewed by @Bryan-Square.