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.