Clover REST API

openapi: 3.1.0
info:
  title: Clover Platform REST API
  description: Clover Platform REST API v3 — merchant-scoped resources for inventory items, categories, orders, line items, payments, customers, employees, and shifts. Authentication uses OAuth 2.0 bearer access tokens (or merchant API tokens) scoped to a single merchant. Schemas and operations are derived from the Clover developer reference at docs.clover.com.
  version: v3
  contact:
    name: Clover Developer Platform
    url: https://docs.clover.com/dev/reference
  x-generated-from: documentation
  x-last-validated: '2026-06-02'
servers:
- url: https://api.clover.com
  description: Production (North America)
- url: https://api.eu.clover.com
  description: Production (Europe)
- url: https://api.la.clover.com
  description: Production (Latin America)
- url: https://apisandbox.dev.clover.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Inventory
  description: Inventory items, categories, and modifier groups for a merchant.
- name: Orders
  description: Orders, line items, and order payments.
- name: Payments
  description: Payment and refund records.
- name: Customers
  description: Customer profiles, contacts, and cards.
- name: Employees
  description: Employees and shifts.
paths:
  /v3/merchants/{mId}/items/{itemId}:
    delete:
      summary: Clover Delete an Inventory Item
      description: Delete an inventory item
      operationId: inventoryDeleteItem
      tags:
      - INVENTORY
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: itemId
        in: path
        required: true
        description: Item Id
        schema:
          type: string
        example: 9ABCDEF1234567
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                InventoryDeleteItem200Example:
                  summary: Default inventoryDeleteItem 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    hidden: true
                    available: true
                    autoManage: true
                    itemGroup: {}
                    options:
                    - {}
                    name: example-value
                    alternateName: example-value
                    code: example-value
                    sku: example-value
                    price: 1
                    priceType: FIXED
                    defaultTaxRates: true
                    unitName: example-value
                    cost: 1
                    isRevenue: true
                    stockCount: 1
                    taxRates:
                    - {}
                    modifierGroups:
                    - {}
                    categories:
                    - {}
                    tags:
                    - {}
                    canonical: {}
                    itemStock: {}
                    MenuItem: {}
                    modifiedTime: 1
                    deletedTime: 1
                    priceWithoutVat: 1
                    colorCode: example-value
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      summary: Clover Get a Single Inventory Item
      description: Retrieves an existing inventory item.
      operationId: inventoryGetItem
      tags:
      - INVENTORY
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant idenitifier.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: itemId
        in: path
        required: true
        description: Inventory item identifier.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Additional information provided as an expanded response: [tags, categories, taxRates, modifierGroups, itemStock, options]'
        schema:
          type: string
        example: example-expand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                InventoryGetItem200Example:
                  summary: Default inventoryGetItem 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    hidden: true
                    available: true
                    autoManage: true
                    itemGroup: {}
                    options:
                    - {}
                    name: example-value
                    alternateName: example-value
                    code: example-value
                    sku: example-value
                    price: 1
                    priceType: FIXED
                    defaultTaxRates: true
                    unitName: example-value
                    cost: 1
                    isRevenue: true
                    stockCount: 1
                    taxRates:
                    - {}
                    modifierGroups:
                    - {}
                    categories:
                    - {}
                    tags:
                    - {}
                    canonical: {}
                    itemStock: {}
                    MenuItem: {}
                    modifiedTime: 1
                    deletedTime: 1
                    priceWithoutVat: 1
                    colorCode: example-value
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/categories:
    post:
      summary: Clover Create an Item Category
      description: Create an item category
      operationId: categoryCreateCategory
      tags:
      - INVENTORY
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Expandable field: [items]'
        schema:
          type: string
        example: example-expand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
            examples:
              CategoryCreateCategoryRequestExample:
                summary: Default categoryCreateCategory request
                x-microcks-default: true
                value:
                  id: example-value
                  name: example-value
                  sortOrder: 1
                  items:
                  - {}
                  colorCode: example-value
                  deleted: true
                  modifiedTime: 1
                  canonical: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                CategoryCreateCategory200Example:
                  summary: Default categoryCreateCategory 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    name: example-value
                    sortOrder: 1
                    items:
                    - {}
                    colorCode: example-value
                    deleted: true
                    modifiedTime: 1
                    canonical: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      summary: Clover Get All Categories
      description: Retrieves all categories. Items display on the Register app within categories in the order in which they are added to a category. Items may be associated with one or more categories or may not be associated with any category. Categories display in the Register app based on the sort order value for each category.
      operationId: categoryGetCategories
      tags:
      - INVENTORY
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant identifier.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: filter
        in: query
        required: false
        description: 'Filter fields to display search results: [modifiedTime, deleted, sortOrder, name, colorCode, id]'
        schema:
          type: string
        example: example-filter
      - name: expand
        in: query
        required: false
        description: 'Additional information provided as an expanded response: [items]'
        schema:
          type: string
        example: example-expand
      - name: offset
        in: query
        required: false
        description: Position of the first line item returned in the search results. Indicates the number of line items that are excluded from the search results.
        schema:
          type: integer
        example: 1
      - name: limit
        in: query
        required: false
        description: "Maximum number of line items returned in the search result.\n Default: 100 \n Maximum limit: 1000"
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Category'
              examples:
                CategoryGetCategories200Example:
                  summary: Default categoryGetCategories 200 response
                  x-microcks-default: true
                  value:
                    elements:
                    - {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/items:
    get:
      summary: Clover Get All Inventory Items
      description: Displays line items for each category in the inventory for an order.
      operationId: inventoryGetItems
      tags:
      - INVENTORY
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant identifier.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: filter
        in: query
        required: false
        description: 'Filter fields to display search results: [lowStock, modifiedTime, hidden, itemCode, available, option.id, modifierGroup.id, autoManage, price, id, sku, defaultTaxRates, tags.id, alternateName, isRevenue, tags.name, deleted, item.id, name, itemStock.quantity, itemGroup.id, isAgeRestricted, ageRestrictedType, minimumAge]'
        schema:
          type: string
        example: example-filter
      - name: expand
        in: query
        required: false
        description: 'Additional information provided as an expanded response: [tags, categories, taxRates, modifierGroups, itemStock, options, ageRestricted]'
        schema:
          type: string
        example: example-expand
      - name: offset
        in: query
        required: false
        description: Position of the first line item returned in the search results. Indicates the number of line items that are excluded from the search results.
        schema:
          type: integer
        example: 1
      - name: limit
        in: query
        required: false
        description: "Maximum number of line items returned in the search result.\n Default: 100 \n Maximum limit: 1000"
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Item'
              examples:
                InventoryGetItems200Example:
                  summary: Default inventoryGetItems 200 response
                  x-microcks-default: true
                  value:
                    elements:
                    - {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Clover Create an Inventory Item
      description: Creates an inventory item.
      operationId: inventoryCreateItem
      tags:
      - INVENTORY
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant identifier.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Expandable fields to display additional nested information: [tags, categories, taxRates, modifierGroups, itemStock, options, ageRestricted]'
        schema:
          type: string
        example: example-expand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
            examples:
              InventoryCreateItemRequestExample:
                summary: Default inventoryCreateItem request
                x-microcks-default: true
                value:
                  id: example-value
                  hidden: true
                  available: true
                  autoManage: true
                  itemGroup: {}
                  options:
                  - {}
                  name: example-value
                  alternateName: example-value
                  code: example-value
                  sku: example-value
                  price: 1
                  priceType: FIXED
                  defaultTaxRates: true
                  unitName: example-value
                  cost: 1
                  isRevenue: true
                  stockCount: 1
                  taxRates:
                  - {}
                  modifierGroups:
                  - {}
                  categories:
                  - {}
                  tags:
                  - {}
                  canonical: {}
                  itemStock: {}
                  MenuItem: {}
                  modifiedTime: 1
                  deletedTime: 1
                  priceWithoutVat: 1
                  colorCode: example-value
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                InventoryCreateItem200Example:
                  summary: Default inventoryCreateItem 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    hidden: true
                    available: true
                    autoManage: true
                    itemGroup: {}
                    options:
                    - {}
                    name: example-value
                    alternateName: example-value
                    code: example-value
                    sku: example-value
                    price: 1
                    priceType: FIXED
                    defaultTaxRates: true
                    unitName: example-value
                    cost: 1
                    isRevenue: true
                    stockCount: 1
                    taxRates:
                    - {}
                    modifierGroups:
                    - {}
                    categories:
                    - {}
                    tags:
                    - {}
                    canonical: {}
                    itemStock: {}
                    MenuItem: {}
                    modifiedTime: 1
                    deletedTime: 1
                    priceWithoutVat: 1
                    colorCode: example-value
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/categories/{catId}:
    get:
      summary: Clover Get a Category
      description: Get a category
      operationId: categoryGetCategory
      tags:
      - INVENTORY
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: catId
        in: path
        required: true
        description: Category Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Expandable field: [items]'
        schema:
          type: string
        example: example-expand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                CategoryGetCategory200Example:
                  summary: Default categoryGetCategory 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    name: example-value
                    sortOrder: 1
                    items:
                    - {}
                    colorCode: example-value
                    deleted: true
                    modifiedTime: 1
                    canonical: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/payments/{payId}:
    get:
      summary: Clover Get a Single Payment
      description: Retrieve a single payment information, including the total amount, tip amount, tax amount, and result status.
      operationId: payGetPayment
      tags:
      - PAYMENTS
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: payId
        in: path
        required: true
        description: Payment Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Expandable fields: [tender, germanInfo, lineItemPayments, cardTransaction, dccInfo, employee, refunds, transactionInfo, externalReferenceId, oceanGatewayInfo, taxRates, additionalCharges, appTracking, paymentAttributes, order]'
        schema:
          type: string
        example: example-expand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
              examples:
                PayGetPayment200Example:
                  summary: Default payGetPayment 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    order: {}
                    device: {}
                    tender: {}
                    amount: 1
                    tipAmount: 1
                    taxAmount: 1
                    cashbackAmount: 1
                    cashTendered: 1
                    externalPaymentId: example-value
                    employee: {}
                    createdTime: 1
                    clientCreatedTime: 1
                    gatewayProcessingTime: 1
                    modifiedTime: 1
                    offline: true
                    result: SUCCESS
                    cardTransaction: {}
                    serviceCharge: {}
                    attributes: {}
                    additionalCharges:
                    - {}
                    taxRates:
                    - {}
                    refunds:
                    - {}
                    note: example-value
                    lineItemPayments:
                    - {}
                    authorization: {}
                    voidPaymentRef: {}
                    voidReason: USER_CANCEL
                    voidReasonDetails: {}
                    dccInfo: {}
                    transactionSettings: {}
                    germanInfo: {}
                    appTracking: {}
                    cashAdvanceExtra: {}
                    transactionInfo: {}
                    signatureDisclaimer: {}
                    externalReferenceId: example-value
                    merchant: {}
                    increments:
                    - {}
                    purchaseCardL2: {}
                    purchaseCardL3: {}
                    oceanGatewayInfo: {}
                    terminalManagementComponents:
                    - {}
                    emiInfo: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/employees/{empId}:
    get:
      summary: Clover Get a Single Employee
      description: Returns information for a single employee.  Accepts optional expand query parameters
      operationId: employeeGetEmployee
      tags:
      - EMPLOYEES
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: empId
        in: path
        required: true
        description: Employee Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Expandable fields: [roles, shifts]'
        schema:
          type: string
        example: example-expand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
              examples:
                EmployeeGetEmployee200Example:
                  summary: Default employeeGetEmployee 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    name: example-value
                    nickname: example-value
                    customId: example-value
                    email: example-value
                    inviteSent: true
                    claimedTime: 1
                    deletedTime: 1
                    pin: example-value
                    unhashedPin: example-value
                    role: OWNER
                    roles:
                    - {}
                    isOwner: true
                    shifts:
                    - {}
                    payments:
                    - {}
                    orders:
                    - {}
                    employeeCards:
                    - {}
                    merchant: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/customers/{customerId}:
    get:
      summary: Clover Get a Single Customer
      description: Returns information for a single customer.
      operationId: customersGetCustomer
      tags:
      - CUSTOMERS
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: customerId
        in: path
        required: true
        description: customerId parameter.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: filter
        in: query
        required: false
        description: 'Filter fields: [customerSince, firstName, lastName, emailAddress, phoneNumber, marketingAllowed, fullName, id, deletedTime]'
        schema:
          type: string
        example: example-filter
      - name: expand
        in: query
        required: false
        description: 'Expandable fields: [addresses, emailAddresses, phoneNumbers, cards, metadata]'
        schema:
          type: string
        example: example-expand
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                CustomersGetCustomer200Example:
                  summary: Default customersGetCustomer 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    merchant: {}
                    firstName: example-value
                    lastName: example-value
                    marketingAllowed: true
                    customerSince: 1
                    orders:
                    - {}
                    addresses:
                    - {}
                    emailAddresses:
                    - {}
                    phoneNumbers:
                    - {}
                    cards:
                    - {}
                    metadata: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Clover Update a Customer
      description: Updates information for a single customer.
      operationId: customersUpdateCustomer
      tags:
      - CUSTOMERS
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant identifier.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: customerId
        in: path
        required: true
        description: Unique identifier of the customer.
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: expand
        in: query
        required: false
        description: 'Expandable fields to display additional nested information: [addresses, emailAddresses, phoneNumbers, cards, metadata]'
        schema:
          type: string
        example: example-expand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
            examples:
              CustomersUpdateCustomerRequestExample:
                summary: Default customersUpdateCustomer request
                x-microcks-default: true
                value:
                  id: example-value
                  merchant: {}
                  firstName: example-value
                  lastName: example-value
                  marketingAllowed: true
                  customerSince: 1
                  orders:
                  - {}
                  addresses:
                  - {}
                  emailAddresses:
                  - {}
                  phoneNumbers:
                  - {}
                  cards:
                  - {}
                  metadata: {}
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                CustomersUpdateCustomer200Example:
                  summary: Default customersUpdateCustomer 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    merchant: {}
                    firstName: example-value
                    lastName: example-value
                    marketingAllowed: true
                    customerSince: 1
                    orders:
                    - {}
                    addresses:
                    - {}
                    emailAddresses:
                    - {}
                    phoneNumbers:
                    - {}
                    cards:
                    - {}
                    metadata: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Clover Delete a Customer
      description: Deletes a single customer from a merchant.
      operationId: customersDeleteCustomer
      tags:
      - CUSTOMERS
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: customerId
        in: path
        required: true
        description: customerId parameter.
        schema:
          type: string
        example: 9ABCDEF1234567
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                CustomersDeleteCustomer200Example:
                  summary: Default customersDeleteCustomer 200 response
                  x-microcks-default: true
                  value:
                    id: example-value
                    merchant: {}
                    firstName: example-value
                    lastName: example-value
                    marketingAllowed: true
                    customerSince: 1
                    orders:
                    - {}
                    addresses:
                    - {}
                    emailAddresses:
                    - {}
                    phoneNumbers:
                    - {}
                    cards:
                    - {}
                    metadata: {}
        '401':
          description: Authentication required or invalid token.
        '429':
          description: Too many requests; rate limit exceeded.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/merchants/{mId}/orders/{orderId}/line_items:
    post:
      summary: Clover Create a New Line Item
      description: "Creates a new line item for an order. Requests must include either a `price` or an `item` object with an inventory item `id`. \n\n**Note:** To ensure platform stability, an order is limited to a maximum of 3,000 line items. If this call would cause the order to exceed this limit, the request will fail with a `400 Bad Request` error."
      operationId: orderCreateLineItem
      tags:
      - ORDERS
      parameters:
      - name: mId
        in: path
        required: true
        description: Merchant Id
        schema:
          type: string
        example: 9ABCDEF1234567
      - name: orderId
        in: path
        required: true
        description: Order Id
        schema:
          type: string
        example: 9ABCDEF1234567
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              OrderCreateLineItemRequestExample:
                summary: Default orderCreateLineItem request
                x-microcks-default:

# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clover/refs/heads/main/openapi/clover-platform-rest-api-openapi.yml