Clover made the following API updates for May 2024.

Platform API

Inventory API

Updated identifiers (id) for the following body parameters under the Create or delete associations between inventory items and modifier groups endpoint.

• modifierGroup
• item

Clover made the following API updates for January 2024.

Ecommerce API

Gift Card API

Added the Gift Card API that allows the use of gift cards as a prepaid payment source for services, merchandise, or even cash, depending on the terms and conditions set by the card issuer. To support this feature, Clover introduced the following API endpoints:

• Create a gift card token
• Create and activate physical and virtual gift card
• Request gift card balance
• Reload gift card
• Request cashout of gift card balance

Added gift card parameters to the response bodies of the following Ecomm API endpoints:

• Create a charge
• Create a refund
• Capture a charge

For more information, see Use the Gift Card API tutorial.

Clover made the following API updates for October 2023.

Platform API

Inventory

Added offset and limit parameters to the following endpoints. This lets you search your line items results with a specific limit and offset:

• Get all items in a single modifier group
• Get all modifiers
• Get all modifiers in a single modifier group
• Get all attributes
• Get all options
• Get all options for an attribute
• Get all discounts

offset Position of the first line item returned in the search results indicates the number of line items that are excluded from the search results.`

limit Maximum number of line items returned in the search result.

Ecommerce API

Charge API

Added global currency support

Clover added Multi-Currency Pricing (MCP) support for merchants in the United States (US) and Canada. They can now accept customer payments in currency other than the US Dollar (USD). To use this feature, enter a currency code other than USD in the currency parameter of Create a charge endpoint.

Added split shipment support

Clover added the split_shipment parameter to support Split Shipment for a single pre-authorization. You can create 1-99 split shipments for a single order. To use this feature, enter shipment information in the split_shipment parameter in n/m format, where n is the current shipment and m is the total number of shipments. See Capture a charge.

Customer API

Updated Revoke a payment source endpoint to support ACH (Automated Clearing House) token. You can use Revoke a payment source to remove an ACH token as a payment source from the customer profile.

Clover made the following API updates for September 2023.

Platform API

Inventory

Added offset and limit parameters to the following endpoints. This lets you search your line items results with a specific limit and offset:

• Get all categories
• Get all items in a single category
• Get all categories of a single item
• Get all modifier groups

offset Position of the first line item returned in the search results. Indicates the number of line items that are excluded from the search results.limit Maximum number of line items returned in the search result.

Merchant API

Added offset and limit parameters to the following endpoints. This lets you search your line items results with a specific limit and offset:

• Get all tip suggestions for a merchant
• Get all order types for a merchant
• Get all roles for a merchant
• Get all tenders for a merchant

offset Position of the first line item returned in the search results. Indicates the number of line items that are excluded from the search results.limit Maximum number of line items returned in the search result.

Order API

• Updated an endpoint title name from Void a line item to the Create a list of voided line items endpoint, which was misleading to another endpoint Void a line item due to a similar name
• Updated the state parameter definition of the Update an order endpoint for the following scenarios:
  • open or OPEN and locked - Automatically set by Clover, for example, when a line item is added to the order or a payment is taken.
  • When an order is created using REST API, Clover recommends manually setting the order state value to Open.
  • When an order is created using Android the SDK, do not manually set the order state. The value must be left empty, and Clover automatically updates the value to open and locked.
  • Null - Default value when no value is manually set. This indicates a hidden order. Hidden orders do not display on the screen but can be retrieved using the order ID.

Ecommerce

Order API

• Updated the required objects such as city, postal_code, and state under the shipping address parameter and amount object under the items parameter for the Create an order endpoint.
• Added important information to customer and source parameters under the Pay for an order endpoint. Either a payment source or customer must be associated with an order for payment. If a customer is not attached to the order, then the source in this field is charged for the order.

Invoice API

Added the following information under the customer parameter in the Create checkout endpoint:

• If the merchant uses hosted checkout with the customer information feature enabled (HCO_CUSTOMER_INFO_FEATURE_ENABLED), then it is mandatory to enter the customer’s firstname, lastname, and email address information to create a hosted checkout session. The merchant can also customize fields required on the Merchant Dashboard > Account & Setup > Hosted Checkout > Customer Information > Customize.
• If the merchant uses hosted checkout without enabling the customer information feature, then only the customer's first name, last name, or email address is required to create a hosted checkout session.

Clover made the following API updates for August 2023.

Inventory APIs

Added offset and limit parameters to the following endpoints. This lets you search your line items results with a specific limit and offset:

• Get all tags
• Get all inventory without a revenue class
• Get all item groups
• Get all tax rates

offset Position of the first line item returned in the search results. Indicates the number of line items that are excluded from the search results.limit Maximum number of line items returned in the search result.

Order APIs

Added taxRate and items parameters to the Create or delete association between items and tax rates endpoint. taxRate indicates the name of the tax rate anditems indicates items associated with the tax rate. This update lets you assign a name to the tax rate and associate items with it.

Clover made the following API updates for July 2023.

Payments and Orders APIs

Clover is enforcing a 90-day window for API calls to the following endpoints.

• Get all payments for an order
• Get all payments
• Get all payments under an employee
• Get all authorizations

We discovered an issue caused by developer apps that aren't using a date/time filter when sending GET requests to Clover Payments and Orders endpoints. Some of these apps are causing high server loads and performance issues.

If your app expects orders or payments for a time frame greater than 90 days, you need to make additional API calls that include filter query parameters for the additional time frames.

As a best practice, use the createdTime filter query parameter value in your API calls to reduce payload sizes and server loads. Create the filter within the 90-day time frame.

Example:

filter=createdTime>=[unix-time]&filter=createdTime\<=[unix-time]

Contact developer relations if you have questions.

Token APIs

Introduced the Create an ACH token API. This API creates a single-use token that indicates Automated Clearing House (ACH) details. Use single-pay tokens for single payments, like create a charge or pay for an order endpoint.

Clover made the following API updates for June 2023.

Inventory APIs

Added offset and limit capabilities to the /v3/merchants/{mId}/items endpoint.

offset Position of the first line item returned in the search results. Indicates the number of line items that are excluded from the search results.limit Maximum number of line items returned in the search result.

See Get all inventory items.

Clover made the following API updates for May 2023.

Merchant APIs

Added reseller identifier (reseller_id) to the Get a single merchant endpoint response. This helps merchants identify reseller information.

Payment APIs

Removed the following search filter fields from the Get all payments for an order, Get all payments, and Get all payments under an employee endpoints.

• voidPaymentRef
• voidReasonDetails
• voidReason
• voidPaymentRef.id
• cardTransaction.last4
• cashTendered
• voidPaymentRef.createdTime
• cardTransaction.transactionNo
• voidPaymentRef.employeeId
• paymentRefundId
• paymentAttributes.type
• merchantId
• deletedTime
• tipAmount
• order.id
• paymentAttributes.value
• paymentAttributes.uuid
• voidReasonDetails
• cardTransaction.captured
• cardTransaction.currency
• taxAmount
• orderType.databaseId
• developerApp.package

Order APIs

Updated the Gets a list of orders endpoint. The search results for orders list is restricted to the last 90 days if the search filter fields include:

• deletedTime
• externalReferenceId
• createdTime
• total
• payType
• title
• note
• state
• manualTransaction
• cardTransaction.last4
• testMode
• touched

Clover made the following API updates for April 2023.

Updated the /v3/merchants/{mId}/orders/{orderId}/payments endpoint. This allows you to log external tenders for bookkeeping purposes.

See Create a payment record on an order.

Clover made the following API updates for March 2023.

For Clover merchants in the US, Canada, and Argentina, signature verification is no longer required as a cardholder verification method (CVM). The verify or reject signature screen is replaced with a signature screen that does not require merchant action. CVM in receipts now displays “Signature” instead of “Signature Verified.”

For more information, see our blog.