Clover

Clover

This connector uses the Clover Platform REST API v3 for one merchant: business details and settings, inventory items with stock, categories, tax rates, discounts and modifier groups, orders with line items and discounts, payments, refunds and tenders, customers, employees, roles and shifts. It can create and update items, stock, categories, orders and customers. It does not take card payments or issue refunds: those happen on the Clover device or through the Ecommerce API.

Setup (5 minutes)

1. Sign in to the Clover Merchant Dashboard as an admin and open Settings, View all settings, API tokens (Account and setup, Business operations). Create a token and tick the permissions the tools need: Merchant read, Inventory read and write, Orders read and write, Payments read, Customers read and write, Employees read. For a test merchant, do the same from the Global Developer Dashboard (Test merchants, Launch dashboard).
2. Paste the token into CLOVER_API_TOKEN. It is sent as Authorization: Bearer <token>.
3. Set CLOVER_MERCHANT_ID to the 13-character merchant id (mId), shown in the dashboard address .../merchants/<mId>/... and under Account and setup, Merchants.
4. Set CLOVER_API_URL to the region of the merchant: https://api.clover.com (North America), https://api.eu.clover.com (Europe), https://api.la.clover.com (Latin America) or https://apisandbox.dev.clover.com (sandbox).
5. Run clover_get_merchant to check the setup.

Workflow

• Merchant: clover_get_merchant, clover_get_merchant_address, clover_get_merchant_properties (currency, time zone), clover_list_order_types, clover_list_roles.
• Inventory: clover_list_items, clover_get_item, clover_create_item, clover_update_item; stock with clover_list_item_stocks, clover_get_item_stock, clover_update_item_stock; categories with clover_list_categories, clover_get_category, clover_list_category_items, clover_create_category, clover_update_category; clover_list_tax_rates, clover_list_discounts, clover_list_modifier_groups.
• Orders: clover_list_orders (filter by time, expand lineItems and payments), clover_get_order, clover_list_order_line_items, clover_get_order_line_item, clover_list_order_discounts. To build an order in one call use clover_calculate_order to show the total, then clover_create_atomic_order. Step by step: clover_create_order, clover_add_line_item, clover_add_order_discount, clover_update_order. clover_void_line_item and clover_delete_order remove lines and orders.
• Payments: clover_list_payments, clover_get_payment, clover_list_order_payments, clover_list_employee_payments; refunds with clover_list_refunds, clover_get_refund; payment methods with clover_list_tenders, clover_get_tender.
• Customers: clover_list_customers (expand emailAddresses and phoneNumbers), clover_get_customer, clover_create_customer, clover_update_customer, clover_delete_customer.
• Staff: clover_list_employees, clover_get_employee, clover_list_shifts, clover_list_employee_shifts.

Switched off at install: clover_void_line_item, clover_delete_order and clover_delete_customer; they cannot be undone, so an admin switches them on when the team needs them.

Before writing: orders and stock changes show up on the merchant's devices and reports at once. Clover updates records with POST to the record's address. clover_update_item_stock sets an absolute quantity, not a difference.

Filters: filter takes a list of conditions, each field operator value, e.g. ["createdTime>=1767225600000", "createdTime<1767830400000"]; they are combined with AND. Time filters on orders, payments and refunds cover at most 90 days per request: split longer periods into 90-day windows. expand adds related records in the same call (comma-separated).

Reading the answers: lists come as {elements: [...], href}. Money is an integer in cents of the merchant currency (1999 = 19.99); discounts are negative amounts. Quantities on line items (unitQty) are x 1000. Tax rates are x 100000 (825000 = 8.25%). Times are Unix epoch milliseconds in UTC; convert with the time zone from clover_get_merchant_properties. Ids are 13-character strings.

Paging: limit (default 100, at most 1000) and offset. When a page has limit elements, ask again with offset + limit. Nested expanded lists stop at 100 entries.

Limits and errors: 16 requests per second and 5 concurrent requests per token (429 with retry-after). 401 means a wrong or revoked token or the wrong region in CLOVER_API_URL; 403 a token without the permission for that data; 404 a wrong merchant id or record id; 400 an invalid filter field.