Subscription Actions and Events

Applies to: Subscriptions APISubscriptions API

Learn how to track Square subscriptions with actions and events.

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

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

The following is an example response:

{
  "subscription": {
    "id": "8cb3cc07-b408-4340-a528-c2b971161e89",
    "location_id": "LS41RG22G3RNG",
    "plan_variation_id": "LOTN2MFIA57JWLRQEFLA2QDX",
    "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4",
    "start_date": "2021-09-30",
    "charged_through_date": "2021-10-30",
    "status": "ACTIVE",
    "invoice_ids": [
      "inv:0-ChBV_wzLxkOMfFM1CRi-pJ0QEKsI"
    ],
    "version": 1,
    "created_at": "2021-09-30T20:35:21Z",
    "timezone": "UTC",
    "source": {
      "name": "My iOS App"
    },
    "actions": [
      {
        "id": "f0a1dfdc-675b-3a14-a640-99f7ac1cee83",
        "type": "SWAP_PLAN",
        "effective_date": "2021-10-30",
        "new_plan_id": "P6MXKHZTCHMPCSRJMIQB75U6"
      },
      {
        "id": "99b2439e-63f7-3ad5-95f7-ab2447a80673",
        "type": "PAUSE",
        "effective_date": "2021-12-29"
      },
      {
        "id": "18ff74f4-3da4-30c5-929f-7d6fca84f115",
        "type": "RESUME",
        "effective_date": "2022-01-28"
      }
    ]
  }
}

The possible action types associated with subscriptions are:

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

After an action occurs, it becomes an eventevent.

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

Events represent past subscription changes. Call ListSubscriptionEventsListSubscriptionEvents 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 VariationsSwap Subscription Plan Variations).
• RESUME_SUBSCRIPTION - The subscription was resumed after being paused.
• DEACTIVATE_SUBSCRIPTION - The subscription was deactivated.deactivated.
• BILLING_ANCHOR_DATE_CHANGED - The subscription's billing_anchor_date was changed.

The following is an example response:

{
  "subscription_events": [
    {
      "id": "884b0d09-112b-4eae-929e-1154f0b5ccd1",
      "subscription_event_type": "START_SUBSCRIPTION",
      "effective_date": "2021-02-28",
      "plan_id": "RN3E4TBOBPDWHLB2OXG5VLYS"
    },
    {
      "id": "fd7d97f3-beba-4762-8d6f-f408aa1d96d1",
      "subscription_event_type": "PAUSE_SUBSCRIPTION",
      "effective_date": "2021-05-28",
      "plan_id": "RN3E4TBOBPDWHLB2OXG5VLYS"
    },
    {
      "id": "d7e9db43-3595-4f93-adb5-a5ab88c79c71",
      "subscription_event_type": "RESUME_SUBSCRIPTION",
      "effective_date": "2021-08-28",
      "plan_id": "RN3E4TBOBPDWHLB2OXG5VLYS"
    }
  ]
}