Managing the SaaS subscription life cycle

Microsoft Marketplace manages the entire life cycle of a SaaS subscription after the end user purchases it. It uses the landing page, Fulfillment APIs, Operations APIs, and the webhook to drive the actual SaaS subscription activation, usage, updates, and cancellation. The end user's bill is based on the state of the SaaS subscription that Microsoft maintains.

States of a SaaS subscription

The following diagram shows the states of a SaaS subscription and the applicable actions.

Diagram showing the life cycle of software as a service subscription in Microsoft Marketplace.

Important

When you enable auto activation, the subscription goes directly to the Subscribed state, skipping PendingFulfillmentStart. Publishers can enable auto activation in Partner Center. For more information, see Create plans for a SaaS offer.

Summary of behaviors

Step Manual activation Automatic activation
PendingFulfillmentStart state Yes No
Landing page redirect Yes No
Resolve API required Yes No
Activate API required Yes No
Billing starts After activation Immediately after purchase

Purchased but not yet activated (PendingFulfillmentStart)

This state applies only to SaaS offers that are configured for manual activation. It represents a subscription that is successfully purchased but not yet activated by the publisher. For SaaS offers configured for auto activation, the subscription is activated immediately after purchase and transitions directly to the Subscribed state.

After an end user or cloud solution provider (CSP) purchases a SaaS offer in Microsoft Marketplace, the publisher is notified of the purchase. The publisher can then create and configure a new SaaS account on the publisher side for the end user.

For account creation to happen:

  1. The customer selects the Configure account now button that's available for a SaaS offer after its successful purchase in Microsoft Marketplace or from Marketplace within Azure portal. Alternatively, the customer can use the Configure now button in the email that they receive shortly after the purchase.
  2. Microsoft then notifies the partner about the purchase by opening the landing page URL with the token parameter (the purchase identification token from Microsoft Marketplace) in the new browser tab.

An example of such call is https://contoso.com/signup?token=<blob>, but the landing page URL for this SaaS offer in Partner Center is configured as https://contoso.com/signup. This token provides the publisher with an ID that uniquely identifies the SaaS purchase and the customer.

Tip

Don't include the pound sign character (#) in the landing page URL. Otherwise, customers can't access your landing page. The publisher has 30 days to resolve the asset when the status is PendingFulfillmentStart. Otherwise, the asset is voided. Because the billing cycle wasn't initiated and the respective purchase isn't billed, the status then changes to Unsubscribed. The customer isn't billed for the purchase.

Important

The landing page URL must be up and running all day, every day, and ready to receive new calls from Microsoft always. If the landing page becomes unavailable, customers can't sign up for the SaaS service and start using it.

Next, the publisher must pass the token back to Microsoft by calling the SaaS Resolve API, and entering the token as the value of the x-ms-marketplace-token header parameter. As the result of the Resolve API call, the token is exchanged for details of the SaaS purchase such as the unique ID of the purchase, purchased offer ID, and purchased plan ID.

On the landing page, the customer should be signed in to the new or existing SaaS account via Microsoft Entra single sign-on (SSO).

Note

The publisher isn't notified of the SaaS purchase until the customer initiates the configuration process from the Microsoft side.

The publisher should implement SSO to provide the user experience required by Microsoft for this flow. Make sure to use the multitenant Microsoft Entra application and allow both work and school accounts or personal Microsoft accounts when configuring SSO. This requirement applies only to the landing page, for users who are redirected to the SaaS service when already signed in with Microsoft credentials. SSO isn't required for all sign-ins to the SaaS service.

Note

If SSO requires that an administrator must grant permission to an app, the description of the offer in Partner Center must disclose that admin-level access is required. This disclosure is to comply with Microsoft Marketplace certification policies.

After sign in, the customer should complete the SaaS configuration on the publisher side. Then, the publisher must call the Activate Subscription API to send a signal to Microsoft Marketplace that the provisioning of the SaaS account is complete. This action starts the customer's billing cycle. If the Activate Subscription API call isn't successful, the customer isn't billed for the purchase.

Diagram showing the A P I calls for a provisioning scenario.

Both the purchaser and the billing account owner receive an email requesting them to configure the account.

Note

The publisher has 30 days to resolve the asset when the status is PendingFulfillmentStart. Otherwise, the asset is voided since the billing cycle wasn't initiated and the respective purchase isn't billed. The status changes to Unsubscribed. The customer isn't billed for the purchase.

Active (Subscribed)

Active (Subscribed) is the steady state of a provisioned SaaS subscription. After the Microsoft side processes, the Activate Subscription API call, the SaaS subscription is marked as Subscribed. The customer can now use the SaaS service on the publisher's side and is billed.

When a SaaS subscription is already active, the customer can select Manage SaaS experience from the Azure portal or Microsoft 365 Admin Center. This action also causes Microsoft to call the landing page URL with the token parameter, as happens in the Activate flow. The publisher should distinguish between new purchases and the management of existing SaaS accounts, and handle this landing page URL call accordingly.

An activation notification email is sent to both the purchaser and the billing account owner.

Being updated (Subscribed)

This state means that Microsoft and the publisher are processing an update to an existing active SaaS subscription. Updates can come from:

  • The customer through Microsoft Marketplace.
  • The CSP through Microsoft Marketplace.
  • The customer through the publisher's SaaS site (but not for CSP-made purchases).

Two types of updates are available for a SaaS subscription:

  • Update plan when the customer chooses another plan for the subscription.
  • Update quantity when the customer changes the number of purchased licenses for the subscription.

You can only update an active subscription. While the subscription is being updated, its state remains Active on the Microsoft side.

Update initiated from Microsoft Marketplace

In this flow, the customer changes the subscription plan or quantity of licenses from the Azure portal or Microsoft 365 Admin Center.

  1. After an update is entered, Microsoft calls the publisher's webhook URL, configured in the Connection webhook field on the Technical configuration page in Partner Center, with an appropriate value for action and other relevant parameters.
  2. The publisher side makes the required changes to the SaaS service, and notifies Microsoft when finished by calling the Update Status of Operation API.
  3. If the patch is sent with fail status, the update process doesn't finish on the Microsoft side. The SaaS subscription keeps the existing plan and quantity of licenses.

Note

The publisher should invoke PATCH to update the Status of Operation API with a Failure/Success response within a 10-second time window after receiving the webhook notification. If PATCH of operation status isn't received within the 10 seconds, the change plan is automatically patched as Success.

The following diagram shows the sequence of API calls for an update scenario that initiates from Microsoft Marketplace.

Diagram showing the A P I calls for a Microsoft Marketplace initiated update.

Update initiated from the publisher

In this flow, the customer changes the subscription plan or quantity of licenses purchased from the SaaS service itself.

  1. Before the requested change is made on the publisher side, the publisher code must call the Change Plan API or the Change Quantity API or both.
  2. Microsoft applies the change to the subscription, and then notifies the publisher via Connection webhook to apply the same change.
  3. Only then does the publisher make the required change to the SaaS subscription, and notify Microsoft when the change is done by calling Update Status of Operation API.

The following diagram shows the sequence of API calls for an update scenario that initiates from the publisher side.

Diagram showing the A P I calls for a publisher side initiated update.

A notification email indicating a plan change is sent to both the purchaser and the billing account owner.

A notification email indicating a change in quantity is sent to both the purchaser and the billing account owner.

Suspended (Suspended)

This state indicates that a customer's payment for the SaaS service wasn't received. Microsoft notifies the publisher of this change in the SaaS subscription status. The notification is done via a call to webhook with the action parameter set to Suspended.

The publisher might or might not make changes to the SaaS service on the publisher side. We recommend that the publisher makes this information available to the suspended customer and limits or blocks the customer's access to the SaaS service. There's a probability that the payment isn't ever received.

Note

Microsoft gives the customer a 30-day grace period before automatically canceling the subscription. After the 30-day grace period is over, the webhook receives an Unsubscribe action.

When a subscription is in the Suspended state:

  • The partner or ISV must keep the SaaS account in a recoverable state, so that full functionality can be restored without any loss of data or settings.
  • The partner or ISV should expect a request to reinstate the subscription, if the payment is received during the grace period, or a request to de-provision the subscription at the end of the grace period. The webhook mechanism sends both requests.

The subscription state is changed to Suspended on the Microsoft side before the publisher takes any action. Only Active subscriptions can be suspended.

A notification email indicating the change in status to Suspended is sent to both the purchaser and the billing account owner.

Following a 30-day period of suspension, an email regarding the post-suspension cancellation is sent to both the purchaser and the billing account owner.

Reinstated (Suspended)

This action indicates that the customer's payment instrument is valid again. A payment was made for the SaaS subscription and the subscription is reinstated. In this case:

  1. Microsoft calls webhook with an action parameter set to the Reinstated value.
  2. The publisher makes sure that the subscription is fully operational again on the publisher side.
  3. The Reinstate process is successful and the customer is billed again for the SaaS subscription.

Only a suspended subscription can be reinstated. The suspended SaaS subscription remains in a Suspended state while it's being reinstated. After this operation finishes, the subscription's status becomes Active.

An email is sent to both the purchaser and the billing owner following the transition from suspended state to reinstated state.

Renewed (Subscribed)

The default for the autorenewal setting is off for all SaaS subscriptions. The SaaS subscription is automatically canceled at the end of the current billing term. Customers can also cancel the SaaS subscription at any time. A customer can turn on automatic renewal for a SaaS subscription via the Microsoft 365 Admin Portal. In this case, Microsoft automatically renews the SaaS subscription at the end of the subscription term of a month or a year if the auto renew setting is turned on. Active SaaS subscriptions continue to be renewed with a regular cadence. Microsoft provides inform-only webhook notifications for renew events.

Only active subscriptions are automatically renewed. Subscriptions stay active during the renewal process, and if automatic renewal succeeds. After renewal, the start and end dates of the subscription term are updated to the new term's dates.

If an autorenewal fails because of an issue with payment, the subscription becomes Suspended and the publisher is notified.

Reminder emails for renewal are sent to both the purchaser and the owner of the billing account, 30 days before the annual/multiyear renewal date.

Canceled (Unsubscribed)

Subscriptions reach this state after an explicit customer or CSP action to cancel the subscription. Customers can cancel a subscription from the publisher site, the Azure portal, or the Microsoft 365 Admin Center. A subscription is also canceled implicitly as the result of nonpayment of dues after being in the Suspended state for 30 days.

After the publisher receives a cancellation webhook call, they should retain customer data for recovery on request for at least seven days. Only then can customer data be deleted.

You can cancel a SaaS subscription at any point in its life cycle. After a subscription is canceled, you can't reactivate it.

The cancellation email is sent to both the purchaser and the owner of the billing account.

Free trials

A SaaS subscription can be in a free trial when the customer purchases a trial-enabled plan. The same SaaS subscription states described in this article also apply to SaaS trial subscriptions. The following table explains how each state or action applies during or after a free trial.

State or action How it applies to free trials
PendingFulfillmentStart Applies to manually activated plans, including plans with free trials. The subscription is purchased but not yet activated. The free trial period doesn’t start until the publisher activates the subscription.
Subscribed The subscription is active. During the free trial period, the customer can use the SaaS service and isn’t charged for the plan.

If the plan uses auto activation, Microsoft activates the subscription at purchase and sends a Subscribe webhook notification with the subscription details.
Being updated If the customer upgrades to paid before the trial ends or changes plans during the trial.

If the customer changes from one trial-enabled plan to another trial-enabled plan within the same offer, the trial period doesn’t restart. If the customer changes to a plan that doesn’t have a free trial, the free trial ends immediately and billing starts for the selected paid plan.
Renewed If the customer doesn’t cancel before the trial ends, the subscription converts to paid at the end of the free trial period. Renewals after conversion follow the same behavior as other active SaaS subscriptions.

The subscription remains Subscribed after conversion.
Canceled If the customer cancels during the free trial, the trial ends and the subscription doesn’t convert to paid.
Suspended and reinstated These states apply after the subscription is paid. If payment fails after the trial converts to paid, the subscription can be suspended and later reinstated according to the standard SaaS lifecycle.

Related content

Video tutorials

  • Last updated on