Get an order's payments
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/orders/{id}/paymentsCosts 1 rate-limit point · Rate limits
Read an order's payments: amount paid, balance outstanding, due date and payment attempts.
Only synced/recorded values; null when unknown.
Also searched asorder paymentsdepositbalanceremaining balancewas the balance collectedpayment attemptswhy did the payment fail
Path parameters
idstringRequiredThe order, by STOQ's order ID or the Shopify order ID.
Returns
currencystringISO 4217 code of the currency of every amount in this section.
payment_statusstringWhere the order's payment stands: paid_in_full, balance_pending, balance_overdue, balance_collected, paid, not_synced, cancelled, or the refund status (refunded, partially_refunded).
One ofpaid_in_fullbalance_pendingbalance_overduebalance_collectedpaidnot_syncedcancelledrefundedpartially_refundedfinancial_statusstringThe Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.
subtotal_pricestringShopify's current subtotal, before tax and shipping, as a decimal string. Null when Shopify hasn't reported it.
tax_linesarray of anysThe taxes Shopify charged on the order.
total_pricestringOrder total as a decimal string, including tax and shipping.
total_outstandingstring, nullableAmount still owed according to Shopify, as a decimal string. Null until Shopify has reported it.
amount_paidstring, nullableAmount paid so far (total_price minus total_outstanding), as a decimal string. Null when the outstanding amount isn't known yet or the order was refunded.
deferred_amountstring, nullableThe part of the order left to pay later under a partial payment offer, as a decimal string. Null when nothing was deferred.
due_atstringWhen the remaining balance is due (ISO 8601), or null when there is no payment schedule.
overduebooleanWhether the due date has passed with a balance still outstanding.
balance_collectedbooleanWhether a deferred balance has been fully paid.
balance_collected_atnullWhen STOQ saw the deferred balance paid off (ISO 8601), or null.
last_payment_attemptobject, nullableThe latest charge STOQ attempted on the customer's saved payment method, automatic or manual. Null when there has been none.
Show 6 child attributesHide child attributes
statusstringState of the charge: pending until Shopify settles it, then success or failed; unknown when it couldn't be confirmed.
One ofpendingsuccessfailedunknownshopify_payment_statusnullThe payment status Shopify reported when STOQ checked the charge, or null when it hasn't been checked.
triggered_bynullWhat started the charge, such as automatic (on the due date), manual (from the dashboard or API) or flow_action (Shopify Flow).
error_messagenullWhy the charge failed, or null.
attempted_atstringWhen STOQ made the charge (ISO 8601).
shopify_line_item_idsarray of stringsShopify line item gids of the products a partial charge was for. Empty for any other charge.
payment_attemptsarray of objectsUp to the 10 most recent charges STOQ attempted, newest first.
Show 7 child attributesHide child attributes
statusstringState of the charge: pending until Shopify settles it, then success or failed; unknown when it couldn't be confirmed.
One ofpendingsuccessfailedunknownshopify_payment_statusnullThe payment status Shopify reported when STOQ checked the charge, or null when it hasn't been checked.
amountstringAmount charged as a decimal string, or null when the whole outstanding balance was charged.
triggered_bynullWhat started the charge, such as automatic (on the due date), manual (from the dashboard or API) or flow_action (Shopify Flow).
error_messagenullWhy the charge failed, or null.
attempted_atstringWhen STOQ made the charge (ISO 8601).
shopify_line_item_idsarray of stringsShopify line item gids of the products a partial charge was for. Empty for any other charge.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
validation_failedThe request failed validation.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
curl "https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/payments" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/payments", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/payments",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/payments")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"currency": "string",
"payment_status": "paid_in_full",
"financial_status": "string",
"subtotal_price": "string",
"tax_lines": [
null
],
"total_price": "string",
"total_outstanding": "string",
"amount_paid": "string",
"deferred_amount": "string",
"due_at": "2026-01-15T09:30:00Z",
"overdue": true,
"balance_collected": true,
"balance_collected_at": null,
"last_payment_attempt": {
"status": "pending",
"shopify_payment_status": null,
"triggered_by": null,
"error_message": null,
"attempted_at": "2026-01-15T09:30:00Z",
"shopify_line_item_ids": [
"string"
]
},
"payment_attempts": [
{
"status": "pending",
"shopify_payment_status": null,
"amount": "string",
"triggered_by": null,
"error_message": null,
"attempted_at": "2026-01-15T09:30:00Z",
"shopify_line_item_ids": [
"string"
]
}
]
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Offer not found"
],
"code": "not_found",
"details": [
{
"code": "not_found",
"message": "Offer not found",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}