주문 조회

결제된 주문 내역을 조회해요. 날짜를 비우면 오늘 하루치만 와요.

고객의 결제 이력에 해당하는 주문 내역을 조회해요. 주문 링크, 커머스 직접 결제, 구독 등 모든 주문 유형을 조회할 수 있어요.

API 엔드포인트

GEThttps://api.bootapi.com/v1/ordersBasic Auth

요청 파라미터

파라미터	타입	필수	설명
`user_id`	String	선택	회원 ID 또는 가맹점 회원 ID. 지정하면 그 회원의 주문만 조회하며, 다른 쇼핑몰·없는 회원은 `USER_NOT_FOUND`예요. secretKey 인증에서만 사용할 수 있어요
`user_group_id`	String	선택	주문자 그룹 ID
`order_subscription_ids`	Array	선택	구독 계약 번호 배열
`subscription_billing_type`	Integer	선택	구독 결제 유형 — 숫자로 보내요 (`0` 비구독 · `1` 건별 결제 · `2` 일괄 결제)
`keyword`	String	선택	검색어 — 중간 글자로도 찾아요. 아래 표 참고
`cs_type`	String	선택	검색 일 유형 (c_at: 생성일, p_at: 결제일 · 기본 `c_at`)
`search_date_from`	String	선택	검색 시작일 (YYYY-MM-DD) · 별칭 `css_at`. 생략하면 오늘 00:00
`search_date_to`	String	선택	검색 종료일 (YYYY-MM-DD) · 별칭 `cse_at`. 생략하면 오늘 23:59
`status`	String/Array	선택	주문 상태. enum 문자열·숫자, 쉼표 구분 또는 배열. 해석할 수 없는 값은 `INVALID_PARAMETER`예요
`payment_status`	String/Array	선택	`receipt_ready`, `receipt_success`, `receipt_fail`, `receipt_cancelled` 묶음. 잘못된 값은 `INVALID_PARAMETER`예요
`page`	Integer	선택	페이지 번호 (기본: 1)
`limit`	Integer	선택	페이지당 데이터 수 (기본: 20, 최대: 50)

search_date_from·search_date_to 를 둘 다 생략하면 오늘 하루치만 조회해요. 기간 전체를 보려면 두 값을 꼭 넣어요.

Bootpay-User-JWT를 보내면 그 회원의 주문만 조회해요. JWT를 보내면 유효해야 하며 user_id와 함께 보내면 같은 회원이어야 해요. 회원을 지정하지 않으면 프로젝트의 주문을 조회해요. 주문 API 원문에 인증·필터·응답 전체가 있어요.

keyword 로 찾히는 값

주문에 미리 심어 둔 검색 항목에서 적은 글자가 들어 있는 주문을 찾아요. 중간 글자로도 찾히니 1182 로 25071182… 를 찾을 수 있어요. 번호를 하이픈으로 끊어 적어도(010-1234-5678) 숫자만 남긴 값으로 함께 맞춰봐요.

찾히는 값	예시
주문번호 `order_number`	`25071182085082524116`
주문 ID `order_id`	`68707c59b0eacea5cd974efd`
주문명 `order_name`	`Professional 플랜`
주문자 이름·전화번호·이메일	`홍길동` · `01012345678`
회원 ID·로그인 ID	`67e4b4425ec892162491d0ec`

receipt_id 는 검색 항목이 아니에요. 영수증번호로 주문을 찾으려면 주문 상세의 응답에서 대조하거나 결제 API 쪽 조회를 쓰세요.

(·[·*·\ 같은 글자를 넣어도 그대로 찾아요. 상호명에 괄호가 있는 주문 (오픈코트 (월간))도 적은 그대로 검색돼요.

코드 예제

const { BootpayCommerce } = require('@bootpay/backend-js')

const commerce = new BootpayCommerce({
    client_key: 'your-commerce-client-key',
    secret_key: 'your-commerce-secret-key',
    mode: 'production'
})

const response = await commerce.order.list({
    page: 1,
    limit: 20,
    css_at: '2025-01-01',
    cse_at: '2025-01-31'
})
console.log(response)javascript

from bootpay_backend import BootpayCommerce

commerce = BootpayCommerce(
    client_key='your-commerce-client-key',
    secret_key='your-commerce-secret-key',
    mode='production'
)

response = commerce.order.list(
    page=1,
    limit=20,
    css_at='2025-01-01',
    cse_at='2025-01-31'
)
print(response)python

use Bootpay\ServerPhp\BootpayCommerceApi;

$commerce = new BootpayCommerceApi('your-commerce-client-key', 'your-commerce-secret-key');
$response = $commerce->order->list([
    'page' => 1,
    'limit' => 20,
    'css_at' => '2025-01-01',
    'cse_at' => '2025-01-31'
]);
print_r($response);php

import kr.co.bootpay.store.BootpayStore;
import kr.co.bootpay.store.model.request.TokenPayload;
import kr.co.bootpay.store.model.request.order.OrderListParams;
import kr.co.bootpay.store.model.response.BootpayStoreResponse;

TokenPayload tp = new TokenPayload("your-commerce-client-key", "your-commerce-secret-key");
BootpayStore commerce = new BootpayStore(tp).withToken();

OrderListParams params = new OrderListParams();
params.page = 1;
params.limit = 20;
params.cssAt = "2025-01-01";
params.cseAt = "2025-01-31";

BootpayStoreResponse response = commerce.order.list(params);
System.out.println(response);java

require 'bootpay'

commerce = BootpayStore::RestClient.new(client_key: 'your-commerce-client-key', secret_key: 'your-commerce-secret-key')
response = commerce.orders(
  page: 1,
  limit: 20,
  search_date_from: '2025-01-01',
  search_date_to: '2025-01-31'
)
puts responseruby

import "github.com/bootpay/backend-go/v2"

commerce := bootpay.NewCommerceApi("your-commerce-client-key", "your-commerce-secret-key")
response, err := commerce.Order.List(bootpay.OrderListParams{
    Page:  1,
    Limit: 20,
    CssAt: "2025-01-01",
    CseAt: "2025-01-31",
})
fmt.Println(response)go

using Bootpay.Commerce;

var commerce = new BootpayCommerceApi("your-commerce-client-key", "your-commerce-secret-key");
var response = await commerce.Order.List(new {
    page = 1,
    limit = 20,
    css_at = "2025-01-01",
    cse_at = "2025-01-31"
});
Console.WriteLine(response);csharp

응답

성공 응답

{
  "count": 15,
  "list": [
    {
      "order_id": "68707c59b0eacea5cd974efd",
      "order_name": "프리미엄 구독 1회차",
      "price": 29000,
      "status": "payment_completed",
      "receipt_status": "receipt_success",
      "order_number": "25071182085082524116",
      "purchased_at": "2025-07-11T02:52:09Z",
      "created_at": "2025-07-11T02:52:09Z",
      "username": "홍길동",
      "user_email": "user@example.com"
    }
  ]
}json

에러 응답

HTTP 상태 코드(예: 401)는 헤더로 오고, 본문에는 코드 이름이 문자열로 와요. 형식은 커머스 오류를 봐요.

{
  "error_code": "PROJECT_PK_INVALID",
  "message": "Secret KEY가 일치하지 않습니다."
}json

응답 필드 설명

필드	타입	설명
`count`	Integer	조회된 총 주문 수
`list`	Array	주문 목록
└─ `order_id`	String	주문 문서 ID (24자리). 조회 키가 아니에요
└─ `order_name`	String	주문명
└─ `price`	Integer	결제 금액
└─ `status`	String	주문 상태 — 아래 표 참고
└─ `receipt_status`	String	결제(영수증) 상태 (`receipt_ready`: 미결제, `receipt_success`: 결제완료)
└─ `order_number`	String	주문 고유번호. 상세 조회·취소에 이 값을 써요
└─ `purchased_at`	String	결제 일시
└─ `username`	String	주문자 이름
└─ `products`	Array	상품명·썸네일 등을 포함한 주문 상품
└─ `user_address`	Object	배송지
└─ `receipt_data`	Object	결제수단별 결제 정보

주문 상태 코드 (`status`)

status 필터와 응답에 쓰는 값이에요. 콤마로 여러 개(status=payment_completed,cancellation_completed)를 넘기거나 배열로 넘겨도 돼요.

키	값	설명
`order_pending`	`0`	주문 생성, 결제 대기
`payment_pending`	`1`	결제 진행 중
`payment_completed`	`2`	결제 완료
`subscription_request_completed`	`3`	구독 요청 완료
`subscription_pending`	`4`	구독 대기
`payment_delayed`	`5`	결제 지연
`payment_confirm_ready`	`6`	결제 승인 대기
`purchase_confirmed`	`8`	구매 확정
`cancellation_completed`	`10`	취소 완료
`return_completed`	`11`	반품 완료
`exchange_completed`	`12`	교환 완료
`subscription_terminated`	`13`	구독 종료
`order_expired`	`-1`	주문 만료
`payment_failed`	`-2`	결제 실패
`payment_authorization_failed`	`-3`	결제 승인 실패
`subscription_error`	`-4`	구독 오류
`subscription_server_error`	`-5`	구독 서버 오류
`order_abandoned`	`-100`	주문 포기

payment_status 필터는 결제(영수증) 상태를 크게 네 갈래로 묶은 값이에요 — receipt_ready(대기) · receipt_success(성공) · receipt_fail(실패) · receipt_cancelled(취소). 세부 상태는 커머스 Enum을 참고해요.