Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Subscriptions API

Example 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. In the walkthrough, you 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.

Step 1: Prepare Permalink Get a link to this section

Step 1.1: Square Sandbox testing considerations Permalink Get a link to this section

To charge a customer for the subscription, you must add a card on file. To add a card on file, you use a fake nonce ("cnon:card-nonce-ok") provided 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.

Step 1.2: Gather account information Permalink Get a link to this section

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

  1. Sign in to the Developer Dashboard..

  2. Open one of your applications, which provides you with the credentials you use. If you do not have an application, you first create an application.

  3. Get Sandbox credentials:

    1. On the Credentials page, you can toggle between the Sandbox mode and Production mode. Choose Sandbox.

    2. Copy the access token from Sandbox Access Token.

  4. Get a location ID. When creating subscriptions, you provide a seller location ID where the subscription was created.

    1. Choose Locations in the left navigation.

    2. On the Locations page, choose a location ID.

Step 1.3: Create customers in the seller's Customer Directory Permalink Get a link to this section

You can create subscriptions only for the 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 the receipts to this email address.

  1. Create a customer:

    1. Call CreateCustomer to create a customer.

      curl https://connect.squareupsandbox.com/v2/customers \
        -X POST \
        -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -d '{
          "family_name": "Doe",
          "idempotency_key": "{{UNIQUE_KEY}}",
          "email_address": "{{user@email.com}}",
          "given_name": "John"
        }'
      

      The following is an example response:

      {
         "customer":{
            "id":"P00DNFEQZRSHQAWMK2YNQ1111111",
            "created_at":"2020-05-11T00:17:03.037Z",
            "updated_at":"2020-05-11T00:17:03Z",
            "given_name":"John",
            "family_name":"Doe",
            "email_address":"user@email.com",
            "preferences":{
               "email_unsubscribed":false
            },
            "creation_source":"THIRD_PARTY"
         }
      }
      
    2. Note the customer ID. You provide this ID when creating a subscription.

  2. Create another customer. This time add a card on file for this customer. Make sure to provide a valid email address to receive emails.

    1. Call CreateCustomer to create a customer:

      curl https://connect.squareupsandbox.com/v2/customers \
        -X POST \
        -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -d '{
          "family_name": "Doe",
          "idempotency_key": "{{UNIQUE_KEY}}",
          "email_address": "{{user@email.com}}",
          "given_name": "Jane"
        }'
      

      The following is an example response:

      {
         "customer":{
            "id":"XWTW3CBG74WGQEGH4FK1111111",
            "created_at":"2020-05-11T00:21:17.582Z",
            "updated_at":"2020-05-11T00:21:18Z",
            "given_name":"Jane",
            "family_name":"Doe",
            "email_address":"user@email.com",
            "preferences":{
               "email_unsubscribed":false
            },
            "creation_source":"THIRD_PARTY"
         }
      }
      
    2. Note the customer ID. You need this ID when creating a subscription.

    3. Add a card on file using the nonce Square provides for Sandbox testing:

      curl https://connect.squareupsandbox.com/v2/customers/976VQB7RZMTDSBG76BMEY9PSF8/cards \
        -X POST \
        -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -d '{
          "card_nonce": "cnon:card-nonce-ok"
        }'
      

      The following is an example response:

      {
         "card":{
            "id":"ccof:oW5s9sZR2T1jEzeW4GB",
            "card_brand":"MASTERCARD",
            "last_4":"9029",
            "exp_month":5,
            "exp_year":2022
         }
       }
      
    4. Note the card ID. When adding a subscription for this customer, you provide this card ID so that Square can charge the subscription fee to this card.

Step 2: Create a subscription plan Permalink Get a link to this section

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.

      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, we set the price 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 indicating a continuous subscription.

      curl -X POST \
      -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
      -H 'Accept: application/json' \
      -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"
                     }
                  }
               ]
            }
         }
      }' \
      'https://connect.squareupsandbox.com/v2/catalog/object'
      

      The following is an example response:

      {
        "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"
          }
        ]
      }
      

Step 3: Create subscriptions Permalink Get a link to this section

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.

  1. Make sure you have the following information:

    • Subscription plan ID

    • Customer ID

    • Card ID for the card on file

    • Location ID

  2. Call CreateSubscription to create a subscription for the customer without a card on file:

    curl -X POST \
    -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
      "idempotency_key": "{{UNIQUE_KEY}}",
      "location_id": "{{LOCATION_ID}}",
      "plan_id": "{{SUBSCRIPTION_PLAN_ID}}",
      "customer_id": "{{CUSTOMER_ID}}"
    }' \
    'https://connect.squareupsandbox.com/v2/subscriptions'
    

    The following is an example response:

    {
      "subscription": {
        "id": "3a936436-5836-437d-93e7-b1588c111111",
        "location_id": "S8GWD5R9QB376",
        "plan_id": "3ZODVTLGZVTS6PGBY525H4HQ",
        "customer_id": "7FCET7VZ0CTKZ6FXN6HXWVWNG0",
        "start_date": "2020-08-04",
        "status": "ACTIVE",
        "version": 1596555964218,
        "created_at": "2020-08-04T15:46:03Z",
        "timezone": "Etc/UTC"
      }
    }
    

    In production, after the subscription is created, Square sends an invoice to the customer's email address (Square Sandbox does not send emails). An example is shown:

    subscription-example

    The customer can choose Pay Invoice to open the Square-hosted invoice page to pay for the invoice. The seller also receives a similar email indicating an invoice is sent.

  1. Call CreateSubscription to create a subscription for the customer with a card on file. In the request, card_id is the card ID.

    curl -X POST \
    -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
      "idempotency_key": "{{UNIQUE_KEY}}",
      "location_id": "{{LOCATION_ID}}",
      "plan_id": "{{SUBSCRIPTION_PLAN_ID}}",
      "customer_id": "{{CUSTOMER_ID}}",
      "card_id": "{{CARD_ID}}"
    }' \
    'https://connect.squareupsandbox.com/v2/subscriptions'
    

    The following is an example response:

    {
      "subscription": {
        "id": "5c821827-b16a-4d3b-9682-74eb17811111",
        "location_id": "S8GWD5R9QB376",
        "plan_id": "3ZODVTLGZVTS6PGBY525H4HQ",
        "customer_id": "X09BC00N4WW277H37VKQJJ3GF8",
        "start_date": "2020-08-04",
        "status": "ACTIVE",
        "version": 1596556111837,
        "created_at": "2020-08-04T15:48:31Z",
        "card_id": "ccof:OBdYpQWm8RGByBx93GB",
        "timezone": "Etc/UTC"
      }
    }
    

    If you test this in production, after charging the customer's card on file, Square sends a receipt to the customer's email address.

  1. Verify the invoices in the Seller Dashboard.

    1. Sign in to the Developer Dashboard.

    2. In the Sandbox Test Accounts section, choose open for the Default Test Account.

    3. In the left pane, choose Invoices, and then verify that the two invoices (paid and unpaid) are present.