Subscription Management

This guide covers how to manage existing subscriptions, including understanding their status and making changes to quantity or term.

Understanding Subscription Status

The status field on subscription endpoints provides insight into the provisioning state. Here is a breakdown of common statuses:

Actively Used:

• Active - An active subscription

• Cancelled - A cancelled subscription

• Converted - When a trial is converted to a paid subscription.

• PendingManual / PendingAutomated

  • Both of these display as "Provisioning" in the UI. This means the subscription record has been created, but the provisioning task is not yet closed.
  • The distinction is whether the provisioning task is fully automated or if a manual action is required by our service delivery team.
  • NOTE: This status can sometimes get "stuck" if service delivery manually provisioned the service but the task was not closed (or was skipped). It does not always mean the service wasn't provisioned in the vendor's system.

• PendingCancel

  • This means the subscription has been cancelled (and has an endDate), but deprovisioning has not yet occurred.
  • This status was used more frequently in the past when we scheduled future end dates. Now, an endDate is typically added to a subscription at the time a cancel order is received.

• Trial - A trial subscription. Trials are created with an end date so looking at the end date will help determine if it is active.

Rarely Used:

• PendingActivation

  • This status is no longer used. It was for older vendor models where hardware shipment confirmation was required before activating the subscription.

• Activated - This is related to the PendingActivation status that is also no longer used

• WaitingForDetails

  • This should not appear for most partners. It means provisioning details were missing when the subscription attempted to provision. We have validation to prevent this, so it would likely only occur due. to internal manual actions bypassing validation.

IMPORTANT: Billing and Subscription Status

Subscription status currently has no impact on billing. We bill subscriptions based on the subscription's start and end dates. This means that if there are provisioning delays, it is possible for billing to occur for a service that has not yet been fully provisioned in the vendor's system.

Future-Dated Subscription Changes

Future-Dated Cancellations

Cancelling subscriptions at a future date is supported via the Pax8 API. You can schedule a future cancellation via the following endpoint:

• Endpoint: Cancel Subscription

Future-Dated Subscription Changes: API vs. UX

While the Pax8 Platform (UX) allows users to schedule subscription changes for a future date, the Pax8 API currently handles changes immediately. There is no native API parameter to schedule a change for later execution.

Workarounds

To support future-dated requests via API, integrators must use one of the following methods:

1. Client-Side Scheduling (System Hold): Save the request details and the target date in your own system. Configure a job to trigger the API call only once the specified date arrives.
2. Manual PSA Workflow: Programmatically create a ticket in your PSA requesting the change. A representative from your team can then log in to the Pax8 UX to schedule the change manually.

Capability Matrix

Technical Reference

• Endpoint: Update Subscription - Quantity

Notes for API Users:

• NCE Products: The decrease will only be accepted post-renewal. You must store and manage subscription end dates to track when a quantity decrease can be processed via the Pax8 API.
• Non-NCE Products: Future-dated decreases are possible via the Pax8 platform interface but not the API. Make sure to handle these decreases with a similar time-check mechanism as suggested for orders and increases.

Automating Workflows with Subscription Events

To build a more robust and responsive integration, we highly recommend using Subscription Events. Instead of polling for changes, you can subscribe to events to automate workflows in real-time as changes occur.

Each event corresponds to a Completed Line Item—the atomic transaction that drives billing and provisioning—and includes a type field that identifies the nature of the change. By filtering on these types, you can build powerful, automated responses.

Common Use Cases:

• Trigger Onboarding: Use the New or TrialConvert types to automatically kick off your customer onboarding or welcome-email workflow.
• Automate Billing: Use Change (for seat increases/decreases) or Renewal to automatically update records in your internal billing system, ensuring quantities and term dates are always accurate.
• Handle Upgrades: Filter for ChangeProduct or ChangePartial to log and manage subscription upgrades or downgrades.
• Manage Churn: Use the Cancel type to trigger a de-provisioning process, notify an account manager, or start a customer-feedback workflow.

These are just a few examples. For a complete list of all event types and detailed integration guides, please see the Subscription Events page.