Subscription Actions and Events

Applies to: Subscriptions 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. Actions are scheduled future changes to subscriptions. Events represent past subscription changes.

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.

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

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.

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.

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"
    }
  ]
}