Platform Docs

Setting app permissions

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

IMPORTANT

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.

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

A new API token is generated when a new APK is approved and installed or when a Clover merchant uninstalls and reinstalls your app.

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 App Market Submission Form 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.

Setting app permissions

To view the 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.
  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.

For your Android app, generate an API token using Clover Android SDK. For your web app, generate an API token using OAuth 2.0.

Only for testing purposes, you can generate an API token using the Merchant Dashboard.

NOTE

If you change app permissions after a merchant (including your test merchant) has downloaded the app, 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


Setting 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.