Handle app billing

United States
Canada
Europe

The Clover billing system lets you charge for paid apps in specific regions. To learn more about app pricing options, see Monetize your apps. You need to add bank account details to your verified Clover developer account to receive disbursements from Clover. See Add or update bank account information.

Understand app billing

For metered events

Metered billing is performed in arrears (pay after use) based on the number of merchant events that occurred during the prior month. An event occurs when a merchant uses a metered feature in your app. The price is set per event, for example, $1 per event, so if the merchant uses a feature ten times during the month, they get a $10 charge.

Your app:

  • Can have more than one event type, with a price assigned to each event type; for example, a gift card app can charge a $10 event to ship physical gift card blanks to the merchant, with an additional $0.05 charge per $2 of gift card value when issuing a gift card.
  • Can set subscription pricing in one country and metered event pricing in another country.
  • Must call a Clover API to record when an event occurred. If your merchant uses metered billing, you must track the merchant events and post the metered identifiers (IDs) to Clover using the metereds endpoint. See REST API example.

At the end of the month, Clover:

  • Calculates how much a merchant must be charged for the metered events.
  • Generates the merchant's statement, which is available on the Merchant Dashboard.

Charge for metered events = Total number of events for a pricing tier * price set on a pricing tier for a country

For subscriptions

Subscription billing is performed in advance (pay before use) based on the monthly subscription price, and the charges are prorated at a daily time limit. Merchants are billed to pre-pay subscriptions for the apps they have installed on the 1st of the month. App billing adjustments are made daily for new app installs, uninstalls, subscription upgrades, and subscription downgrade events made the previous day.

Your subscription-based app:

  • Can have a single monthly price or monthly subscription.
  • Can have multiple subscription tiers with different features at different price points.

Prorated charge for subscriptions = Number of days remaining in current month * Subscription price / number of days in current month

For more information, see:

Understand and track merchant account status

Account statusUnited States featuresEuropean region differences
ActiveActive merchant account.
LapsedMerchant account with an ACH Reject status. The subsequent charges in the month change to the Incurred charge status. You get paid for charges in the ACH Reject status.Charges after the first ACH reject continue to be In Progress charge status.
SuppressedMerchant account that is suppressed and marked non-billable. Suppressed status stops the merchant from incurring further charges on their account. Suppressed merchant accounts include:

- Demo merchant
- Test merchant
- Merchant is in a country that is in pilot
- Merchant from which Clover can't collect payments
Suppressed account feature is not available. Merchants who are not paying are deactivated, and their status is set to Inactive.
InactiveMerchant account deactivated and apps uninstalled. Merchant is inactive and non-billable.

Track billable merchants

Billable merchants have active accounts with Clover. These are not test, demo, or suppressed accounts. You can:

  • Track billable and non-billable merchants on your app's Installs page.
  • Use the GET {baseURL}/v3/merchants/{mId}?expand=gateway endpoint to determine whether a merchant is billable. The response contains the property value: isBillable.
  • Use the expand=gateway parameter to prevent the isBillable field from returning as null. If isBillable is true; the merchant is active and billable.

Get a merchant's billing information

Plan for app billing ahead of time to handle various scenarios that occur in real-time with merchant accounts and payments.

REST API endpoint

Use billing_info to track information about how your merchants use your apps. See Get merchant app billing information.

REST API example

Use the GET {baseURL}/v3/apps/{aId}/merchants/{mId}/billing_info to retrieve:

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

Android AppsConnector method

Use the getAppBillingInfo() method to get the merchant billing information.

Android example

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 daysLapsed for Inactive, Suppressed, and Lapsed accounts

REST API example

To retrieve the number of days lapsed since a merchant account was Inactive. See Get merchant app billing information.

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
}

Android AppsConnector method

Use the daysLapsed field in the getAppBillingInfo() method to get the days since the merchant was Inactive, Lapsed, or Suppressed.

Get Active account status

Example of the response for an Active merchant account.

{
    "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
}

Handle merchant payment delays

Use the merchant account status to stop billing merchants that are Inactive, Lapsed, or Suppressed and cut off incurred charges for that merchant. When the merchant account is reinstated, billing resumes as usual.

Work with deactivated and reactivated merchants

Deactivated merchant account

For accurate billing, Clover removes deactivated merchants periodically and:

  • Stops billing and marks the merchant as non-billable.
  • Uninstalls paid apps.
  • Notifies the merchant through email.

Reactivated merchant account

When a merchant reactivates their account, Clover:

  • Reopens their account.
  • Changes the merchant to billable.
  • Notifies the merchant through email.

Merchants can then resume Clover App Market services and reinstall apps or continue purchases for new apps.

For more information:

Track metered events

You can create and view each pricing tier with a single Metered ID on the Developer Dashboard. Select Your Apps > _app name_ > Pricing & Distribution. See Set up pricing tiers.

REST API endpoint

Use the Apps REST API endpoint. See Get an app billing metered event.

REST API example

Use metereds:

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

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();

Promote your apps after setting up subscription tiers

After you've set up your subscription tiers, you can promote your app tiers with targeted links or a subscription page.

Redirect link

Use a link to direct merchants to your app with a preselected subscription level. You can showcase the subscription tier benefits to logged-in merchants.

To get a direct link to a subscription tier, add the subscriptionId={SUBSCRIPTION_ID} query parameter to the Clover App Market link (URL). When using targeted links, provide the public URL for your app to merchants.

Example:

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

The {regionalCloverHost} can be one of the following:

Subscription page

You can also launch a subscription page from an Android app. For more information, see: