Managing subscriptions

If you choose to offer subscription-based digital goods in your application, you can use the Payment Service API to manage the subscriptions.

If you sell your application as a subscription on the BlackBerry App World storefront, the Payment Service confirms the validity of each user subscription. You can invoke purchase history methods to return objects that represent the parent application. These methods verify the user's current subscription status to determine whether the user should continue using the application.

Verifying application subscriptions

If you list your application as a subscription, you can verify the validity of a user's subscription by invoking PaymentEngine.checkExisting(), with the application's SKU as the parameter. This method returns a Boolean value that displays the validity of a user's subscription. If a user's subscription is not valid, you can use the following code sample to direct users to re-purchase the application in BlackBerry App World:
Browser.getDefaultSession().displayPage(“http://appworld.blackberry.com/webstore/clientlaunch/<content ID>/”);
Back To Top

Verifying digital good subscriptions

If you list digital goods as a subscription, you can verify the validity of a user's subscription by invoking PaymentEngine.checkExisting(), with the digital good's SKU as the parameter. This method returns a Boolean value that displays the validity of a user's subscription. If a user's subscription is not valid, you can prompt users to re-purchase the digital good by invoking PaymentEngine.Purchase().

Back To Top

Determining the status of a subscription

You can invoke Purchase.getItemState() to determine the status of a purchase. This method returns a constant that indicates the current status. These constants are included in the Purchase interface, and are described in the following table:

Constant

Description

SUBSCRIBED

This constant indicates that the subscription is active. Users can use the digital goods.

CANCELED

This constant indicates that the subscription was canceled. Users can still use the digital goods until the next renewal date.

REFUNDED

This constant indicates that the subscription was purchased, but subsequently refunded. Users cannot use the digital goods.

RENEW

This constant indicates that the subscription was renewed and is currently active. Users can use the digital goods.

OWNED

This constant indicates that the digital goods are not subscription-based, and that the user owns the digital goods.

In addition to the constants that are listed above, there are two additional methods in the PaymentEngine class that can help you determine the status of a subscription. You can invoke PaymentEngine.checkExisting() and provide an SKU as an argument. This method checks to see whether the user who is currently logged in using a BlackBerry ID is eligible to use the digital goods that are associated with the SKU that you provide. For example, if a subscription has a status of CANCELED, this method returns true until the next renewal date, because the user is eligible to use the digital goods until that date. After that date, this method returns false. If a subscription has a status of REFUNDED, this method returns false, because the user is not eligible to use the digital goods. After you invoke checkExisting(), you can invoke Purchase.get() with the same SKU to retrieve the Purchase object that corresponds to the SKU.

Subscription-based digital goods include both an initial time period and a renewal time period. For some digital goods, you might want to specify a custom initial time period that has a lower price (for example, if your digital goods include a trial period at a reduced cost). You can specify a custom initial time period when you register your digital goods on the vendor portal, and you can retrieve this time period by invoking Purchase.getInitialSubscriptionPeriod(). You can also invoke Purchase.getStartDate() to retrieve the date that a subscription starts, and you can invoke Purchase.getEndDate() to retrieve the date that a subscription expires.

Back To Top

Retrieving the price of a subscription

You can invoke PaymentEngine.getPrice() to retrieve the price of a subscription. You must provide an SKU as an argument to getPrice(), and this method returns a PriceSet object that contains the price of the purchase that the SKU corresponds to. After you retrieve the PriceSet object, you can invoke PriceSet.getPriceSetValue() and pass one of the following constants in the PriceSet interface to retrieve the corresponding information:

  • PRICE: The constant price of digital goods that are not subscription-based.
  • SUBSCRIPTION_INITIAL_PRICE: The initial price of subscription-based digital goods.
  • SUBSCRIPTION_RENEWAL_PRICE: The renewal price of subscription-based digital goods.
  • SUBSCRIPTION_PERIOD_NAME: The renewal time period of subscription-based digital goods (for example, "30 days").
  • SUBSCRIPTION_INITIAL_PERIOD: The initial time period of subscription-based digital goods.
Back To Top

Canceling a subscription

You can invoke PurchaseEngine.cancel() to cancel an existing subscription. You must provide the transaction ID of the subscription-based digital goods as an argument to this method. After you cancel a subscription, the status of the subscription changes to CANCELED. However, the user who purchased the subscription is eligible to use the digital goods until the next renewal date. After that date, the user can no longer use the digital goods.

Back To Top
Previous topic: Arguments for purchases

Was this information helpful? Send us your comments.