# 결제예약 복수조회(빌키) API

{% hint style="warning" %}
**Deprecated**

이 문서는 더 이상 관리되지 않습니다.

[PortOne 개발자센터](https://developers.portone.io/)를 이용해주세요.
{% endhint %}

### customer\_uid 별 결제예약목록을 조회할 수 있습니다

## 빌키(customer\_uid) 기준 결제내역 복수조회 API

<mark style="color:blue;">`GET`</mark> `https://api.iamport.kr/subscribe/payments/schedule/customers/{customer_uid}`

결제예약정보가 목록으로 전달되며 최대 3개월 단위로 조회가 가능합니다.

#### Path Parameters

| Name                                            | Type   | Description                            |
| ----------------------------------------------- | ------ | -------------------------------------- |
| customer\_uid<mark style="color:red;">\*</mark> | String | <mark style="color:red;">**빌키**</mark> |

#### Query Parameters

| Name                                   | Type    | Description                                                                                                                                                               |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page                                   | integer | <p><strong>조회목록 페이징</strong></p><p>1부터 시작하며, 기본값은 1입니다.</p>                                                                                                               |
| from<mark style="color:red;">\*</mark> | integer | <p><mark style="color:red;"><strong>조회 시작시각</strong></mark></p><p>unix timestamp</p>                                                                                      |
| to<mark style="color:red;">\*</mark>   | integer | <p><mark style="color:red;"><strong>조회 종료시각</strong></mark></p><p>unix timestamp</p>                                                                                      |
| schedule-status                        | String  | <p><strong>예약상태</strong></p><p>누락되면 모든 상태의 예약내역 조회</p><p><code>scheduled</code>: 예약됨(실행되기 전)</p><p><code>executed</code>: 예약된 결제실행완료</p><p><code>revoked</code>: 예약철회</p> |

{% tabs %}
{% tab title="200: OK 성공" %}
{% tabs %}
{% tab title="ScheduleResponse" %}
**`code`** <mark style="color:purple;">**integer**</mark>

**`응답코드`**

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

**`message`** <mark style="color:green;">**string**</mark>

**`응답메세지`**

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

**`response`** <mark style="color:red;">**(Array\[ScheduleResultAnnotation], optional**</mark>
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="ScheduleResultAnnotation" %}
**`code`** <mark style="color:purple;">**integer**</mark>

**응답코드**

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

**`message`** <mark style="color:green;">**string**</mark>

**응답메세지**

code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

**`customer_uid`** <mark style="color:green;">**string**</mark>

**빌링키**

**`merchant_uid`** <mark style="color:green;">**string**</mark>

**주문번호**

**`imp_uid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**포트원 결제 고유 UID**

**`schedule_at`** <mark style="color:blue;">**UNIX timestamp**</mark>

**예약결제 실행 예정 시각**

**`executed_at`** <mark style="color:blue;">**UNIX timestamp**</mark>

**예약결제가 실행된 시각**

**`revoked_at`** <mark style="color:blue;">**UNIX timestamp**</mark>

**예약결제 실행을 철회한 시각**

**`amount`** <mark style="color:purple;">**integer**</mark>

**`주문(결제)금액`**

**`name`** <mark style="color:green;">**string**</mark>

**`제품명`**

**`buyer_name`** <mark style="color:green;">**string**</mark>

**`주문자명`**

**`buyer_email`** <mark style="color:green;">**string**</mark>

**`주문자 Email주소`**\\

**`buyer_tel`** <mark style="color:green;">**string**</mark>

**`주문자 전화번호`**

**`buyer_addr`** <mark style="color:green;">**string**</mark>

**`주문자 주소`**

**`buyer_postcode`** <mark style="color:green;">**string**</mark>

**`주문자 우편번호`**

**`custom_data`** <mark style="color:green;">**string**</mark>

**echo data JSON string으로 전달**

**`schedule_status`** <mark style="color:green;">**string**</mark>

**`예약상태`**

* `scheduled`: 예약됨(실행되기 전)
* `executed`: 예약된 결제실행완료
* `revoked`: 예약철회

**`payment_status`** <mark style="color:green;">**string**</mark>

**실행된 결제의 승인 상태**

* `null`: 아직 예약결제가 실행되지 않음(null 이라는 값의 문자열이 아닌 실제 null 입니다)
* `paid`: 예약결제가 결제승인됨
* `failed`: 예약결제가 승인실패됨
* `cancelled`: 예약결제가 결제승인 후 환불됨

**`fail_reason`** <mark style="color:green;">**string**</mark>

**`실패사유`**
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request 검색 파라미터가 유효하지 않은 경우" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized 인증 Token이 전달되지 않았거나 유효하지 않은 경우" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>Response Model Schema</summary>

```json
{
  "code": 0,
  "message": "string",
  "response": [
    {
      "customer_uid": "string",
      "merchant_uid": "string",
      "imp_uid": "string",
      "schedule_at": "0",
      "executed_at": "0",
      "revoked_at": "0",
      "amount": 0,
      "name": "string",
      "buyer_name": "string",
      "buyer_email": "string",
      "buyer_tel": "string",
      "buyer_addr": "string",
      "buyer_postcode": "string",
      "custom_data": "string",
      "schedule_status": "scheduled",
      "payment_status": "paid",
      "fail_reason": "string"
    }
  ]
}
```

</details>

{% hint style="success" %}
**Swagger Test Link**

[**https://api.iamport.kr/#!/subscribe/findSchedulesByCustomer**](https://api.iamport.kr/#!/subscribe/findSchedulesByCustomer)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://portone.gitbook.io/docs/api/api-3/api-4.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.