Clover ORDERS API
The ORDERS API from Clover — 4 operation(s) for orders.
OpenAPI Specification
openapi: 3.1.0
info:
title: Clover Ecommerce CHARGES ORDERS API
description: 'Clover Ecommerce API v1 — online (card-not-present) payments: charges, captures, refunds, tokenization, and hosted checkout. Authentication uses OAuth 2.0 / PAKMS Ecommerce API keys. Schemas and operations are derived from the Clover developer reference at docs.clover.com.'
version: v1
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://scl.clover.com
description: Production Ecommerce
- url: https://scl-sandbox.dev.clover.com
description: Sandbox Ecommerce
security:
- OAuth2: []
tags:
- name: ORDERS
paths:
/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: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderCreateLineItem200Example:
summary: Default orderCreateLineItem 200 response
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
'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 Line Items for an Order
description: Returns all line items for an order.
operationId: orderGetOrderLineItems
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
- name: expand
in: query
required: false
description: 'Expandable fields: [employee, orderType, discounts, modifications, taxRates, payments]'
schema:
type: string
example: example-expand
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
properties:
elements:
type: array
items:
$ref: '#/components/schemas/Order'
examples:
OrderGetOrderLineItems200Example:
summary: Default orderGetOrderLineItems 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}/orders:
post:
summary: Clover Create Custom Orders
description: "**Description:** Creates or updates orders with a non-Clover inventory and dynamically calculates taxes. Valid fields are: taxRemoved, note, title, state, testMode, manualTransaction, groupLineItems, and orderType. Use separate API calls to add line items. <br> \n **Tip:** Use the [create an atomic order](https://docs.clover.com/dev/reference/ordercreateatomicorder) endpoint to create orders using Clover inventory and leverage the real-time totals and tax calculation features using a single API call. <br> \n **Tutorial:** [Create custom orders](https://docs.clover.com/dev/docs/creating-custom-orders)."
operationId: orderCreateOrder
tags:
- ORDERS
parameters:
- name: mId
in: path
required: true
description: Merchant identifier.
schema:
type: string
example: 9ABCDEF1234567
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderCreateOrderRequestExample:
summary: Default orderCreateOrder request
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderCreateOrder200Example:
summary: Default orderCreateOrder 200 response
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
'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 Gets a List of Orders
description: Displays a list of orders. See [Manage orders data](https://docs.clover.com/build/working-with-orders/) for more details.
operationId: orderGetOrders
tags:
- ORDERS
parameters:
- name: mId
in: path
required: true
description: Merchant identifier (mId).
schema:
type: string
example: 9ABCDEF1234567
- name: filter
in: query
required: false
description: "Filter fields to display search results: [employee.id, note, modifiedTime, orderType, touched, cardTransaction.last4, manualTransaction, employee.name, title, device.id, externalReferenceId, clientCreatedTime, total, payType, testMode, createdTime, id, state, deletedTime]\n `Note`: Search results for the list of orders list is restricted to the last 90 days if the filter fields include: [deletedTime, externalReferenceId, createdTime, total, payType, title, note, state, manualTransaction, cardTransaction.last4, testMode, touched]"
schema:
type: string
example: example-filter
- name: expand
in: query
required: false
description: 'Additional information provided as an expanded response: [employee, payments, refunds, credits, voids, payment.tender, payment.cardTransaction, lineItems, customers, serviceCharge, discounts, orderType, lineItems.discounts, lineItems.modifications]'
schema:
type: string
example: example-expand
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
properties:
elements:
type: array
items:
$ref: '#/components/schemas/Order'
examples:
OrderGetOrders200Example:
summary: Default orderGetOrders 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}/orders/{orderId}/payments:
post:
summary: Clover Create a Payment Record on an Order
description: "Payment must include a `positive amount` and a valid `tender ID`.\n `Note`: This endpoint references external tenders and logs them for bookkeeping purposes. This is not for Clover credits/debit tenders. A merchant's tenders and their IDs can be retrieved from /v3/merchants/mId/tenders."
operationId: orderCreatePaymentForOrder
tags:
- ORDERS
parameters:
- name: mId
in: path
required: true
description: Merchant identifier.
schema:
type: string
example: 9ABCDEF1234567
- name: orderId
in: path
required: true
description: Order identifier.
schema:
type: string
example: 9ABCDEF1234567
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderCreatePaymentForOrderRequestExample:
summary: Default orderCreatePaymentForOrder request
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderCreatePaymentForOrder200Example:
summary: Default orderCreatePaymentForOrder 200 response
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
'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}:
post:
summary: Clover Update an Order
description: Updates a single order. See [working-with-orders](https://docs.clover.com/build/working-with-orders/) for more details.
operationId: orderUpdateOrder
tags:
- ORDERS
parameters:
- name: mId
in: path
required: true
description: Merchant identifier.
schema:
type: string
example: 9ABCDEF1234567
- name: orderId
in: path
required: true
description: Order identifier.
schema:
type: string
example: 9ABCDEF1234567
- name: expand
in: query
required: false
description: 'Additional information provided as an expanded response: [lineItems, serviceCharge, discounts, credits, payments, customers, orderFulfillmentEvent, refunds]'
schema:
type: string
example: example-expand
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderUpdateOrderRequestExample:
summary: Default orderUpdateOrder request
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderUpdateOrder200Example:
summary: Default orderUpdateOrder 200 response
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
'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 Order
description: 'Returns a single order. See https://docs.clover.com/build/working-with-orders/ for more details. '
operationId: orderGetOrder
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
- name: expand
in: query
required: false
description: 'Expandable fields: [lineItems, serviceCharge, discounts, credits, payments, customers, orderFulfillmentEvent, refunds]'
schema:
type: string
example: example-expand
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderGetOrder200Example:
summary: Default orderGetOrder 200 response
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
'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 an Order
description: Deletes a single order. See https://docs.clover.com/build/working-with-orders/ for more details.
operationId: orderDeleteOrder
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
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderDeleteOrder200Example:
summary: Default orderDeleteOrder 200 response
x-microcks-default: true
value:
id: example-value
currency: example-value
customers:
- {}
employee: {}
total: 1
externalReferenceId: example-value
unpaidBalance: 1
paymentState: OPEN
title: example-value
note: example-value
orderType: {}
taxRemoved: true
isVat: true
state: example-value
manualTransaction: true
groupLineItems: true
testMode: true
payType: SPLIT_GUEST
createdTime: 1
clientCreatedTime: 1
modifiedTime: 1
deletedTimestamp: 1
serviceCharge: {}
additionalCharges:
- {}
discounts:
- {}
lineItems:
- {}
payments:
- {}
refunds:
- {}
credits:
- {}
voids:
- {}
preAuths:
- {}
device: {}
authorizations:
- {}
merchant: {}
printGroups:
- {}
orderFulfillmentEvent: {}
'401':
description: Authentication required or invalid token.
'429':
description: Too many requests; rate limit exceeded.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Order:
type: object
properties:
id:
type: string
description: Unique identifier
example: 9ABCDEF1234567
currency:
type: string
description: Currency of this order. For example, "USD"
example: USD
customers:
type: array
items:
type: object
example: []
employee:
type: object
example: {}
total:
type: integer
description: Total price of the order in cents
example: 1099
externalReferenceId:
type: string
description: External reference id if present in the order
example: 9ABCDEF1234567
unpaidBalance:
type: integer
description: The net of orders with payment minus the amount collected. Includes refunds, manual refunds, tax, tip, service charge, non-revenue items, paid gift card activations and loads and discounts
example: 1099
paymentState:
type: string
description: Is this order paid or not?
enum:
- OPEN
- PAID
- REFUNDED
- CREDITED
- PARTIALLY_PAID
- PARTIALLY_REFUNDED
example: OPEN
title:
type: string
example: example-title
note:
type: string
description: An arbitrary string with information about this order, may be printed on the order receipt and displayed in apps
example: Example note value.
orderType:
type: object
example: {}
taxRemoved:
type: boolean
description: If true then this order should not have taxes applied to it
example: true
isVat:
type: boolean
description: This order was created by merchant with VAT enabled.
example: true
state:
type: string
description: A String generally describing the state of the order. If no value is set, the state defaults to null, which indicates a hidden order. A hidden order is not displayed in user interfaces and can only be retrieved by its id. When creating an order via the REST API the value must be manua
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clover/refs/heads/main/openapi/clover-orders-api-openapi.yml