Skip to content

Get an order's payments

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

GET/preorders/orders/{id}/payments

Costs 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

  • idstringRequired

    The order, by STOQ's order ID or the Shopify order ID.

Returns

  • currencystring

    ISO 4217 code of the currency of every amount in this section.

  • payment_statusstring

    Where 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 of paid_in_fullbalance_pendingbalance_overduebalance_collectedpaidnot_syncedcancelledrefundedpartially_refunded
  • financial_statusstring

    The Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.

  • subtotal_pricestring

    Shopify's current subtotal, before tax and shipping, as a decimal string. Null when Shopify hasn't reported it.

  • tax_linesarray of anys

    The taxes Shopify charged on the order.

  • total_pricestring

    Order total as a decimal string, including tax and shipping.

  • total_outstandingstring, nullable

    Amount still owed according to Shopify, as a decimal string. Null until Shopify has reported it.

  • amount_paidstring, nullable

    Amount 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, nullable

    The part of the order left to pay later under a partial payment offer, as a decimal string. Null when nothing was deferred.

  • due_atstring

    When the remaining balance is due (ISO 8601), or null when there is no payment schedule.

  • overdueboolean

    Whether the due date has passed with a balance still outstanding.

  • balance_collectedboolean

    Whether a deferred balance has been fully paid.

  • balance_collected_atnull

    When STOQ saw the deferred balance paid off (ISO 8601), or null.

  • last_payment_attemptobject, nullable

    The 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
    • statusstring

      State of the charge: pending until Shopify settles it, then success or failed; unknown when it couldn't be confirmed.

      One of pendingsuccessfailedunknown
    • shopify_payment_statusnull

      The payment status Shopify reported when STOQ checked the charge, or null when it hasn't been checked.

    • triggered_bynull

      What started the charge, such as automatic (on the due date), manual (from the dashboard or API) or flow_action (Shopify Flow).

    • error_messagenull

      Why the charge failed, or null.

    • attempted_atstring

      When STOQ made the charge (ISO 8601).

    • shopify_line_item_idsarray of strings

      Shopify line item gids of the products a partial charge was for. Empty for any other charge.

  • payment_attemptsarray of objects

    Up to the 10 most recent charges STOQ attempted, newest first.

    Show 7 child attributesHide child attributes
    • statusstring

      State of the charge: pending until Shopify settles it, then success or failed; unknown when it couldn't be confirmed.

      One of pendingsuccessfailedunknown
    • shopify_payment_statusnull

      The payment status Shopify reported when STOQ checked the charge, or null when it hasn't been checked.

    • amountstring

      Amount charged as a decimal string, or null when the whole outstanding balance was charged.

    • triggered_bynull

      What started the charge, such as automatic (on the due date), manual (from the dashboard or API) or flow_action (Shopify Flow).

    • error_messagenull

      Why the charge failed, or null.

    • attempted_atstring

      When STOQ made the charge (ISO 8601).

    • shopify_line_item_idsarray of strings

      Shopify line item gids of the products a partial charge was for. Empty for any other charge.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

422
validation_failed

The 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.

GET/preorders/orders/{id}/payments
curl "https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/payments" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "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"
      ]
    }
  ]
}