Subscriptions API

Subscription Billing and Invoices

Subscriptions created on the Square Developer Platform are billed in advance, beginning on the subscription's start_date and repeating based on the cadence specified in SubscriptionPlanVariation. At the start of each billing period, customers with a card_id on file as part of their subscription are charged based on the pricing object specified in SubscriptionPlanVariation. All other customers receive an emailed invoice with a payment link.

ACH payments aren't available through the Subscriptions API because bank account sources cannot be stored on file and charged later.

Each time an invoice is sent to a customer, it is emailed to the seller and its ID is added to the invoice_ids section of the Subscription object, listed in order of when the invoices were created (newest first). All invoices created by the Subscriptions API are available in the Seller Dashboard and include a subscription_id field. You can also manage invoices using the Invoices API. For more information, see Invoices API Overview.

As long as the subscription's status is ACTIVE, Square sends invoices regardless of whether the customer paid the invoices previously billed. Each invoice amount remains specific to the billing period, so individual invoices don't show any accumulation of the outstanding balance. You can track the payment status of subscriptions by subscribing to the invoices.payment_made webhook event of the Invoices API or by calling the ListPayments or GetPayment endpoint of the Payments API to retrieve payment objects and inspect the payment status.

All card payments made through the Square API, including subscription payments, incur seller transaction fees. These fees vary by country.

If a subscription has a card_id set and Square's attempt to charge the card fails, Square sends the invoice to the customer's email address with a link for making a payment. Square doesn't receive complete information from credit card providers about why payments fail. If a customer's card fails or is declined, they should contact the card provider for more information. In some circumstances, Square might deactivate a subscription that has become non-billable. For more information, see Deactivated subscriptions.

Link to section
Billing dates

Plan variations with a MONTHLY cadence (including multiple months, such as QUARTERLY or EVERY_SIX_MONTHS) are billed on the same day each billing cycle, based on the subscription's start_date. If the billing date isn't present in a given month, Square invoices the customer on the last date of that month. For example, a monthly subscription beginning on May 31 is billed again on June 30. An annual subscription beginning February 29 is billed again the next year on February 28.

Link to section
Deactivated subscriptions

After a subscription is created, some events can make a subscription non-billable, causing Square to deactivate the subscription. These reasons include:

The customer's email address is no longer valid or is deleted from the profile in the seller's Customer Directory.
The customer's name is deleted from the profile in the seller's Customer Directory.
The customer's entire profile is deleted from the seller's Customer Directory.
The location is deactivated by the seller.
The location isn't allowed to accept payments by the Square risk department.

The following is an example subscription with the status set to DEACTIVATED:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "subscription": {
    "id": "337270b4-2154-49a0-8160-710dd05930a7",
    "location_id": "7WQ0KXC8ZSD90",
    "plan_variation_id": "DYTUGVCCDBZRQDP3ASBBTPYL",
    "customer_id": "VXWW1WCNWCVDDBM0VGF3XJV9H8",
    "start_date": "2021-03-18",
    "charged_through_date": "2022-03-20",
    "status": "DEACTIVATED",  
    "invoice_ids": [
      "inv:0-ChDqhmIo-6qI0lpT567p1_XtEJAH"
    ],
    "version": 1616085625242,
    "created_at": "2021-03-18T09:40:25-07:00",
    "paid_until_date": "2022-03-20",
    "source": {
      "name": "My iOS App"
    },
    "timezone": "America/Los_Angeles"
  }
}

Square only deactivates a subscription at the end of the billing cycle. In the case of a monthly subscription billed on the first of the month:

On January 1, the customer is charged for their monthly subscription.
On January 15, the customer's email is deleted from their customer profile.
On February 1, Square discovers that the subscription is non-billable and deactivates the subscription. Square doesn't send any new invoices.

To learn when a subscription has been deactivated, your application can subscribe to the subscription.updated webhook to receive notifications and check when a subscription's status changes to DEACTIVATED. For more details about why the subscription was deactivated, call ListSubscriptionEvents with the subscription's ID.

List Subscription Events

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/events \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response showing a list of the subscription's events, including a DEACTIVATE_SUBSCRIPTION event. The info object provides the reason code and detail about why the subscription was deactivated.

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

  {
  "subscription_events": [
    {
      "id": "428cdeaf-71f6-46e3-87ee-e2954c1b01b8",
      "subscription_event_type": "START_SUBSCRIPTION",
      "effective_date": "2021-03-18",
      "plan_variation_id": "DYTUGVCCDBZRQDP3ASBBTPYL"
    },
    {
      "id": "f195d3e3-b71b-4adf-a8ac-1279781c8614",
      "subscription_event_type": "DEACTIVATE_SUBSCRIPTION",
      "effective_date": "2021-03-19",
      "plan_variation_id": "DYTUGVCCDBZRQDP3ASBBTPYL",
      "info": {
        "detail": "The customer with ID `PT7KZ4P8A0SZ75P8GAN30E06BM` does not have an email address.",
        "code": "CUSTOMER_NO_EMAIL"
      }
    },
    {
      "id": "0e631bca-caea-442e-96c8-0260db65542c",
      "subscription_event_type": "RESUME_SUBSCRIPTION",
      "effective_date": "2021-03-20",
      "plan_variation_id": "DYTUGVCCDBZRQDP3ASBBTPYL"
    }
  ]
}

Sellers can also use the Seller Dashboard to view deactivated subscriptions.

Link to section
Resume a deactivated subscription

After the issues causing the subscription deactivation have been resolved, there are two ways to resume a deactivated subscription:

A seller can resume a deactivated subscription in the Seller Dashboard.

Your application can call the ResumeSubscription endpoint as shown:

Resume Subscription

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/resume \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

This request fails unless all issues are resolved. A successful call to ResumeSubscription sets the subscription status to ACTIVE.

If a subscription is resumed in the middle of the billing cycle, Square sends a prorated invoice for the remaining billing cycle. In the case of a monthly subscription billed on the first of the month:

On January 1, the customer is charged for their monthly subscription.
On January 15, the customer's email is deleted from their customer profile.
On February 1, Square discovers that the subscription is non-billable and deactivates the subscription.
On February 15, the customer's email is added back to the profile.
On February 15, the application calls ResumeSubscription.
On February 15, Square sends a prorated invoice for the rest of February.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Subscription Billing and Invoices

Important

Link to section
Billing dates

Link to section
Deactivated subscriptions

Link to section
Resume a deactivated subscription

On this page

Docs

Subscription Billing and Invoices

Important

Link to section Billing dates

Link to section Deactivated subscriptions

Link to section Resume a deactivated subscription

On this page

Link to section
Billing dates

Link to section
Deactivated subscriptions

Link to section
Resume a deactivated subscription