Handling Gift Subscriptions

Questions
1

We use Square Subscriptions in my home-built yoga-studio membership system.

Thinking about home-building a Gift Suscription method, and I need some clarification on supported workflows.

  1. Deferred-activation gift subscriptions

    • Can a subscription’s start_date and/or canceled_date be updated after creation via the UpdateSubscription endpoint?

    • If a subscription is created with a future start date, does Square validate or authorize the customer’s payment method at creation time, or only when the first invoice is generated?

    • Is there a supported pattern for a “gift” or “deferred activation” flow where billing should begin only when the recipient activates the subscription?

  2. Reliable detection of card failures
    Current process for card failures is customer can’t figure out why their subscription got cancelled (they pay no attention to Square emails). When customer complains, we say - ‘change your card.’ For gift subscriptions, I would like notification if a gifter’s card failed.

    • What is the recommended webhook or API-based method to detect a payment failure for a subscription renewal?

    • Are there canonical event types or fields I should monitor (e.g., invoice.payment_failed, payment.failed) to ensure I’m not missing failure cases that use different event names or payload structures?

    • Does Square provide a consolidated notification that ties a failed charge back to the specific subscription_id?

Any detailed guidance or example JSON payloads would be greatly appreciated.
Thank you for your help,
Jay Schauer

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Gift Card Webhooks
Subscription Plan Checkout
Use a Gift Card (Orders and Payments Integration)

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

  1. Deferred-activation gift subscriptions

    • Updating start_date and canceled_date: Yes, you can update a subscription’s start_date and canceled_date using the UpdateSubscription endpoint. This allows you to modify the activation and cancellation dates after the subscription has been created.

    • Payment method validation for future start dates: When a subscription is created with a future start date, Square does not immediately validate or authorize the customer’s payment method. The payment method is typically validated when the first invoice is generated and the payment is attempted.

    • Gift or deferred activation flow: Square does not natively support a “gift” or “deferred activation” flow where billing begins only upon recipient activation. However, you can implement this by creating the subscription with a future start date and updating it to the current date when the recipient is ready to activate it.

  2. Reliable detection of card failures

    • Detecting payment failures: To detect payment failures for subscription renewals, you should subscribe to the invoice.payment_failed webhook event. This event notifies you when a payment attempt for an invoice fails, which is crucial for handling subscription renewals.

    • Monitoring event types: The invoice.payment_failed event is the primary event to monitor for payment failures. Additionally, you can monitor the payment.failed event for more granular payment failure details. These events will help ensure you capture all failure cases.

    • Consolidated notification for failed charges: Square does not provide a direct notification that ties a failed charge back to a specific subscription_id. However, the invoice.payment_failed event will include details about the invoice and the associated subscription, allowing you to trace the failure back to the specific subscription.

By subscribing to these webhook events and implementing the suggested workflows, you can effectively manage deferred activation gift subscriptions and handle payment failures more reliably.

This answer was reviewed by @Bryan-Square.

4

Thanks for the help:
There are 2 parties involved

  1. the student who gets the gift, info about attending etc.
  2. the subscriber who creates the gift

Based on the ‘Pay on Subscription Created’ I plan to retain info on both, and provide an ‘Activation code’ that will be point at which the subscription is actually ‘created’

My plan is to capture the subscriber’s card with a nonce created at the time the gifting record gets made, and save it with the values in the gifting record. I’ll created a subscription using those values (including that nonce) when the subscription link is activated.

Do ccofs have an expire date? Or would it work after a month’s delay (or more)?