Getting Started with the Clover REST API using Postman
We have a new version of this blog post! Clover has made some improvements to the platform since this article was published. Please check out Clover REST API Basics with Postman instead.
The Clover REST API provides a way for apps and services to interact with Clover. However, you don’t need to build a complete web app to get started playing with our REST API.
This guide is aimed for developers new to the Clover REST API and will demonstrate the basics of making API requests with Postman.
Prerequisites
Before we start making API requests, you’ll need to make sure you have the following:
- A Clover sandbox developer account and test merchant. Sign up for a free sandbox developer account if you don’t have one yet.
- Postman. Download it for free. There are other apps that offer similar functionality, but these instructions will use Postman.
Download and Import the Clover API Tutorial Collection
Download and unzip the clover_api_tutorial.postman_collection.json.zip file. After unzipping, you will need to import it into Postman:
- Click the Import button on the top left of Postman. Alternatively, you can access this from the application menu by selecting Collections and then selecting Import.
- Under Import File, select Choose Files to browse for the clover_api_tutorial.postman_collection.json file.
You should now see the new Collection in Postman.
Set up your Postman environment
- Click the gear icon in the top right-hand corner of Postman.
- Select Manage Environments.
- In the pop-up window, click the Add button.
- In the Environment Name field, enter a name: for example, Clover Test Merchant (Sandbox)
- You’ll need to enter a few key-value pairs in order to use the Clover API Collection you imported.
- Add url : https://apisandbox.dev.clover.com
- Add mId : <your merchant id> (How to find my merchant id)
- Add api_token : <your API token> (How to get a merchant API token for testing and set up permissions. Note: Merchant tokens are ONLY for testing and development.)
- Once you’re done, click Add. You can then exit out of the pop-up window.
- In the environment dropdown menu, make sure you switch from No Environment to your newly created one.
You’re now ready to start making your first Clover API requests!
Creating your first order
Creating orders is fundamental to using the API. Most Clover items, including payments, line items, and refunds, must be associated with an order. You will learn how to create an order, make line items and discounts associated with the order, and then query for your order.
- Create an order
When creating an order, make sure to set the state to open or you won’t see the order show up with the rest of your orders. You can view the body tab to see how to do this. Take note of the order id in the response body; you’ll need to add it to the URL in the next step. - Add a line item to an order
When adding a line item to an order, you can provide a line item id for an inventory item or provide the name/price and a new custom line item will be created. - Add a discount to the order
Order discounts let merchants to offer discounted prices for special promotions or sales. You can provide a discount id for an existing discount the merchant has or create a new discount. - View your order
If you have the order id, you can quickly use our REST API to get the full information about the order. Expansions can show you more info on associated line items and discounts.
Note: Developers should check out our Developer Docs on how to calculate order totals.
Adding an external payment to an order
Now that you’ve mastered creating orders, it’s time to start raking in the dough. Most of the time, orders are paid for in person or via Clover’s Ecommerce API. But sometimes, you need to add external payments to an order. This section of the Clover REST API Tutorial collection guides you through that process.
Additional V3 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 for reducing the number of API calls and improving response time. This means your app will be more responsive and less likely to be rate limited. This section demonstrates how to make 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 have nailed the basics, you can use your newfound skills to create your own app in our Clover App Market. For additional information, be sure to check out our Developer Docs and REST API Reference.
It’s important to note that production apps and services must use API tokens generated by OAuth or the Clover Android SDK. Merchant API tokens are not suitable for production apps because they have additional restrictions, which may change at any time without notice.