Subscription Billing and Invoices

Applies to: Subscriptions API | Invoices API | Payments API

Learn about subscription billing and how Square invoices are used in the Subscriptions API.

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.

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 Square Dashboard and include a subscription_id field. You can also manage invoices using the Invoices API. For more information, see Invoices API.

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.

Plan variations with a day-based cadence (such as EVERY_TWO_WEEKS, THIRTY_DAYS, and NINETY_DAYS) are billed relative to the subscription's start_date. Variations with a MONTHLY cadence (including multiple months, such as QUARTERLY, EVERY_SIX_MONTHS, and ANNUAL) can be configured to bill on a specific numbered day of the month by setting the monthly_billing_anchor_date when creating or updating a CatalogSubscriptionPlanVariation. For example, a plan variation with a monthly_billing_anchor_date of 15 always bills (by charging the card on file or emailing the customer an invoice) on the 15th day of the relevant month, regardless of the start_date of a specific subscription.

Optionally, you can allow prorated (partial) charging for subscriptions by setting the can_prorate field to true on the plan variation upon creation. If true, Square sends an invoice for a portion of the total amount, based on the number of days until the next billing date. For example, you offer a monthly subscription that charges customers on the 15th of every month, and allows proration. If a customer subscribes on September 30, they are charged half the total subscription amount immediately, and sent another invoice for the full amount on October 15.

If a plan variation has can_prorate set to false, customers can subscribe at any time, but they are charged the full amount of the first phase immediately, regardless of the billing_anchor_date. A customer subscribing on October 1 to a variation billing monthly on the 15th would be charged the subscription's full amount on October 1st, and again on October 15.

For all cadences, 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 quarterly subscription billing on January 31 is billed again on April 30. An annual subscription billing February 29 is billed again the next year on February 28.

Use the ChangeBillingAnchorDate endpoint to change the billing date for an individual customer’s subscription.

The response returns the current Subscription object containing a new, scheduled CHANGE_BILLING_ANCHOR_DATE action. The monthly_billing_anchor_date remains the same until the action's effective_date (the next occurrence of the anchor date).

{
  "subscription": {
    "id": "910afd30-464a-4e00-a8d8-2296e",
    "location_id": "S8GWD5R9QB376",
    "plan_variation_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "card_id": "ccof:qy5x8hHGYsgLrp4Q4GB",
    "start_date": "2023-01-19",
    "paid_until_date": "2023-11-19",
    "status": "ACTIVE",
    "invoice_ids": [
      "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
      "inv:0-ChrcX_i3sNmfsHTGKhI4Wg2mceA"
    ],
    "created_at": "2022-01-19T21:53:10Z",
    "version": 3,
    "timezone": "America/Los_Angeles",
    "monthly_billing_anchor_date": 19,
    "source": {
      "name": "My Application"
    }
  },
  "actions": [
    {
      "id": "f0a1dfdc-675b-3a14-a640-99f7ac1cee83",
      "type": "CHANGE_BILLING_ANCHOR_DATE",
      "effective_date": "2023-12-04",
      "monthly_billing_anchor_date": 4
    }
  ]
}

Note that ChangeBillingAnchorDate doesn't change the billing date for any other customers subscribed to the same plan variation. To make changes to multiple customer subscriptions at once, you must use the BulkSwapPlan endpoint to reassign subscription plan variations.

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:

{
  "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:

1. On January 1, the customer is charged for their monthly subscription.
2. On January 15, the customer's email is deleted from their customer profile.
3. 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.

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.

  {
  "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 Square Dashboard to view deactivated subscriptions.

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 Square Dashboard.

• Your application can call the ResumeSubscription endpoint as shown:

  Resume subscription

  cURL

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:

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