Premium Assets V2: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Show a customer everything they pay for

An app or assistant acting for an account owner often needs to answer "what am I paying for". Because a single account can hold plans, domains, business email, and digital goods, one query returns the whole picture.

To list everything an account currently pays for:

1. Call Query Premium Assets with the account in the targetAccountId header, filtering for active assets:

   Copy

2. For each returned asset, read productData.productTypeName to identify what kind of purchase it is.

3. Build a display name for each asset. Use productData.productName for Premium plans. For domains, business email, and digital goods that field is empty, so use domainsData.domain, mailboxesData.domainName, or digitalGoodsData.digitalGoodsType instead.

4. Read siteData.siteName to tell the customer which site each asset belongs to. Assets that aren't assigned to a site don't have siteData.

5. If pagingMetadata.hasNext is true, call Query Premium Assets again with cursorPaging.cursor set to pagingMetadata.cursors.next until every asset is retrieved.

Tell a customer when a subscription renews

Renewal questions are the most common thing a customer asks about a subscription. The asset carries both the renewal behavior and the last invoice, so no second call is needed.

To report the renewal state of an account's assets:

1. Call Query Premium Assets with the account in the targetAccountId header, sorted by the next invoice date:

   Copy

2. Read renewalType for each asset. AUTO_RENEW_ON means the customer is charged automatically, AUTO_RENEW_OFF means the subscription ends at the end of the period, and MANUAL means it renews only if the customer pays.

3. Read wixBillingDetails.nextInvoiceDetails.date for the next charge date. For assets with a renewalType of AUTO_RENEW_OFF, read subscriptionEndDate instead, since there's no next invoice.

4. Read wixBillingDetails.lastInvoiceDetails for what the customer last paid. Check billingReference.providerName before formatting amount, because its representation depends on the billing provider.

5. Check freeTrialData. When inFreeTrialPeriod is true, confirm that pendingExternalActivation is false before telling the customer they're in a free trial, because the same flag is set while billing is deferred.

Work out why a Premium product stopped working

When a customer reports that a Premium feature stopped working, the asset shows whether the underlying purchase is still active and, for domains, whether it's still usable.

To investigate a product that stopped working:

1. Call Query Premium Assets with the account in the targetAccountId header and no status filter, so inactive assets are returned too.

2. Find the affected asset by premiumId, or by siteData.metasiteId when you know only the site. To retrieve only the assets with specific Premium IDs, filter on premiumId:

   Copy

3. Read status. NOT_ACTIVE covers every inactive situation, including cancelled, expired, and failed subscriptions, so it confirms the purchase is no longer live without saying why. TRANSFERRED means a new asset was created for a different account.

4. Read wixBillingDetails.lastInvoiceDetails.paymentStatus. A value of CHARGE_ATTEMPT_FAILED points to a payment problem rather than a cancellation.

5. For domains, read domainsData.validInRegistrar and domainsData.expirationDate. A domain can be active as a purchase while no longer being valid at the registrar.

6. For domains still within their redemption period, read domainsData.redemptionPeriod to tell the customer how long they have to recover it.

Check whether a site has an active Premium plan

An app that gates features on Premium needs a yes or no answer for a specific site.

To check a single site:

1. Call Query Premium Assets with the account in the targetAccountId header, filtering on the site and an active status:

   Copy

2. Treat a non-empty premiumAssets array as the site having an active Premium purchase.

3. Read productData.productTypeId on the returned assets to decide whether the specific product type your app depends on is present.