Clover REST API Basics with Postman

The Clover REST API allows apps and services to interact with Clover. However, you don’t need to build a complete web app to test out our REST API.

New to Clover’s REST API? Or want a refresher? Follow along as we demonstrate the basics of making Clover API requests with a little help from Postman, an API platform for building and using APIs.

Prerequisites

Before you can make API requests, you’ll need the following:

Postman

Download it for free or create an account to use Postman in a browser. There are other apps that offer similar functionality, but instructions in this tutorial use Postman.

Clover Sandbox account

Sign up for a free Sandbox developer account if you don’t have one yet. You will also create a test merchant connected to your account during this process.

Clover Sandbox app

See our instructions on how to set up a basic app. Your app should:

• Support Web as an App Type.
• Request at least the following Permissions:
  — Inventory Read and Write (R/W)
  — Orders R/W
  — Payments R/W
  — Merchant R
  — Customers R
  — Ecommerce
• Include a Site URL as part of the app’s REST Configuration. The particular link depends on your preferred Postman workspace:
  — For Postman on the Desktop, use: https://www.postman.com/oauth2/callback
  — For Postman on the web, use: https://oauth.pstmn.io/v1/browser-callback
• Be installed to your test merchant.

Import the Clover API Tutorial collection

Open your Postman workspace. To import Clover’s example Postman collection:

1. Download the Clover REST API Tutorial collection JSON
2. Under the Collections tab, select the Import button
3. Choose your downloaded JSON file
4. Confirm the import

Import a Postman collection by uploading a JSON file

This collection uses a matching environment. Importing the environment is similar to importing a collection:

1. Download the Clover Tutorial Environment JSON file
2. Under the Environments tab, select the Import button
3. Choose your downloaded JSON
4. Confirm the import

Postman will recognize a valid JSON file as a “Postman Collection” or “Postman Environment” format

Your workspace should now include:

• Collections > Clover REST API Tutorial, and
• Environments > Clover Tutorial Environment

Configure your Postman environment

The Clover tutorial collection comes with an environment template. You need to fill out a few details to get started.

Finish setting up the Clover Tutorial Environment

1. Click the Environments tab on the left navigation menu.
2. Select the Clover Tutorial Environment.
3. If this isn’t your active environment, do one of the following:
   — Select the checkmark next to its name to set it as Active
   — Select Clover Tutorial Environment from the Environments dropdown list
4. The base URL variables are already filled out:
   — baseUrl: Since we’re testing in Sandbox, the base URL for all of our requests is https://sandbox.dev.clover.com
   — ecommBaseUrl: We’ll use an Ecommerce endpoint to demonstrate paying for an order. Note that Clover Ecommerce requests use a slightly different base URL: https://scl-sandbox.dev.clover.com
5. Add a Current Value to the following variables:
   — appId: Your app’s 13-character ID
   — appSecret: Your app’s secret key
   — mId: Your test merchant’s 13-character ID
   — (The rest of the IDs will be filled in as we go)
6. Make sure to Save your changes.

Generate an OAuth token

To authenticate your API requests, you’ll need to generate an access token. Clover uses the OAuth 2.0 framework for its API access tokens. Here’s how to generate one in Postman.

Get a new access token from Postman’s Authorization tab

1. Click the Collections tab on the left navigation menu.
2. Select the Clover REST API Tutorial collection.
3. Make sure you are viewing the Authorization tab for the collection.
4. Check out the token configuration fields. These should already be filled out after adding values to the appId and appSecret variables in the previous section.
5. Scroll to the bottom of the screen and select Get New Access Token.
6. Log into your Clover account.
7. If you have multiple test merchants, make sure to select the merchant associated with the mId you are using.
8. Click Use Token.

You’re all set to start making Clover API requests!

Create your first order

Orders are often fundamental to the Clover experience. Most Clover objects, including payments, line items, and refunds, must be associated with an order. You will learn how to create an inventory item, create an order for that item, create more complex orders, and then search for your order. The following sections correspond to API requests in the collection.

Create an inventory item

You’ll first create an item for your merchant. Inventory items act as templates; when you add them to an order, the order’s line items inherit relevant details from the inventory item. You will need to provide at least a name and price for your new inventory item.

View the request’s Body tab in Postman for an example.

Adding a new $5.00 Popcorn item to a merchant’s inventory

Review the returned response. In particular, you will reference the item ID later. A post-response script sets this ID as the environment’s itemId variable.

Click the Environment Quick Look button to confirm that the current value of itemId matches the returned item ID.

Note: You’ll notice that the price is set to 500 for this $5.00 item. This is because Clover stores money as integers rather than decimal values to avoid rounding errors. You can find a great explanation why we (and others) do this in this Computerphile video.

Create an order

Clover’s atomic order endpoint requires, at minimum, a line item. This is where your newly-created inventory item comes into play. You only need to reference the relevant item ID and your order will include the item’s name and price. When you submit the order creation request, it will automatically tally item prices, along with any modifications, discounts, and taxes (if set up) for the order total.

1. Note the expected JSON structure in the request’s Body tab.
2. Provide line items as a list, even if there’s only one of them.
3. Enclose everything in an orderCart object.

{
  "orderCart": {
    "lineItems": [
      {
        "item": {
          "id": "{{itemId}}"
        }
      }
    ]
  }
}

Create an order with a discount

You can expand on this basic order structure to create orders with all sorts of variations. This request modifies the order structure to create an order with multiple line items and an order discount.

Similar to items, you can add a discount using the discount ID if you already have one. For this example, however, the body simply specifies a name for the discount and a percentage. You can instead use an amount for a flat discount.

Check out our docs on working with orders for even more variations on building an order request.

View your order

With your order ID in hand, you can quickly retrieve all of the order’s details using our REST API. Expansions provide even more information, such as associated line items and discounts.

If you’re following along, Postman has set your most recent order as the current orderId. If you want to review details on both of your previous orders, you can retrieve multiple orders using the GET {{baseUrl}}/v3/merchants/{{mId}}/orders endpoint instead.

Add a gift card payment to an order

Now that you’re comfortable with creating orders, how about closing them out?

Most of the time, orders are paid for in person or using Clover’s Ecommerce API. To get a taste of using the Ecommerce API without all the encryption, you can pay for an order with a gift card tender instead of a credit card. Ecommerce’s Pay for an order endpoint closes out your order, automatically paying for the full order total by default.

Check out the documentation on each request in the Postman collection for a step-by-step guide through this process.

Add a payment to your order

To explore implementing a full payment solution, learn more about our Ecommerce API for card-not-present (CNP) payments or our REST Pay API for card-present (CP) payments.

Additional API operations

Advanced query operations allow for greater control of response results when making requests. For merchants with large amounts of orders, payments, or inventory items, efficient queries are important to reduce the number of API calls and improve response time. This means your app will be more responsive and less likely to be rate limited.

Explore filters and other query parameters available for Clover APIs

The Additional V3 API Operations section of the Postman collection demonstrates how to perform the following operations:

• Expanding fields
• Filtering by modifiedTime
• Applying multiple filters
• Sorting collections
• Displaying null fields
• Paging through results

What’s next

Now that you’ve nailed the basics, you can use your newfound skills to create your own app for our Clover App Market. For additional information, be sure to check out our Developer Docs, REST API Reference, and tutorial videos.