On the Pricing & Distribution page, for each pricing tier with a single Metered ID, you must track the merchant events, and post the IDs to Clover using the metereds endpoint.

👍

TIP

Create a single pricing tier with all the countries to introduce the same pricing tier in other regions, and send only one set of events for a single Metered ID.

Alternatively, if you create separate pricing tiers with separate Metered IDs for each country, you must post one set of events for each unique Metered ID.

At the end of the month, Clover uses the total number of events for a pricing tier and then multiplies it with the price you set on a pricing tier for a country to calculate how much the merchant must be charged for the metered events.

Track metered events

Use the Apps REST API endpoint or the Android AppsConnector method to track metered events.

The following shows you how to use the metereds endpoint.
POST {baseURL}/v3/apps/{aId}/merchants/{mId}/metereds/{meteredId}

Android AppsConnector Method
Use the Android AppsConnector method to send the events to Clover: logMetered(String meteredId, int numberOfEvents)

Android Example
The following example demonstrates how to implement metered billing using the Android AppsConnector method.

Account account = CloverAccount.getAccount(this);

final AppsConnector appsConnector = new AppsConnector(this, account);

new AsyncTask<Void, Void, Void>() {
  @Override protected Void doInBackground(Void[] params) {
    try {
      appsConnector.logMetered("{meteredID}", 1);
      return null;
    }
    catch (Exception e) {
      e.printStackTrace();
    }
    return null;
  }
}.execute();

At the end of the month, Clover uses the events your app captured and generates the merchant's statement. The merchant can see their statements from the Merchant Dashboard.

Get a merchant's billing information

Planning for app billing ahead of time can help you handle various scenarios that occur in real time with merchant accounts and payments.

You can track information about how your merchants are using your apps using the billing_info REST API endpoint. You can query for:

• A merchant's current subscription tier
• The start time, if the merchant is using a free trial period in their subscription
• The merchant account status: Active, Lapsed, Inactive, or Suppressed.

GET {baseURL}/v3/apps/{aId}/merchants/{mId}/billing_info

Merchant account statuses

Android AppsConnector Method
Use the Android AppsConnector method for obtaining merchant billing information getAppBillingInfo().

Android Example
The following snippet demonstrates how to obtain merchant billing information with the getAppBillingInfo() method.

Account account = CloverAccount.getAccount(this);

final AppsConnector appsConnector = new AppsConnector(this, account);

new AsyncTask<Void, Void, AppBillingInfo>() {
  @Override protected AppBillingInfo doInBackground(Void[] params) {
    try {
      return appsConnector.getAppBillingInfo();
    }
    catch (Exception e) {
      e.printStackTrace();
    } 
    return null;
  }
}.execute();

Track daysLapsed for merchant accounts

Get the number of days since the merchant was in the Inactive, Lapsed, or Suppressed statuses. Use the daysLapsed field in the getAppBillingInfo() method.

Get daysLapsed for Inactive, Suppressed, and Lapsed accounts

The following snippet demonstrates how to get the number of days lapsed since a merchant account that was Inactive.

curl -s "{baseUrl}/v3/apps/{appId}/merchants/{mId}/billing_info" -X GET --header "Bearer {authToken}"

In response, you get the subscription tier details, account status, number of days lapsed, and the billing start time.

{
    "appSubscription": {
        "active": true,
        "amount": 500,
        "app": {
            "id": "X5JY8W311JK3P"
        },
        "description": "Professional tier $10 per month",
        "id": "KKG7Z36JJHSH4",
        "label": "Pro $10 per month",
        "name": "Pro $10 per month",
        "plan": false,
        "subscriptionCountries": {
            "elements": [
                {
                    "active": true,
                    "amount": 500,
                    "appSubscription": {
                        "id": "KKG7Z36JJHSH4"
                    },
                    "country": "US",
                    "description": "5",
                    "id": "5HSK5TYSPKXD3",
                    "name": "Pro $10 per month"
                }
            ]
        }
    },
    "billingStartTime": 1571247887000,
    "isInTrial": false,
    "status": "INACTIVE",
    "daysLapsed": 232
}

Get Active account status

The following snippet demonstrates the response for a merchant account in the Active status.

{
    "appSubscription": {
        "active": true,
        "amount": 500,
        "app": {
            "id": "X5JY8W311JK3P"
        },
        "description": "Professional tier $10 per month",
        "id": "KKG7Z36JJHSH4",
        "label": "Pro $10 per month",
        "name": "Pro $10 per month",
        "plan": false,
        "subscriptionCountries": {
            "elements": [
                {
                    "active": true,
                    "amount": 500,
                    "appSubscription": {
                        "id": "KKG7Z36JJHSH4"
                    },
                    "country": "US",
                    "description": "5",
                    "id": "5HSK5TYSPKXD3",
                    "name": "Pro $10 per month"
                }
            ]
        }
    },
    "billingStartTime": 1571247887000,
    "isInTrial": false,
    "status": "ACTIVE",
    "daysLapsed": 0
}

See Using Clover REST API and the API Reference for more information.

Handling merchant payment delays

You can use the merchant account status to stop billing merchants in the Inactive, Lapsed, or Suppressed statuses and cut off incurred charges for that merchant. When the merchant account is reinstated, billing resumes as usual.

Deactivating and reactivating merchants

Clover removes deactivated merchants periodically to ensure accurate billing by:

• Stopping billing and marking the merchant as non-billable
• Uninstalling paid apps
• Notifying them through email

The billing_info endpoint returns the Inactive status for these merchants.

When a merchant reactivates their account, Clover reopens their account, changes the merchant to billable, and notifies them through email. Merchants can then resume App Market services and reinstall apps or continue purchases for new apps.

The billing_info endpoint returns the Active status for these merchants.

You can view merchant install information on the Installs page of your app.

Track billable merchants

Billable merchants have active accounts with Clover that are not test or demo accounts or are not suppressed. You can track billable and non-billable merchants on the Installs page of your app.

Use the following endpoint to determine whether a merchant is billable. The isBillable property values are returned with:
GET {baseURL}/v3/merchants/{mId}?expand=gateway

Using the expand=gateway parameter prevents the isBillable field from returning as null. If isBillable is true, the merchant is a live, billable merchant.

See the REST API Reference and Using Clover REST API for more information.

After publishing your apps, you can track revenue generated by your apps. Learn about the billing lifecycle to understand your statements and track refunds.

Promote your apps using targeted links

After you've set up your subscription tiers, you can promote your app tiers by sending merchants to your app using a link that pre-selects a given subscription level. You can showcase subscription tier benefits to merchants who're logged in.

To get a direct link to a tier, add the subscriptionId={SUBSCRIPTION_ID} query parameter to the App Market URL.

{regionalCloverHost}/appmarket/apps/[APP_ID]?subscriptionId=[SUBSCRIPTION_ID]

The {regionalCloverHost} can be one of the following:

• clover.com
• eu.clover.com
• la.clover.com

You can also launch a subscription page from an Android app. For more information, see our sample code. You can also see the full example.

👍

TIP

When using targeted links, provide the public URL for your app to merchants.