---
title: 주문 목록 조회
description: GET /v1/invoices 로 내 계정의 주문 목록을 페이지 단위로 조회해요.
sidebar:
  order: 2
  badge: GET
---

```http
GET /v1/invoices
```

API 키 계정의 주문을 최신순으로 조회해요. 결제 여부, 만료 여부, 만든 날짜로 거를 수 있어요. 계좌를 제한한 API 키로는 [허용된 계좌의 주문](/api-reference#api-키-계좌-제한)만 나와요.

## 쿼리 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `offset` | integer | 예 | 건너뛸 항목 수예요. 0 이상이에요. |
| `limit` | integer | 예 | 가져올 항목 수예요. 1~100이에요. |
| `search` | string | | 주문 ID가 같거나, 입금자명, 이메일, 전화번호, 현금영수증 식별번호에 검색어가 들어간 주문을 찾아요. 대소문자를 구분하지 않고, 전화번호와 식별번호는 하이픈이 있어도 찾아요. |
| `paid` | boolean | | `true`면 결제 완료된 주문, `false`면 결제 대기 주문만 조회해요. |
| `expired` | boolean | | `true`면 만료된 주문, `false`면 만료 기간이 없거나 아직 만료되지 않은 주문만 조회해요. |
| `dateAfter` | string | | 이 날짜(KST) 이후에 만든 주문만 조회해요. 그날도 포함해요. `YYYY-MM-DD` |
| `dateBefore` | string | | 이 날짜(KST) 이전에 만든 주문만 조회해요. 그날도 포함해요. `YYYY-MM-DD` |

결제 대기 중이고 아직 입금받을 수 있는 주문만 보려면 `paid=false&expired=false`를 함께 쓰세요.

## 요청 예시

```bash cURL
curl "https://api.paysync.kr/v1/invoices?offset=0&limit=20&paid=true&dateAfter=2026-04-01" \
  -H "Authorization: Bearer $PAYSYNC_API_KEY"
```

```js Node.js
const params = new URLSearchParams({ offset: "0", limit: "20", paid: "true", dateAfter: "2026-04-01" });
const res = await fetch(`https://api.paysync.kr/v1/invoices?${params}`, {
  headers: { Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}` },
});
const { totalItems, data } = await res.json();
```

```python Python
import os
import requests

res = requests.get(
    "https://api.paysync.kr/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
    params={"offset": 0, "limit": 20, "paid": "true", "dateAfter": "2026-04-01"},
)
print(res.json())
```

## 응답

`data`는 [주문 객체](/api-reference/invoices/get#주문-객체) 배열이고, `totalItems`는 조건에 맞는 전체 주문 수예요.

```json 200 OK
{
  "code": "OK",
  "totalItems": 57,
  "data": [
    {
      "id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
      "issuerId": "acc_x9y8z7w6v5u4t3s2r1q0p9o8",
      "bankAccountIds": [],
      "customer": {
        "name": "홍길동",
        "email": "hong@example.com",
        "phoneNumber": "01012345678"
      },
      "cashReceipt": null,
      "amount": 50000,
      "paid": true,
      "metadata": { "orderId": "ORDER-2026-0001" },
      "issuedAt": "2026-04-28T03:14:15.926Z",
      "expiresAt": "2026-04-29T03:14:15.926Z",
      "deletedAt": null
    }
  ]
}
```

## 오류

| HTTP | `code` | 발생 조건 |
| --- | --- | --- |
| 401 | `NOT_AUTHORIZED` | API 키가 없거나 올바르지 않아요. |
| 403 | `LIMIT_EXCEEDS_MAXIMUM` | `limit`이 100을 넘어요. |
| 422 | `INVALID_OFFSET` | `offset`이 0보다 작아요. |
| 422 | `INVALID_LIMIT` | `limit`이 0 이하예요. |
| 422 | `INVALID_DATE_RANGE_FORMAT` | `dateAfter`나 `dateBefore`가 `YYYY-MM-DD` 형식이 아니에요. |