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.
\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.
\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 manually set to "open". When creating an order via the Android SDK the value must be left empty and the value will be updated to "open" and "locked" automatically when actions such as taking payments and adding line items occur. The state value is not checked or enforced by the Clover server, at this time it is used for visualization purposes only.
example: open
manualTransaction:
type: boolean
description: Whether this order represents a manual transaction. A manual transaction is a transaction that has an arbitrary amount defined and is not associated with any inventory items. For example, the Clover Sale App and Clover Manual Transaction App create manual transactions. A manual transactions will have a single associated line item to hold the sale amount, but the generated receipt will display this differently to indicate that it is not considered a typical order with inventory items.
example: true
groupLineItems:
type: boolean
description: Whether similar line items should be grouped together on the receipt that this order generates. Item "similarity" is based on items having matching values for a set of properties including price, modifiers, and discounts.
example: true
testMode:
type: boolean
description: Whether this order was created in test mode. Payments made against test orders are not processed. Test mode orders can be deleted from the Orders App on the merchant's device or web dashboard (https://www.clover.com/orders/m/{mId}/orders). They will also be deleted when the device sends a POST to the /v2/merchant/{mId}/orders/delete_all_tests endpoint.
example: true
payType:
type: string
description: 'Possible values: SPLIT_GUEST, SPLIT_ITEM, SPLIT_CUSTOM, FULL. During the payment flow, if the user chooses to split the payment for this order, this field will be set to one of the SPLIT_* values to indicate how the full amount should be split. If the user chooses to pay for the order in full with one payment, then this field will be FULL.'
enum:
- SPLIT_GUEST
- SPLIT_ITEM
- SPLIT_CUSTOM
- FULL
example: SPLIT_GUEST
createdTime:
type: integer
format: int64
description: Creation timestamp
example: 1718153645000
clientCreatedTime:
type: integer
format: int64
description: Time at which the client created this order.
example: 1718153645000
modifiedTime:
type: integer
format: int64
description: Last modified time of the order.
example: 1718153645000
deletedTimestamp:
type: integer
format: int64
example: 1718153645000
serviceCharge:
type: object
example: {}
additionalCharges:
type: array
items:
type: object
example: []
discounts:
type: array
items:
type: object
example: []
lineItems:
type: array
items:
type: object
example: []
payments:
type: array
items:
type: object
example: []
refunds:
type: array
items:
type: object
example: []
credits:
type: array
items:
type: object
example: []
voids:
type: array
items:
type: object
example: []
preAuths:
type: array
items:
type: object
example: []
device:
type: object
example: {}
authorizations:
type: array
items:
type: object
example: []
merchant:
type: object
example: {}
printGroups:
type: array
items:
type: object
example: []
orderFulfillmentEvent:
type: object
example: {}
description: Clover Order resource. Schema derived from the Clover Platform REST API v3 reference.
x-schema-source: documentation
x-source-url: https://docs.clover.com/dev/reference/ordergetorder
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://www.clover.com/oauth/authorize
tokenUrl: https://api.clover.com/oauth/token
scopes: {}
description: OAuth 2.0 token or Ecommerce (PAKMS) API key.