Subscription Actions and Events

Applies to: Subscriptions API

Learn how to track Square subscriptions with actions and events.

Link to section

Overview

You can manage and follow the lifecycle of subscriptions on the Square Developer platform by tracking subscription actions and events. Actions are scheduled future changes to subscriptions. Events represent past subscription changes.

Link to section

Actions

To see future actions scheduled for subscriptions, call RetrieveSubscription or SearchSubscriptions. Set the include query parameter to actions, which includes the actions associated with the subscription in the response.

Retrieve subscription

The following is an example response:

The possible action types associated with subscriptions are:

  • PAUSE - Pause an active subscription indefinitely or for a set period of time. Scheduled by calling PauseSubscription.
  • RESUME - Resume a subscription that has been previously paused or deactivated. Scheduled by calling ResumeSubscription.
  • SWAP_PLAN - Swap the existing plan variation for another variation while maintaining the subscription. Scheduled by calling SwapPlan.
  • CANCEL - Cancel an active or paused subscription. Scheduled by calling CancelSubscription.
  • CHANGE_BILLING_ANCHOR_DATE - Change the subscription's billing_anchor_date. Scheduled by calling ChangeBillingAnchorDate.

After an action occurs, it becomes an event.

Link to section

Cancel an action

If you want to cancel an action before it occurs (for example, if a PAUSE action is scheduled but no longer necessary), call DeleteSubscriptionAction with the subscription_id and action_id to cancel the action.

Delete subscription action

Link to section

Events

Events represent past subscription changes. Call ListSubscriptionEvents to retrieve events for a specific subscription. The event types are:

  • START_SUBSCRIPTION - The subscription was created.
  • STOP_SUBSCRIPTION - The subscription was canceled.
  • PAUSE_SUBSCRIPTION - The subscription was paused.
  • PLAN_CHANGE - The SubscriptionPlanVariation was swapped with another (see Swap Subscription Plan Variations).
  • RESUME_SUBSCRIPTION - The subscription was resumed after being paused.
  • DEACTIVATE_SUBSCRIPTION - The subscription was deactivated.
  • BILLING_ANCHOR_DATE_CHANGED - The subscription's billing_anchor_date was changed.

List subscription events

The following is an example response: