Set data permission for your app

When building an app, you need to configure the necessary settings and permissions to access merchant data. Upon installation, merchants approve the permissions your app requests. Some permissions grant access to Personal Identifiable Information (PII), which is protected by national and international laws. Additional restrictions may apply in special cases—for example, the General Data Protection Regulation (GDPR) in Europe protects customer data, and Health Insurance Portability and Accountability Act (HIPPA) in the U.S. restricts access to personal healthcare data.

In production, to get your app approved for Clover devices, you must justify each requested permission. Provide clear, in-line explanations of how your app uses each one. The Developer Relations (DevRel) team reviews this information during the app approval process to ensure only relevant permissions are requested and used.

Before you begin

Based on your app’s functionality, you must request specific data permissions from merchants. Before setting or updating these permissions, keep the following in mind:

• Understand the merchant’s Clover plan, as it determines available app features. For example, Payments Plus merchants cannot access Items or Orders. Request permissions aligned with the plans you support.
• Limit permissions to those essential for your app’s core functionality. This helps:
  • Support PCI-DSS compliance, especially when handling PII, whether directly or incidentally.
  • Simplify the app approval process.
  • Broaden your app’s availability across more merchants.
• If you update permissions after installation, merchants (including test merchants) must uninstall and reinstall the app for changes to take effect. For Android app permission settings to take effect:
  • Clover must approve your APK.
  • Merchant must uninstall and reinstall the app on the Clover device.
  • Clover generates a new APK token after installation.

Understand permissions mapping

The Clover REST API organizes endpoints by data categories such as inventory, orders, and merchants. Each category corresponds to either Read or Write permissions:

• Read permission—Required for retrieving data.
  Example: Accessing GET /v3/merchants/{mId}/employees needs the Read Employees permission.
• Write permission—Required for creating, updating, or deleting data.
  Example: Using POST /v3/merchants/{mId}/employees/{empId} requires the Write Employees permission.

Use case example—A loyalty and reporting app that tracks best-selling items primarily needs Read permissions. It doesn’t require access to employees, payments, or ecommerce data. Minimal Read permissions for Customers, Inventory, Merchant, and Orders are sufficient.

Permissions justification examples

• Customer Read—To associate orders with specific customers to apply loyalty rewards accurately. The app may also display a customer’s name and their list of qualifying items upon request.
  Uses: CustomerConnector.getCustomers(), Customer.getOrders(), Customer.getFirstName()
• Inventory Read—To monitor item sales performance and determine if line items qualify for rewards, such as a free drink after purchasing 10. Uses: InventoryConnector.getItemWithCategories()
• Merchant Read—To retrieve the merchant’s support email address for customer service or troubleshooting purposes. Uses: MerchantConnector.getMerchant(), Merchant.getSupportEmail()
• Orders Read—To check whether orders contain line items that qualify for rewards. Uses:
  OrderConnector.getOrder(), Order.getLineItems()
• Orders Write—If an order qualifies for a reward, apply a discount before payment. Uses:
  OrderConnector.addDiscount()

Customer permissions

Click to view Customer permissions and sample REST API calls

Permissions	Sample REST API calls: Operation	Description
Read customers Required to read customer information.	GET /v3/merchants/{mId}/customers	Retrieves all customers' information.
	GET /v3/merchants/{mId}/customers/{customerId}	Retrieves information for a customer.
Write customers Required to add and update customer information.	POST /v3/merchants/{mId}/customers/{customerId}	Update the information of a customer.
	DELETE /v3/merchants/{mId}/customers/{customerId}	Deletes a customer record.

Employee permissions

Click to view Employee permissions and sample REST API calls

Permissions	Sample REST API calls: Operation	Description
Read employees Required to read employee information, for example, to view who created an order.	GET /v3/merchants/{mId}/employees	Retrieves all employees' information.
	GET /v3/merchants/{mId}/employees/{empId}/shifts	Retrieves all shift information of an employee.
Write employees Required to add and update employees.	POST /v3/merchants/{mId}/employees/{empId}/shifts	Creates a shift for an employee.
	DELETE /v3/merchants/{mId}/employees/{empId}	Deletes an employee record.

Inventory permissions

Click to view Inventory permissions and sample REST API calls

Permissions	Sample REST API calls: Operation	Description
Read inventory Required to read inventory.	GET /v3/merchants/{mId}/inventory/items	Retrieves all items in a merchant's inventory.
	GET /v3/merchants/{mId}/inventory/categories	Retrieves all categories and the number of items in each category.
	GET /v3/merchants/{mId}/inventory/discounts	Retrieves all custom discounts.
	GET /v3/merchants/{mId}/inventory/modifiers/groups\	Retrieves all modifier groups.
Write inventory Required to add and update inventory.	POST /v3/merchants/{mId}/items	Adds a list item to an inventory.
	POST /v3/merchants/{mId}/inventory/items/{itemId}	Updates a list item.
	DELETE /v3/merchants/{mId}/categories/{categoryId}	Deletes a category.

Merchant permissions

Click to view Merchant permissions and sample REST API calls

Permissions	Sample REST API calls: Operation	Description
Read merchant Required to read merchant properties, for example, to view basic information for a merchant.	GET /v3/merchants/{mId}/tip_suggestions	Retrieves all tip suggestions for a merchant.
	GET /v3/merchants/{mId}/address	Retrieves a merchant address.
Write merchant Required to update merchant properties.	DELETE /v3/merchants/{mId}/order_types/{orderTypeId}	Deletes an order type.
	POST v3/merchants/{mId}/properties	Updates a merchant's properties.

Order permissions

Click to view Order permissions and sample REST API calls

Permissions	Sample REST API calls: Operation	Description
Read order Required to read order information.	GET /v3/merchants/{mId}/orders	Retrieves all orders.
	GET /v3/merchants/{mId}/orders/{orderId}?expand=customers	Retrieves customers for an order.
Write order Required to add and update an order.	POST /v3/merchants/{mId}/orders/{orderId}/line_items	Adds a new line item to an order.
	POST /v3/merchants/{mId}/orders/{orderId}\	Adds a new order

Payments permissions

Click to view Payments permissions and sample REST API calls

Permissions	Sample REST API calls: Operation	Description
Read payments Required to read payment information.	GET /v3/merchants/{mId}/orders/{orderId}/payments	Retrieves the payment summary for an order.
	GET /v3/merchants/{mId}/payments/{paymentId}	Retrieves a single payment.
Write payments Required to add and update payment records.	POST /v3/merchants/{mId}/orders/{orderId}/payments	Adds payment data to an order.

Ecommerce API permissions

Click to view Ecommerce API permissions and sample REST API calls

Permissions	Sample Ecommerce API calls: Operation	Description
Use for Clover apps providing card-not-present payments. See Ecommerce app permissions for more information about permissions required for using the Ecommerce API.	POST /v2/merchant/{mId}/pay	Processes a credit card payment.

---

View or set up app permissions

1. Log in to the Global Developer Dashboard.
2. Click the Sandbox toggle icon to go to either the sandbox or the production environment.
3. Do one of the following:

• Click Create new app and complete the initial setup.
• In the My Apps section, click an app.
  The App name - App Settings page appears. Here, you can view and configure the settings and permissions that your app requires to access merchant data.

4. Click Requested Permissions. The Edit Requested Permission page appears.
5. 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. For apps for Europe, additional fields display in the Customer permissions section to comply with GDPR. For more information, see Customers API permissions in Europe.
6. Click Save. Your selected permissions display on the App Settings page.

Use app API token to request for merchant data

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

• Android apps(—)Query web services and generate a token using Clover Android SDK.
• Web apps(—)Use OAuth 2.0 to generate an API token.
• Test apps(—)Generate an API token on the Test Merchant Dashboard.

---

Healthcare merchants and Clover support for HIPAA

Limited app permissions for healthcare merchants

Due to Health Insurance Portability and Accountability Act (HIPAA) requirements, Clover restricts healthcare merchants in specific categories from installing apps that require Read or Write permissions for customers or inventory. When merchants from any of these categories try to install apps from the Clover App Market requiring these permissions, a banner notification displays. The Install button is also not available for these apps.

Restricted merchant category codes (MCCs) for HIPPA compliance:

Scope of Clover HIPAA support

Clover uses merchant category codes (MCCs) to categorize merchants as healthcare merchants. These merchants must comply with HIPAA. Healthcare merchants can use Clover for Healthcare without requiring Clover to sign a HIPAA Business Associate Agreement.

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