Welcome to the Clover platform REST API Reference. This reference describes the function of each REST API endpoint in the sandbox environment.

Before you begin

• See Get started to learn about the type of Clover integrations.
• See Use Clover developer environments to learn about the different Clover environments, developer dashboards, and setting up your developer account.
• See Generate a merchant-specific test API token for information on retrieving your first API token. The API token provides the necessary permissions to access test merchant data.
• Learn about API tokens and keys in our blog post Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys.

Sandbox base URLs

Use the Android emulator or Developer Kits in the sandbox environment for building and testing your apps with test merchants. In the sandbox environment, Clover provides base URLs for different services:

Production base URLs

In the production environment, Clover provides base URLs for different services in supported markets.

Use the API Reference

Prerequisites

To use the Clover platform API, you require the following:

• Sandbox developer account
• Test merchant account
• Test API token with permissions to make REST API requests and manage your test merchant's data.

Make a sample REST API call

To make a sample REST API call using the Clover API reference:

1. From the Platform API left navigation, select MERCHANTS > Get a single merchant.
2. Set the Authorization header as Bearer token type, and enter the test API token you generated in the sandbox Developer Dashboard.
3. In the Path Params section, enter your test merchantId in the mId field. Your test merchant ID is a 13-alphanumeric identifier that displays in the browser link (URL) of the Merchant Dashboard for your test merchant. See Locate your test merchant ID.
4. Click Try It. In the JSON output response, the name value is your test merchant’s name.

Sample REST API requests

To test Clover REST APIs:

1. Set the Authorization header as Bearer token type, and enter the auth_token.
2. Include the merchantId in the request URL in place of {mId}.

To retrieve information about your test merchant, send a GET request to /v3/merchants/mId:

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}' \
  --header 'accept: application/json' \  
  --header 'authorization: Bearer {auth_token}'

In this request,

• mId is the test merchant's universally unique identifier (UUID), also known as the merchantId
• auth_token is the test API token or access token. See Use test merchant IDs and API tokens for more information.

To update your test merchant's name, send a POST request to /v3/merchants/mId:

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}' \
  --header 'accept: application/json' \  
  --header 'authorization: Bearer {auth_token}'
  --data '{"name":"{updated_merchant_name}"}'

Set additional query parameters

To retrieve more information from your REST API requests, set query parameters for supported endpoints in the following format.

[Endpoint URI]?field=value[,additionalValues...]&[additionalQueryParameters...]

In the API documentation, the Query Params section lists the additional parameters available. For example, use the expand query parameter for additional information about a merchant.

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}?expand=openingHours' \
  --header 'accept: application/json' \  
  --header 'authorization: Bearer {auth_token}'

See Use expandable fields for more information.