Documentation # Subscriptions & Billing
The App Center is designed as a vast marketplace that offers merchants the ability to subscribe to your applications based on your pre-estbalished plan. For this reason, subscription plans play an important role in the billing and monetization flow.
Below, we have compiled the different aspects of subscriptions that you must consider when integration with GoDaddy Poynt Billing.
# Subscription Lifecycle
Poynt Billing Service is responsible for maintaining the life-cycle of each subscription from start to finish.
In this sense, subscriptions are initiated when a merchant subscribes to an application on the app center and they end when either a merchant explicitly requests a cancellation or fails to pay for the subscription within the allowed grace period.
NOTE
Merchants can cancel subscriptions through the GoDaddy Poynt Apps application on the Account screen found in App Center.
# Subscription Verification
Although Poynt Apps and Billing services take care of handling all billing needs for your app, it is very important for your applications to perform all the necessary checks to make sure all your users have subscribed to your app and their subscriptions are in good standing.
Poynt In-App and RESTful Billing APIs provide various ways for you to perform these checks from your App or from your backend:
In-App Billing Service: IPoyntInAppBillingService provides the necessary APIs on the PoyntOS platform for your App to verify the subscription status programmatically.
These include APIs to get subscriptions associated with the current business (to which the terminal is associated with), and plans associated with your own app.
RESTful APIs: Poynt Billing Service provides simple REST apis to obtain all subscriptions associated with your application. This includes both active and inactive subscriptions.
Web Hooks: Poynt Billing Service sends SUBSCRIPTION START and END webhook events that you can receive on your backend to record the merchants that have started or ended their subscriptions.
The webhook event includes the merchant’s businessId, your applicationId, and a url to GET the subscription status.
# Billing Cycle
The billing cycles dictates when and how merchants are charged for their app subscriptions. Currently, GoDaddy Poynt only supports monthly billing cycles, which you must select when creating a new subscription plan for your application.
The billing cycle begins on the first day of each month and ends with said month. Whenever a merchant subscribes to an application, GoDaddy Poynt Billing calculates the prorated amount based on the days that the merchant will be using the app before the next billing cycle.
# Billing Use Cases
When you integrate with GoDaddy Poynt Billing, it's important to consider the following scenarios and make sure your application code can handle them as necessary.
Below are some of the most common uses cases to keep in mind:
Merchant has a valid subscription but has never used your app before (First Time Subscriber)
Merchant has a valid subscription and has used your app in the past (Returning Subscriber)
Merchant has a canceled subscription after using your app (Canceled Subscriber)
Merchant has no subscriptions and has never used your app.
NOTE
Although this is no longer possible once you’ve integrated with GoDaddy Poynt Billing, we still recommend you to handle this scenario to prevent any fraud that might occur in the future. (Not a Subscriber)
Merchant has no subscriptions but has used your app before
TIP
These are your existing merchants before you switch to GoDaddy Poynt billing. You must ensure support for these merchants to provide a more graceful upgrade process to billing. (Sponsored Subscriber)
Merchant has a valid subscription but wants to upgrade or downgrade (Upsell/Downsell Subscriber)
# Supporting Existing Merchants
Whenever you release an update for your application, it is very important to make sure all existing merchants can continue to use your app - not just the newly subscribed merchants. This includes both merchants that have installed your app without any subscriptions in the past or with subscriptions using older billing plans.
For new plans, please indicate whether you intend to replace existing plans with the new plans or add them as additional plans.
Please note that Poynt never deletes existing plans that have any on-going subscriptions attached to them, but can hide them from being displayed to the merchants as available billing plans based on your needs.
When deprecating existing plans, please make sure you handle merchants with existing subscriptions gracefully.
You can either continue supporting them, or ask them to upgrade from within your application to a newer plan using the GoDaddy Poynt's Billing Fragment API.
TIP
Avoid hard coding the planIds in your application APKs.
You can use the GetPlans API in the Poynt InAppBillingService to query available plans for your application and use your backend to identify what features/functionality the merchant is authorized to use based on the subscribed plan.
This will help you support merchants that might have subscribed to a newer plan but still using an older version of your app.
# Upgrades & Downgrades
Upgrades and downgrades are now supported for Cloud Apps and Smart Terminal Apps and can be implemented following the recommendations for each application.
If you'd like to learn more about this topic, please refer to one of the following articles:
Please note that in some cases, it’s also a valid use case for a merchant to have multiple subscriptions for different premium features provided by your application. So it’s really up to your application’s monetization models on how you would like to handle these.