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

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.

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}?include=actions \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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.

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.

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/actions/{action_id} \
  -X DELETE \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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.

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/events \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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