Set app permissions

United States
Canada
Europe
Latin America

Watch Webinar

Review Clover's webinar on data minimization in the app permissions process. Here’s what you will learn in the webinar:

  • The significance of permissions in the app-making process
  • What is PII? How does PII relate to data minimization?
  • Tips for trimming unnecessary permissions

You can view or download the webinar slides here.

Based on the features you are building in your app, you will require a specific set of data permissions from merchants. When a merchant installs your app, they approve the permissions your app is requesting.

🚧

IMPORTANT

You must only request the permissions your app needs.

If you change app permissions after a merchant (including your test merchant) downloads your app, the new permissions don't take effect until the merchant uninstalls and reinstalls the app.

Clover generates a new APK token:

  • After approving your new APK
  • When a merchant uninstalls and reinstalls your app

📘

NOTE

For any of your Android app permission settings to take effect, your app's APK must be approved and a Clover merchant must install your app on their Clover device.

Provide permission justifications

Certain permission sets control access to data containing Personally Identifiable Information (PII). PII is protected by national or international law and regulations. Hence, you must justify why you requested for those specific permissions before Clover approves your app for installation on Clover devices.

While setting your app permissions, provide in-line justifications about how your app is using this information. The Developer Relations team uses this information during the app approval process to ensure only relevant permissions are requested and used by your app.

Set up app permissions

To view or set app permissions for your app:

  1. On the Developer Dashboard, click App Settings on the side-nav.
  2. On the App Settings page, click Requested Permissions.
  3. On the Edit Requested Permissions modal that appears, select your app's READ or WRITE permissions for each REST API endpoint as required. For any selected permission, provide a clear justification for how your app is using this information.
  4. Click Save. Your selected permissions appear on the App Settings page.

Based on the permissions you set, you can use your app's API token to request for Clover merchant data:

Understand permissions mapping

Clover's REST API is divided into categories of data such as inventory, orders, and merchants. Each category of endpoints in the Clover REST API corresponds to either a Read or Write permission.

Actions that retrieve data from an endpoint require the merchant to grant your app the Read permission. Actions that create, update, or delete merchant data require the Write permission.

For example, if your app retrieves data from the GET /v3/merchants/{mId}/employees endpoint, your app must have the Read employees permission granted by the merchant. If your app modifies information about a merchant's employees using POST /v3/merchants/{mId}/employees/{empId}, the Write employees permission is required.

Read customers

The Read customers permission is required to read customer data.

Sample REST API calls

OperationDescription
GET /v3/merchants/{mId}/customersList all customers
GET /v3/merchants/{mId}/customers/{customerId}Retrieve the specified customer

Write customers

The Write customers permission is required to add and update customer data.

Sample REST API calls

OperationDescription
POST /v3/merchants/{mId}/customers/{customerId}Update the specified customer
DELETE /v3/merchants/{mId}/customers/{customerId}Delete the specified customer

Read employees

The Read employees permission is required to read employees. If you want to see who created an order, you'll need this permission.

Sample REST API calls

OperationDescription
GET /v3/merchants/{mId}/employeesList all employees
GET /v3/merchants/{mId}/employees/{empId}/shiftsRetrieve all shifts of the specified employee

Write employees

The Write employees permission is required to add and update employees.

Sample REST API calls

OperationDescription
POST /v3/merchants/{mId}/employees/{empId}/shiftsCreate a shift for the specified employee
DELETE /v3/merchants/{mId}/employees/{empId}Delete the specified employee

Read inventory

The Read inventory permission is required to read inventory.

Sample REST API calls

OperationDescription
GET /v3/merchants/{mId}/inventory/itemsList all items in the merchant's inventory
GET /v3/merchants/{mId}/inventory/categoriesList all categories and the number of items in each category
GET /v3/merchants/{mId}/inventory/discountsList all custom discounts
GET /v3/merchants/{mId}/inventory/modifiers/groupsList all modifier groups

Write inventory

The Write inventory permission is required to add and update inventory.

Sample REST API calls

OperationDescription
POST /v3/merchants/{mId}/itemsAdd a list item to the inventory
POST /v3/merchants/{mId}/inventory/items/{itemId}Update the specified list item
DELETE /v3/merchants/{mId}/categories/{categoryId}Delete the specified category

Read merchants

The Read merchants permission is required to read merchant properties. If you want to see basic information about a merchant, you'll need this permission.

Sample REST API calls

OperationDescription
GET /v3/merchants/{mId}/tip_suggestionsList all tip suggestions for a merchant
GET /v3/merchants/{mId}/addressList the specified merchant's address

Write merchants

The Write merchants permission is required to update merchant properties.

Sample REST API calls

OperationDescription
DELETE /v3/merchants/{mId}/order_types/{orderTypeId}Delete the specified order type
POST /v3/merchants/{mId}/propertiesUpdate the specified merchant's properties

Read orders

The Read orders permission is required to read orders.

Sample REST API calls

OperationDescription
GET /v3/merchants/{mId}/ordersList all orders
GET /v3/merchants/{mId}/orders/{orderId}?expand=customersRetrieve the customer(s) for an order

Write orders

The Write orders permission is required to add and update orders.

Sample REST API calls

OperationDescription
POST /v3/merchants/{mId}/orders/{orderId}/line_itemsAdd a new line item to an order
POST /v3/merchants/{mId}/orders/{orderId}Add a new order

Read payments

The Read payments permission is required to read payments.

Sample REST API calls

OperationDescription
GET /v3/merchants/{mId}/orders/{orderId}/paymentsRetrieve the payment summary for an order
GET /v3/merchants/{mId}/payments/{paymentId}Retrieve a single payment

Write payments

The Write payments permission is required to add and update payment records.

Sample REST API call

OperationDescription
POST /v3/merchants/{mId}/orders/{orderId}/paymentsAdd payment data to an order

Ecommerce API permissions

📘

NOTE

New Clover apps providing card-not-present payments should use the Ecommerce API. The Ecommerce API is currently available in US and Canada. We will continue expanding availability to other regions.

See Ecommerce app permissions for more information about permissions required for using the Ecommerce API.

Sample REST API call

OperationDescription
POST /v2/merchant/{mId}/payProcesses a credit card payment

Limited app permissions for Healthcare merchants

Due to HIPAA requirements Clover restricts merchants in the following categories from installing apps that require read or write permissions for customers or inventory. Review this table to see the Merchant Category Codes (MCC) and their descriptions.

MCC CodeMCC Description
4119Ambulance
5975Hearing Aids
5976Orthopedic Goods Artificial Limbs
5912Pharmacies or Drug Stores
8011Doctors and Physicians (Not Classified Elsewhere)
8021Dentists and Orthodontists
8031Osteopaths
8041Chiropractors
8042Optometrists and Ophthalmologists
8043Opticians, Opticians Goods and Eyeglasses
8049Podiatrists and Chiropodists
8050Nursing and Personal Care Facilities
8062Hospitals
8071Medical and Dental Laboratories
8099Medical Services and Health Practitioners (Not Classified Elsewhere)

Merchants will not see the Install button for such apps on Clover's App Market. If a merchant attempts to install an app that requires these permissions, they will be notified with a banner on Clover's App Market.

Scope of Clover HIPAA support

Clover uses MCCs to categorize merchants as healthcare merchants. These merchants must comply with HIPAA.

  • Clover for Healthcare is HIPAA exempt.
  • Clover for Healthcare takes advantage of a transaction-processing exemption within HIPAA and is HIPAA exempt.
  • HIPAA rules exempt financial institutions from HIPAA, to the extent that protected healthcare information is used solely for processing payments for healthcare. Clover for Healthcare is designed to limit PHI use to payment processing only.

🚧

IMPORTANT

Healthcare merchants can use Clover for Healthcare without requiring Clover to sign a HIPAA Business Associate Agreement.