List orders
List orders using Shopently API. Parameters: limit, cursor, number, status_id. Examples in cURL, PHP and Python.
GET/api/v1/orders
- Authentication
Bearer- Available from
- BASIC
- Required permissions
orders.order:read
Code examples
Request example
cURL
: "${SHOPENTLY_SHOP_URL:?}"
curl --disable --globoff --fail-with-body --silent --show-error \
--proto '=https' --connect-timeout 5 --max-time 30 \
--request GET \
--header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
--url "${SHOPENTLY_SHOP_URL%/}"'/api/v1/orders?limit=20'
PHP
<?php
declare(strict_types=1);
$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
isset($origin['query']) || isset($origin['fragment'])) {
throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/orders?limit=20');
curl_setopt_array($handle, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 30,
CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
if (str_contains($line, ':')) {
[$name, $value] = explode(':', $line, 2);
$responseHeaders[strtolower(trim($name))] = trim($value);
}
return strlen($line);
},
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
throw new RuntimeException('HTTP ' . $status . '; request_id=' .
($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;
Python
from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit
import requests # python -m pip install requests
base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
headers["Content-Type"] = "application/json"
with ExitStack() as stack:
session = stack.enter_context(requests.Session())
files = None
if False:
image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
if os.fstat(image.fileno()).st_size > 5242880:
raise ValueError("Image exceeds 5 MiB")
files = {"file": ("article.png", image, "image/png")}
response = session.request(
'GET', base_url + '/api/v1/orders?limit=20', headers=headers,
data=body.encode("utf-8") if body is not None else None, files=files,
timeout=(5, 30), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
if False:
if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
raise ValueError("Unexpected image response")
with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
output.write(response.content)
else:
result = response.json() if response.content else None
print(json.dumps(result, ensure_ascii=False, indent=2))
Response example 200
{
"data": [
{
"created_at": "2026-10-19T10:00:00Z",
"customer": {
"email": "customer@example.invalid",
"first_name": "Example",
"last_name": "Example",
"phone": null
},
"delivery": {
"amount": {
"amount": "0.00",
"currency": "PLN",
"minor_units": 2
},
"dates": {
"dispatch_timezone": "Europe/Warsaw",
"estimated_delivery_from": "2026-10-20",
"estimated_delivery_to": "2026-10-21",
"planned_dispatch_on": "2026-10-19"
},
"method_code": "shipping-old",
"method_name": "Historic carrier",
"pickup_point": null,
"recipient_mode": "full_address"
},
"discount_amount": {
"amount": "24.60",
"currency": "PLN",
"minor_units": 2
},
"id": "order-0000",
"lifecycle_state": "placed",
"locale": "pl",
"market_id": "market-pl",
"number": "0001",
"payment": {
"amount": {
"amount": "329.40",
"currency": "PLN",
"minor_units": 2
},
"environment": "live",
"method_code": "payment-old",
"method_name": "Historic method",
"paid_at": null,
"status": "unpaid",
"updated_at": "2026-10-19T10:00:00Z",
"version": 0
},
"prices_include_tax": true,
"shipping_discount_amount": {
"amount": "24.60",
"currency": "PLN",
"minor_units": 2
},
"status": {
"id": "status-0",
"name": "Status 0",
"updated_at": "2026-10-19T10:00:00Z",
"version": 1
},
"subtotal": {
"amount": "329.40",
"currency": "PLN",
"minor_units": 2
},
"tax": {
"amount": "49.40",
"currency": "PLN",
"minor_units": 2
},
"tax_country_code": "PL",
"total": {
"amount": "329.40",
"currency": "PLN",
"minor_units": 2
}
}
],
"meta": {
"pagination": {
"has_more": false,
"limit": 20,
"next_cursor": null
},
"request_id": "example"
}
}
How it works
- The collection provides order summaries and filters for number, status, payment status and creation time.
- Order lists and details include delivery.dates. YYYY-MM-DD dates are planned and do not confirm shipment. Current dates take precedence; older orders use the recorded estimate. Cleared or unknown values are null. Details also include all order lines and product images.
- Obtain valid status identifiers from /api/v1/order-statuses.
- Order status and payment status use separate PATCH endpoints and permissions.
- Changing the recorded payment status does not charge a card or issue a refund through a payment provider.
Order · Totals
Amounts and tax rates come from the saved order, including item corrections. Missing history is null and is never replaced with current catalog tax rates. Monetary values remain decimal strings.
The list returns summaries. Fetch GET /api/v1/orders/{order_id} for each result to export full financial details. GET retries are bounded; respect Retry-After. A creation-date export does not synchronize later corrections.
Parameters
Query parameters
limitIntegerOptionalMaximum number of records on this page.
minimum:1maximum:100cursorString nullOptionalOpaque continuation value returned by the previous page.
String:minLength:1maxLength:1024numberString nullOptionalHuman-facing order or request number.
String:minLength:1maxLength:48status_idString nullOptionalIdentifier obtained from the relevant status dictionary.
Constraints · String 1
pattern"^[a-z0-9][a-z0-9_-]{0,62}$"
payment_statusString nullOptionalRecorded payment status.
Constraints · String 1
enum["unpaid", "paid", "failed", "refunded"]
created_fromString nullOptionalStart of the creation-time filter.
String:format:"date-time"created_toString nullOptionalEnd of the creation-time filter.
String:format:"date-time"
This operation does not accept a JSON body.
Responses
Response 200
Full model: ApiResponse_list_OrderSummaryData__
dataArray <OrderSummaryData> RequiredSuccessful response payload.
Fields ·
datacreated_atStringRequiredCreation time.
format:"date-time"customerCustomerDataRequiredCustomer information recorded for this resource.
deliveryShippingDataRequiredDelivery method and associated information.
discount_amountMoneyDataRequiredDecimal amount encoded as a JSON string; null only where allowed.
idStringRequiredResource identifier; preserve it as returned.
lifecycle_stateOrderLifecycleStateRequiredBusiness lifecycle state.
localeStringRequiredLanguage selected for this request.
market_idStringRequiredMarket identifier returned by the context endpoint.
numberStringRequiredHuman-facing order or request number.
paymentPaymentDataRequiredPayment details recorded for the order.
prices_include_taxBooleanRequiredWhether listed prices include tax.
shipping_discount_amountMoneyDataRequiredDecimal amount encoded as a JSON string; null only where allowed.
statusOrderStatusDataRequiredStatus accepted by this specific operation.
subtotalMoneyDataRequiredAmount before the additional components shown in the response.
taxMoneyDataRequiredTax information.
tax_country_codeString nullRequiredTax country · Recorded order snapshot · ISO 3166-1 alpha-2; null.
totalMoneyDataRequiredTotal amount.
metaContextPageMetaContextMetaPageMetaRequestMetaRequiredResponse metadata.
Fields ·
metalocaleStringRequiredLanguage selected for this request.
market_codeStringRequiredMarket code returned by the context endpoint.
market_idStringRequiredMarket identifier returned by the context endpoint.
paginationPaginationRequiredCursor pagination metadata.
request_idStringRequiredRequest identifier; in response metadata this identifies the HTTP request.
minLength:1maxLength:100
localeStringRequiredLanguage selected for this request.
market_codeStringRequiredMarket code returned by the context endpoint.
market_idStringRequiredMarket identifier returned by the context endpoint.
request_idStringRequiredRequest identifier; in response metadata this identifies the HTTP request.
minLength:1maxLength:100
paginationPaginationRequiredCursor pagination metadata.
request_idStringRequiredRequest identifier; in response metadata this identifies the HTTP request.
minLength:1maxLength:100
request_idStringRequiredRequest identifier; in response metadata this identifies the HTTP request.
minLength:1maxLength:100
HTTP status
200- Successful response Schema
400- Invalid request
401- Authentication required
403- Permission denied
404- Resource not found
409- Version conflict
422- Validation failed
429- Rate limit exceeded
Other HTTP statuses (7)
405- Method not allowed
413- Request too large
415- Unsupported media type
500- Server error
502- API gateway error
503- Service unavailable
504- Gateway timeout
Error catalog: ErrorResponse
Headers
401
WWW-AuthenticateStringOptionalAuthentication scheme required by the server.
405
AllowStringOptionalHTTP methods supported by this resource.
429, 503
Retry-AfterIntegerOptionalMinimum delay before retrying, in seconds.
minimum:0