Walkthrough: Create a Subscription Plan and Manage Subscriptions

In this cURL-based walkthrough, you set up a subscription program for a gym membership, create customer subscriptions, and verify customer billing. You also test both scenarios: sending a subscription invoice to a customer's email address and charging a customer's card on file. You test the walkthrough in the Square Sandbox.

Link to section

Step 1: Prepare

• Review Sandbox testing consideration.

• Get credentials.

• Create two customers and add a card on file for one of these customers.

Link to section

Step 1.1: Square Sandbox testing considerations

To charge a customer for the subscription, you must add a card on file. To add a card on file, you use a fake payment token ("cnon:card-nonce-ok") that Square provides for Sandbox testing. The resulting card on file is a fake card that is never charged. For more information, see Sandbox Test Values.

The cURL commands in this exercise specify the connect.squareupsandbox.com domain in the endpoint URLs for Sandbox testing. In production, the domain is connect.squareup.com.

Link to section

Step 1.2: Gather account information

Follow these steps to gather account information for your Sandbox environment:

Link to section

Step 1.3: Create customers in the seller's Customer Directory

You can create subscriptions only for customers that have a profile in the seller's Customer Directory. In this step, create two customers and add a card on file for one of these customers.

You must provide a valid email address when creating these customers. Square emails the subscription invoices and receipts to this email address.

Link to section

Step 2: Create a subscription plan

Call the UpsertCatalogObject to create a subscription plan. In the request:

• name specifies the gym membership.

• phases includes two subscription phases.

  • Phase 1 offers a significant discount. It specifies a monthly cadence with only $1 (price_money). Also, the phase period value is set to 1, indicating a month-long phase. For more information about cadence, see Set up a subscription plan.

    Note

    You can set the price to 0 to offer a free initial phase. In this case, Square does not send an invoice until the initial free period is over. Therefore, the price is set to $1 so you can immediately verify the invoice.

  • Phase 2 identifies the weekly cadence with price_money set to $15. That is, customers pay a $15 weekly subscription fee. The phase does not specify the period, which indicates a continuous subscription.

    Upsert Catalog Object

    cURL

    • cURL
    • C#
    • Java
    • PHP
    • Python
    • Ruby
    • Node.js

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32

    curl https://connect.squareupsandbox.com/v2/catalog/object \
      -X POST \
      -H 'Square-Version: 2023-05-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "object": {
          "type": "SUBSCRIPTION_PLAN",
          "id": "#plan",
          "subscription_plan_data": {
            "name": "Multiphase Gym Membership",
            "phases": [
              {
                "cadence": "MONTHLY",
                "periods": 1,
                "recurring_price_money": {
                  "amount": 100,
                  "currency": "USD"
                }
              },
              {
                "cadence": "WEEKLY",
                "recurring_price_money": {
                  "amount": 1500,
                  "currency": "USD"
                }
              }
            ]
          }
        }
      }'

    Try in API Explorer

    The following is an example response:

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40

    {
      "catalog_object": {
        "type": "SUBSCRIPTION_PLAN",
        "id": "NS6YKIV4CWFGHQCA51111111",
        "updated_at": "2020-07-14T15:41:59.777Z",
        "version": 1594741319777,
        "is_deleted": false,
        "present_at_all_locations": true,
        "subscription_plan_data": {
          "name": "Multiphase Gym Membership",
          "phases": [
           {
              "uid": "2Z3OKONRGHLUEJL2FSYBH4V3",
              "cadence": "MONTHLY",
              "periods": 1,
              "recurring_price_money": {
                "amount": 100,
                "currency": "USD"
              },
              "ordinal": 0
            },
            {
              "uid": "7QEXRL7ID2RNCELANGPSO7JC",
              "cadence": "WEEKLY",
              "recurring_price_money": {
                "amount": 1500,
                "currency": "USD"
              },
      "ordinal": 1
            }
          ]
        }
      },
      "id_mappings": [
        {
          "client_object_id": "#plan",
          "object_id": "NS6YKIV4CWFGHQCA5D6NBIE3"
        }
      ]
    }
    

Link to section

Step 3: Create subscriptions

Create subscriptions for the two customers you created. One of the customers has a card on file so you include that card ID in the CreateSubscription request.