App Marketplace

Subscriptions API Requirements

The App Marketplace requirements described in this topic apply to partner applications that use the Subscriptions API.

Outdated subscription plans Permalink Get a link to this section

When you change a subscription plan name or a phase price, the change is effective immediately on any existing subscriptions for the plan. If you do not want this to happen, you can create another subscription plan. In this case, you have two active subscription plans and you can create subscriptions in both plans. Partner application should disable the outdated plan by setting the enabled_at_all_locations field to false. When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.

Customer subscription management Permalink Get a link to this section

Note that the Subscriptions API requires customers to have a profile in the seller's Customer Directory to enroll them in a plan. The customer profiles must also include a valid email address because Square sends the subscription invoices and the receipts to this email address. For more information, see Manage enrollments in a subscription plan. The following requirements apply to all partner applications:

  • A customer must have the ability to cancel a subscription or continue a pending canceled subscription.

  • A customer must have the ability to add or remove the selected card on file for a subscription. A customer is only able to select a card on file that is stored through a partner application (do not use card_ids that previously existed). .

Subscription invoice tracking Permalink Get a link to this section

Partners should leverage the webhooks provided by the Invoices API to track payments made on invoices. Note that a subscription invoice has the subscription_id that links the Invoice object back to the corresponding subscription. The following guidelines apply:

  • Partner applications should use invoice.payment_made webhooks to track successful invoice payments. The paid invoice should then be attributed back to the specified subscription.

  • Partner applications should use the invoice.scheduled_charge_failed webhooks to track failed invoice payments.

  • Reminders are scheduled relative to the due_date of the payment request (see InvoicePaymentReminder). These payment reminders are specified on each individual invoice. For more information, see InvoicePaymentReminder. Reminders must be set before the payment due date specified on each invoice on an ongoing basis and after the payment due date if payment is not received.

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