Guides

Subscription Events: Completed Line Items

Suggest Edits

When Pax8 emits subscription events, each event corresponds to a Completed Line Item—the atomic transaction that drives billing and provisioning. These events allow partners to automate workflows such as onboarding, billing updates, renewals, and cancellations.

Completed Line Items represent every transaction from subscriptions, arrears billing, and one-time charges. Each event includes a type field that identifies the nature of the change.


Line Item Types & What They Mean

Use these types to decide which events to subscribe to for automation:

  • New – A new subscription was created (initial entitlement).
  • Change – Mid-term modification (e.g., seat increase/decrease, price updates).
  • ChangePartial – A partial product swap. Related to upgrades/downgrades.
  • ChangeProduct – A full product swap. Related to upgrades/downgrades.
  • UpdateRatePlan – Rateplan change without altering the product.
  • SpiffPriceAdjustment – A promotion or spiff adjustment applied to the line item.
  • Renewal – A subscription commitment term was renewed.
  • Cancel – A subscription was fully canceled.
  • Resurrect – Reactivation of a previously canceled subscription.
  • Migration – Migration of a subscription (e.g., between partners or companies).
  • ParentReassignment – Ownership reassignment to a new parent subscription.
  • TrialCreate – A trial subscription was created.
  • TrialConvert – A trial converted to a paid subscription.
  • TrialCancel – A trial was canceled.
  • ArrearsUpload – Manual arrears line item (manual usage posting).
  • RevertToCurrent – Reverts a pending change back to current state.

Common Use Cases & Filtering Strategies

You can build powerful automations by filtering webhook topics for specific event actions or types. Here are several common workflows and the events you should use to build them:

  • Automated Onboarding:

    • Event: New
    • Use Case: Triggered immediately when a subscription is created. Use this to automate provisioning, create entitlement records, and send welcome emails.

  • Handling Subscription Upgrades:

    • Event: ChangeProduct
    • Use Case: This indicates a full subscription upgrade where the underlying SKU or product has been changed.
    • Event: ChangePartial
    • Use Case: This signals a partial quantity change. Important: This event fires on both the base subscription (decreasing quantity) and the new subscription (increasing quantity).

  • Trial-to-Paid Conversions:

    • Event: TrialConvert
    • Use Case: Triggered when a trial period ends and successfully converts to a paid plan. Use this to update your CRM and billing system.

  • Dynamic Billing & Usage Updates:

    • Events: Change, UpdateRatePlan, ArrearsUpload
    • Use Case: Use these events to keep your billing system in real-time sync with quantity changes, plan adjustments, and metered usage.

  • Renewal Confirmations:

    • Event: Renewal
    • Use Case: Triggered after a subscription successfully renews. Use this to send a confirmation receipt, refresh entitlements, and update billing records.

  • Automated Offboarding & Cleanup:

    • Event: Cancel
    • Use Case: Triggered when a subscription is canceled. Use this to immediately start deprovisioning workflows, stop billing, and reclaim licenses.

Important Note on Advanced Topic Filtering

Please be aware that advanced filtering for event subscriptions (e.g., filtering on specific event properties) is currently only possible via the API. This level of granular filtering is not available through the standard "Subscribe to Events" UX in the Integrations Hub.

To configure advanced filters, developers must use the API endpoints directly:

  1. Discover Topics & Filters: Use GET /webhooks/topic-definitions to retrieve all available topic definitions and the specific filterable conditions for each.
  2. Create or Update Subscriptions with Filters:
    1. Create: Use POST /webhooks and include the desired filter configuration within the webhookTopics array when creating a new webhook subscription.
    2. Update: To add or replace topics with filters, or to update the filter configuration on an existing topic, use the dedicated topic endpoints (like POST /webhooks/{id}/topics or POST /webhooks/{id}/topics/{topicId}/configuration).

Updated 14 days ago