Platform Docs

App Permissions

Overview

Depending on the features of 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. You should only request the permissions your app needs.

Justifications are required for permissions

Some permission sets control access to data containing personally identifiable information (PII). PII is protected by national or international law or regulation, so developers must justify their request for permissions before an app will be approved for installation on Clover devices. Complete the Personally Identifiable Information Checklist for each app you want to publish to the Clover App Market. The Developer Relations team will use this form during the app approval process to ensure only needed permissions are requested and used by your app.

Viewing current permissions

  1. On your app's Settings page on the Developer Dashboard, review the permissions scheme under Required Permissions.

Setting permissions

  1. On your app's Settings page on the Developer Dashboard, select Required Permissions.
  2. On the Permissions page, select the permissions needed for your app.
  3. Select Save.

NOTE

If you change app permissions after a merchant (including your test merchant) has downloaded it, the new permission scheme will not take effect until the merchant uninstalls and reinstalls the app.

Understanding permissions mapping

The Clover 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 two permissions: a read permission and a write permission. Actions that retrieve data from an endpoint require the merchant to grant your app the read permission (_R). Actions that create, update, or delete merchant data require the write permission (_W).

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

Available permissions

The following permissions are available on the Clover platform.

CUSTOMERS_R

CUSTOMERS_R is required to read customer data.

Sample REST API Calls for CUSTOMERS_R

HTTP method
Endpoint
Description

GET

/v3/merchants/{mId}/customers

Returns a list of customer summaries

GET

/v3/merchants/{mId}/customers/{customerId}

Returns a Customer object

CUSTOMERS_W

CUSTOMERS_W is required to add and update customer data.

Sample REST API Calls for CUSTOMERS_W

HTTP method
Endpoint
Description

POST

/v3/merchants/{mId}/customers/{customerId}

Updates a customer

DELETE

/v3/merchants/{mId}/customers/{customerId}/phone_numbers/{phoneId}

Deletes a customer's phone number

EMPLOYEES_R

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

Sample REST API Calls for EMPLOYEES_R

HTTP method
Endpoint
Description

GET

/v3/merchants/{mId}/employees

Lists all employees

GET

/v3/merchants/{mId}/employees/{empId}/shifts

Gets all shifts for an employee

EMPLOYEES_W

EMPLOYEES_W is required to add and update employees.

Sample REST API Calls for EMPLOYEES_W

HTTP method
Endpoint
Description

POST

/v3/merchants/{mId}/employees/{empId}/shifts

Creates a shift for an employee

DELETE

/v3/merchants/{mId}/employees/{empId}

Deletes an employee

INVENTORY_R

INVENTORY_R is required to read inventory.

Sample REST API Calls for INVENTORY_R

HTTP method
Endpoint
Description

GET

/v3/merchants/{mId}/inventory/items

Lists all items in the merchant's inventory

GET

/v3/merchants/{mId}/inventory/categories

Lists all categories and the number of items in each category

GET

/v3/merchants/{mId}/inventory/discounts

Returns a list of custom discounts

GET

/v3/merchants/{mId}/inventory/modifiers/groups

Lists all modifier groups

INVENTORY_W

INVENTORY_W is required to add and update inventory.

Sample REST API Calls for INVENTORY_W

HTTP method
Endpoint
Description

POST

/v3/merchants/{mId}/items

Adds an item to the inventory

POST

/v3/merchants/{mId}/inventory/items/{itemId}

Updates an item

DELETE

/v3/merchants/{mId}/categories/{categoryId}

Deletes a category

MERCHANT_R

MERCHANT_R 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 for MERCHANT_R

HTTP method
Endpoint
Description

GET

/v3/merchants/{mId}/tip_suggestions

Gets all tip suggestions for a merchant

GET

/v3/merchants/{mId}/address

Gets a merchant's address

MERCHANT_W

MERCHANT_W is required to update merchant properties.

Sample REST API Calls for MERCHANT_W

HTTP method
Endpoint
Description

DELETE

/v3/merchants/{mId}/order_types/{orderTypeId}

Deletes an order type

POST

/v3/merchants/{mId}/properties

Updates a merchant's settings

ORDERS_R

ORDERS_R is required to read orders.

Sample REST API Calls for ORDERS_R

HTTP method
Endpoint
Description

GET

/v3/merchants/{mId}/orders

Returns a list of orders

GET

/v3/merchants/{mId}/orders/{orderId}?expand=customers

Gets the customer(s) for an order

ORDERS_W

ORDERS_W is required to add and update orders.

Sample REST API Calls for ORDERS_W

HTTP method
Endpoint
Description

POST

/v3/merchants/{mId}/orders/{orderId}/line_items

Adds a new line item to orders

POST

/v3/merchants/{mId}/orders/{orderId}

Adds a new order

PAYMENTS_R

PAYMENTS_R is required to read payments.

Sample REST API Calls for PAYMENTS_R

HTTP method
Endpoint
Description

GET

/v3/merchants/{mId}/orders/{orderId}/payments

Gets the summary of the payments made for an order

GET

/v3/merchants/{mId}/payments/{paymentId}

Returns a single Payment object

PAYMENTS_W

PAYMENTS_W is required to add and update payment records.

Sample REST API Calls for PAYMENTS_W

HTTP method
Endpoint
Description

POST

/v3/merchants/{mId}/orders/{orderId}/payments

Adds payment data to an order

PROCESS_CARD

PROCESS_CARD is required to process credit card payments. This can only be used for apps used by merchants in the US region (see Developer Pay API for more information).

NOTE

PAYMENTS_W must also be enabled to process payments using the Pay API.

Sample REST API Calls for PROCESS_CARD

HTTP method
Endpoint
Description

POST

/v2/merchant/{mId}/pay

Processes a credit card payment


App Permissions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.