Subscription Management

Build a robust subscription management integration by understanding subscription state, handling quantity or term changes, and reacting to subscription lifecycle events.

Most subscription workflows depend on more than a single update call. In most implementations, you need to understand the current subscription state, decide whether the requested change should happen now or later, account for billing and commitment rules, and then synchronize the result into your PSA, billing platform, or internal workflow.

Recommended Build Flow

1. Resolve the Current Subscription State

Read the subscription before you make changes so you can see its status, dates, quantity, and current term. Treat the subscription record as the source for what exists now, then apply your business logic on top of it.

2. Decide Whether the Change Is Immediate or Future-Dated

Some subscription changes can be scheduled, while others must be handled immediately by the API or delayed in your own system. Make that decision before you build downstream billing, ticketing, or customer communication steps.

3. Apply the Change and Store the Result

When you update quantity, term, or cancellation state, store the returned identifiers and dates in your own system. This gives you a reliable record for reconciliation and downstream workflows.

4. Use Events for Downstream Automation

Use subscription events to keep external systems aligned after the change is complete. This is usually more reliable than polling alone for onboarding, billing updates, lifecycle notifications, and churn handling.

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.

If your business process requires a future execution date, store that timing in your own system and trigger the API call when the change should take effect.

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: When a Microsoft NCE subscription net new order or subscription renewal occurs, there is a 7 day window for a cancel or qty decrement before it locks in for the commitment term. While the sub is in this window, we only allow cancellations to be submitted for the same day. After you are out of that window, we will allow you to schedule the cancellation on the commitment term end date.
• 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.

Design Recommendations

• Treat subscription status as provisioning context, not billing truth.
• Use start dates, end dates, and commitment dates when you design billing and cancellation logic.
• Store requested future-dated changes in your own system when the API cannot schedule them directly.
• Use events to update downstream systems after changes complete instead of relying only on polling.

Related Integration Guides

If you want a more specific, use-case-driven subscription workflow, use these Integration Guides in the Pax8 platform. They include detailed steps for common lifecycle scenarios and give you structured flows that you can adapt in your own system or push into your preferred AI tool to accelerate implementation.