Use this topic to understand the primary data types used in Clover API requests and responses—String, UUID, Number, Integer, Boolean, Date, and Timestamp.

String

Sequence of characters used to represent text. Strings are enclosed in quotes in most programming languages, such as "Hello, World!".

Usage:

• Text data, such as names, descriptions, and other textual information.
• Configuration settings that are human-readable and editable.
• User inputs, such as form data in web applications.
• Messages, logging information, or text that needs to be displayed to users.

Example: Text data—Merchant name and description.

{
  "name": "John Smith",
  "description": "Test merchant"
}

UUID (Universally unique identifier) String

Universally unique identifier (UUID) is a 128-bit identifier used to uniquely identify information. It is represented as a string of 32 hexadecimal digits, displayed in five groups separated by hyphens. Example: 123e4567-e89b-12d3-a456-426614174000.

Usage:

• Unique identifiers in distributed systems.
• Primary database keys.
• Unique session IDs.

Example:

Merchant information—To retrieve merchant details, use the merchant UUID.

GET /v3/merchants/{merchantId}

Orders—Listing orders for a merchant requires the merchant's UUID.

GET /v3/merchants/{merchantId}/orders

Number

Numeric values that can be integers or floating-point numbers, that is a number that has a decimal point.

Usage:

• Arithmetic operations or calculations.
• Measurements, such as weight, height, or distance.
• Financial data, such as monetary values, prices, or financial calculations.

Example: Prices—Indicating prices or amounts.

{
  "price": 19.99
}

Integer and format: int64

Whole number without a fractional component.

Usage:

• Count of items, such as number of products or users.
• Indexes, such as arrays or lists
• Numeric identifiers (IDs) that do not require the uniqueness of UUIDs.

Example: Quantities—Used for quantities or counts.

{
  "quantity": 5
}

int64

A 64-bit integer capable of representing a wide range of integer values. It provides higher precision and can store significantly larger numbers compared to int32 or smaller integer types.

Example: Large Identifiers—Used for large numeric identifiers.

{  
  "largeId": 9223372036854775807  
}

Boolean

Indicates a value that can be either true or false.

Usage:

• Flags or binary states, such as on/off, true/false, yes/no.
• Conditions in logic statements or control flow.

Example: Binary state—True/false

{
  "isActive": true
}

Date

Indicates a specific day, month, and year.

Usage:

• Record the date of events, such as transactions or appointments.
• Schedule tasks or reminders.
• Store historical dates or timelines.

Example: Transaction dates—Log the date of a transaction.

{
  "transactionDate": "2025-01-01"
}

Timestamp and Unix time

Indicates a specific point in time, often including both date and time components.

Unix time is a system for tracking time as the number of seconds that have elapsed since the Unix epoch (January 1, 1970). Clover uses timestamps in milliseconds from the same epoch time. If your app requires Unix time, divide the Clover timestamp by 1000.

Usage:

• Record and log the exact time an event occurred.
• Calculate durations or time differences.
• Synchronize data across different systems or time zones.

Example: Event timestamp—Log the exact time an event occurred.

{
  "createdTimestamp": 1706547596608
}

Null

Indicates a null value, which indicates the absence of a value or that a value is not applicable. To have a response display all possible fields, set the return_null_fields query parameter to true.

Usage:

In the Clover API, null values are used to indicate fields that do not have a value. For example, when retrieving order details, some fields may be null if they are not applicable or are not set. Usage includes:

• Optional fields that may not always have a value.
• Value is not set or is unknown.
• Clear or remove a value from a field.

Example: Order details—Example response with null values for fields such as note, labelKey, label, taxable, indicating that they do not have values.

{
  "id": "order_12345",
  "currency": "USD",
  "employee": {
    "id": "employee_67890"
  },
  "total": 152,
  "note": null,
  "orderType": {
    "id": "orderType_123",
    "labelKey": null,
    "label": null,
    "taxable": null,
}

Additional considerations and data types that may be relevant depending on the specific API endpoints and use cases:

Array

Collection of elements, which can be of any data type, including objects, strings, numbers, and so on.

Usage:

• Lists to store multiple values in a single variable, such as a list of items, orders, or products.
• Batch operations on multiple elements at once.

Example: List of Items—Array of item objects.

{
  "items": [
    {
      "id": "item1",
      "name": "Item One"
    },
    {
      "id": "item2",
      "name": "Item Two"
    }
  ]
}

Object

Collection of key-value pairs, where each key is a string, and the value can be any data type, including another object.

Usage:

• Indicate complex data structures with multiple attributes.
• Organize related data into a single entity, as in nested data.

Example: Merchant information—An object indicating a merchant with nested attributes.

{
  "merchant": {
    "id": "merchant1",
    "name": "John's Store",
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345"
    }
  }
}

Enum

Enumeration (enum) is a special data type that consists of a set of named values called elements or members.

Usage:

• Fixed set of values, for example, to indicate a variable that can only take one out of a small set of possible values.
• Status status codes, types, or categories.

Example: Order status—Enum representing the status of an order.

{
  "status": "COMPLETED"
}