Four minute guide to get up & running with the Clover REST API
The Clover REST API is a way for web 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 to making test API requests with Postman.
Before getting to the exciting bits, 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 3rd-party apps you can use to test API calls 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 downloading, you will need to import it in 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: eg, Clover Test Merchant (Sandbox)
- You’ll need to enter a few key/value pairs in order to use the Clover API Library 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 to 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 this for 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 a current discount the merchant has or create a new custom 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. Many third-party developers accept e-commerce payments through Payeezy, a First Data product. In order to represent these payments in Clover, you can add external payments to an order. This section guides you through that process.
Additional V3 API Operations
Advanced query operations allow for greater control 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
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.