Get orders

get https://scl-sandbox.dev.clover.com/v1/orders

Retrieves a list of the merchant's orders. Newest order displays first in the list.

Query Params

created

Order creation date.

customer

string

length ≤ 5000

Returns orders for a specific customer.

ending_before

string

length ≤ 5000

Cursor used in pagination. The ending_before object ID sets your place in the list. For example, if you receive 100 objects in a list starting with obj_bar, add ending_before=obj_bar in your subsequent request to retrieve the previous page of the list.

expand

array of strings

Additional information provided as an expanded response, for example, related object nested within the parent. See Use expandable fields.

expand

ids

array of strings

Universally unique identifier (UUID) of the order.

ids

limit

integer

Number of objects returned by the request, ranging between 1 and 100.
Default value: 10

starting_after

string

length ≤ 5000

Cursor used in pagination. The starting_after object ID sets your place in the list. For example, if you receive 100 objects in a list starting with obj_foo, add starting_after=obj_foo in your subsequent request to retrieve the next page of the list.

status

string

length ≤ 5000

Displays orders based on status—created, paid, fulfilled, or refunded.

status_transitions

object

Displays orders based on the time of a status change—paid, fulfilled, canceled, or returned.

Responses

Response body

object

data

array of objects

required

data*

object

amount

int64

required

Total order amount in the smallest monetary unit of the merchant's currency.

amount_paid

int64

≥ 0

Amount currently paid toward the order total.

amount_due

int64

≥ 0

Amount still due toward the order total.

tax_amount

int64

≥ 0

Merchant-defined flat tax amount for the order.
Format: Cents

tax_amount_paid

int64

≥ 0

Amount currently paid toward the tax total.

tip_amount

int64

≥ 0

Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized.

partial_auth

boolean

Indicates if partial approval has occurred.

additional_charges

object

Additional surcharge or other fee applied on the transaction.

threeds

object

3DSecure validation result.

gift_card

object

Indicates meta data of the gift card.

saved_credentials_on_file

object

Data about any surcharge or other fee applied to a transaction.

amount_returned

int64 | null

charge

string

length ≤ 5000

Charge identifier. Returns the result when the order status is paid, fulfilled, or refunded.

auth_code

string | null

Authorization code of the charge, if available.

external_coupon_code

string

External coupon code available for this order.

upstream_id

string

Billing address country, if provided.

updated

int64

Time stamps when the order was last updated.

first6

string

First 6 numbers of the primary account number.

amount_preauthorized

int64

Displays the pre-authorized amount for the order. If any.

ref_num

string | null

If available, the reference number returned from the payment gateway if the transaction is successful.

warning_message

string | null

Detailed warning information about the order or associated charge (for example, missing original transaction id for c-token).

ecomind

string

Defaults to ecom

Indicates who entered the card data used for a charge - customer (ecom) or merchant (moto).

ecom moto retail

created

int64

required

Displays results based on the object's created field.
Values:
String with a Unix timestamp (in milliseconds)
or
Dictionary of multiple options describing a time range.

currency

string

required

Three-letter ISO 4217 currency code.

customer

string

Customer identifier.

string | null

Email address of the customer placing the order.

external_reference_id

string

An identifier such as an invoice or PO number, passed to the merchant's gateway and ultimately appears in settlement records.
Note:
Applicable for US customers, spaces are allowed in the reference number.
Length: Max 12 (including alphanumeric characters)

external_customer_reference

string

Customer reference number from the merchant's order management system.

string

required

length ≤ 5000

Order identifier.

items

array of objects

required

Displays a list of items in an order.

items*

object

amount

int64

required

Amount of an item in the order.

currency

string

required

Three-letter ISO 4217 currency code.

description

string

required

length ≤ 5000

Description of the item.

inventory_id

UUID of the associated object for the line item. The value is expandable if it is not null.

object

string

required

Object type. Objects with the same type have the same value.

order_item

parent

deprecated

DEPRECATED. UUID of the associated object for the line item. The value is expandable if it is not null.

quantity

int64 | null

If the type is sku, the number of instances of parent for the line item.

tax_rates

array

tax_rates

type

string

required

length ≤ 5000

Line item type.

sku shipping

past_charges

array of objects

List of previous applicable charges on the order.

past_charges

object

amount

int64

required

Charge amount in cents. If the charge request includes tax (tax_rate_uuid or tax_amount), this value must be the sum of any item prices and any tax or tip.
For example, if the item cost = $10 and the tax is $1, the amount is 1100 cents ($11).
Format: cents

tax_amount

int64

≥ 0

Amount paid in taxes. This value is not automatically added to the total amount. Your app must ensure the Amount property is the total final amount to charge the customer.

tip_amount

int64

≥ 0

Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized.

additional_charges

object

Additional surcharge or other fee applied on the transaction.

amount_refunded

int64

required

Amount refunded in cents. This value can be less than the amount property on the charge if a partial refund is issued.

partial_auth

boolean

Indicates if the transaction was partially approved.

billing_details

object

required

captured

boolean

required

Indicates whether to immediately capture the charge.
Values:
True - Default.
False - Indicates the charge transaction type is AUTH (or PRE-AUTH), and the charge can be captured later using the capture a charge endpoint.

created

int64

required

Charge creation time (Unix timestamp in milliseconds).

currency

string

required

Three-letter ISO 4217 currency code.
Format: Lower case
Length: Maximum 3

customer

string

length ≤ 5000

Unique identifier of the customer associated with the charge.

description

string | null

Detail description of the charge.

external_reference_id

string

Unique identifier (ID), such as an invoice or purchase order (PO) number, that is sent to the merchant's gateway and displayed in settlement records.
Format: Supported for US—alphanumeric characters with in-between spaces.
Length: Maximum 12, including spaces and alphanumeric characters.

external_customer_reference

string

Customer reference number from the merchant's order management system.

auth_code

string | null

Authorization code of the charge, if available.

ref_num

string | null

Reference number returned from the payment gateway when the transaction is successful.

failure_code

string | null

Error code explaining the reason for the charge failure.

failure_message

string | null

Detailed information about the reason for the charge failure.

warning_message

string | null

Detailed warning information about the charge. Example: Missing original transaction identifer for c-token.

string

required

length ≤ 5000

Unique identifier of the charge.

livemode

boolean

required

Indicates whether the token object is live in production.

metadata

string

required

length ≤ 500

Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format.
Length: Maximum 500 characters

object

string

required

Object type.

charge

order

string

length ≤ 5000

Unique identifier of the order.

outcome

object

Explanation of whether and why the payment was accepted.

paid

boolean

required

Indicates whether the charge was successful or authorized for capture.

payment_method_details

string

Indicates the payment method used for the charge.

card ach paypal giftCard

on_behalf_of

boolean

Indicates the transaction was made on someone's behalf.

debt_payment

string

Indicates the status of the charge.

approved declined not_processed

receipt_email

string | null

Email address to which the charge receipt is sent. Receipts are sent only after the charge is paid.
Note: Receipts are not sent in the sandbox environment.

receipt_number

string | null

Receipt number of the charge.

receipt_url

string

required

length ≤ 5000

URL where the charge receipt is accessible. The receipt displays the latest state of the charge, including any refunds. If the charge is for an invoice, the receipt is displayed as an invoice.

refunded

boolean

required

Indicates whether the charge was fully refunded or partial refunded.
Values:
True - Full refunded
False - Partially refunded

shipping

Shipping information for the charge.

source

object | null

Payment source of the charge. This can be a token or an alternate tender.

status

string

required

length ≤ 5000

Payment status of the charge.

succeeded pending failed

stored_credentials

object

Stored credentials for a transaction. For subsequent payments with a saved card, stored credentials are available only with multi-pay (mTokens) tokens. See Save a card for future transactions for more information.

soft_descriptor

object

Soft descriptor information for a transaction. This information displays on the customer's card statement in place of the merchant's business information on record.

threeds

object

3DSecure validation result.

gift_card

object

Indicates meta data of the gift card.

level2

object

Additional data for purchase card transactions (US only).

level3

object

Additional data for purchase card level3 transactions (US only). Supported for Mastercard® and Visa® only. Purchase card level2 is mandatory for level3 transactions.

saved_credentials_on_file

object

Data about any surcharge or other fee applied to a transaction.

ecomind

string

Defaults to ecom

Indicates the source of the card data.

ecom moto retail

amount_captured

int64

Total amount captured for pre-auth transactions.

livemode

boolean

required

Indicates whether the item is in production or sandbox.
True - Item is in production
False - Item is in sandbox

metadata

object

required

Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format.
Length: Maximum 500 characters

Has additional fields

object

string

required

Object type. Objects with the same type have the same value.

order

returns

object | null

selected_shipping_method

string | null

Selected shipping method of the order. If present, the value is set from the shipping_methods list. For multiple shipping methods, the first method is automatically selected.

shipping

Shipping address of the order.

shipping_methods

array of objects | null

List of supported shipping methods for the order. The shipping method can be set when paying for the order and updated as needed before the order ships.

shipping_methods

object

amount

int64

required

Total amount in the smallest monetary unit of the merchant's currency.

currency

string

required

Three-letter ISO 4217 currency code (in lowercase).

description

string

required

length ≤ 5000

Container for user-facing information about the object.

string

required

length ≤ 5000

Unique object identifier.

source

object | null

Payment source of the charge. This can be a token or an alternate tender.

status

string

required

length ≤ 5000

Current order status.

created paid canceled fulfilled returned partially_paid partially_refunded refunded

status_transitions

Timestamps (in milliseconds) for all order status updates.

has_more

boolean

required

Set to true if there is another page of list items after the current page

object

string

required

Object type, set to list. Objects with the same type have the same value.

list

url

string

required

length ≤ 5000

URL of the list

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request GET \
2
     --url https://scl-sandbox.dev.clover.com/v1/orders \
3
     --header 'accept: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Successful response. A list of orders displayed.

defaultError response.