---
title: "Get an order's payments"
description: "Read an order's payments: amount paid, balance outstanding, due date and payment attempts."
url: https://docs.stoqapp.com/v2-reference/preorders-orders/get-an-orders-payments/
api: "API v2 reference"
method: GET
path: "/preorders/orders/{id}/payments"
---

# Get an order's payments

`GET https://app.stoqapp.com/api/v2/external/preorders/orders/{id}/payments`

Read an order's payments: amount paid, balance outstanding, due date and payment attempts.

**Note:** Only synced/recorded values; null when unknown.

## Path parameters

- `id` (string, required): The order, by STOQ's order ID or the Shopify order ID.

## Returns

- `currency` (string): ISO 4217 code of the currency of every amount in this section.
- `payment_status` (string): 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_full`, `balance_pending`, `balance_overdue`, `balance_collected`, `paid`, `not_synced`, `cancelled`, `refunded`, `partially_refunded`.
- `financial_status` (string): The Shopify financial status, such as paid, partially_paid, pending, authorized, refunded, partially_refunded or voided.
- `subtotal_price` (string): Shopify's current subtotal, before tax and shipping, as a decimal string. Null when Shopify hasn't reported it.
- `tax_lines` (array of anys): The taxes Shopify charged on the order.
- `total_price` (string): Order total as a decimal string, including tax and shipping.
- `total_outstanding` (string, nullable): Amount still owed according to Shopify, as a decimal string. Null until Shopify has reported it.
- `amount_paid` (string, 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_amount` (string, 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_at` (string): When the remaining balance is due (ISO 8601), or null when there is no payment schedule.
- `overdue` (boolean): Whether the due date has passed with a balance still outstanding.
- `balance_collected` (boolean): Whether a deferred balance has been fully paid.
- `balance_collected_at` (null): When STOQ saw the deferred balance paid off (ISO 8601), or null.
- `last_payment_attempt` (object, nullable): The latest charge STOQ attempted on the customer's saved payment method, automatic or manual. Null when there has been none.
  - `status` (string): State of the charge: pending until Shopify settles it, then success or failed; unknown when it couldn't be confirmed. One of: `pending`, `success`, `failed`, `unknown`.
  - `shopify_payment_status` (null): The payment status Shopify reported when STOQ checked the charge, or null when it hasn't been checked.
  - `triggered_by` (null): What started the charge, such as automatic (on the due date), manual (from the dashboard or API) or flow_action (Shopify Flow).
  - `error_message` (null): Why the charge failed, or null.
  - `attempted_at` (string): When STOQ made the charge (ISO 8601).
  - `shopify_line_item_ids` (array of strings): Shopify line item gids of the products a partial charge was for. Empty for any other charge.
- `payment_attempts` (array of objects): Up to the 10 most recent charges STOQ attempted, newest first.
  - `status` (string): State of the charge: pending until Shopify settles it, then success or failed; unknown when it couldn't be confirmed. One of: `pending`, `success`, `failed`, `unknown`.
  - `shopify_payment_status` (null): The payment status Shopify reported when STOQ checked the charge, or null when it hasn't been checked.
  - `amount` (string): Amount charged as a decimal string, or null when the whole outstanding balance was charged.
  - `triggered_by` (null): What started the charge, such as automatic (on the due date), manual (from the dashboard or API) or flow_action (Shopify Flow).
  - `error_message` (null): Why the charge failed, or null.
  - `attempted_at` (string): When STOQ made the charge (ISO 8601).
  - `shopify_line_item_ids` (array of strings): Shopify line item gids of the products a partial charge was for. Empty for any other charge.

Rate limit: this call costs 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Example request

```sh
curl "https://app.stoqapp.com/api/v2/external/preorders/orders/5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30/payments" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

Success: the requested resource.

```json
{
  "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"
      ]
    }
  ]
}
```

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 404

The resource does not exist for this shop, or the action path is not registered.

```json
{
  "errors": [
    "Offer not found"
  ],
  "code": "not_found",
  "details": [
    {
      "code": "not_found",
      "message": "Offer not found",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

