Orders

주문 목록과 단건을 조회해요.

주문 목록

API 키의 test 또는 live 환경과 상품 범위에 속한 주문을 페이지 단위로 조회해요.

권한 orders:read

쿼리 파라미터

pagenumber

조회할 페이지 번호예요.

제약 1 이상·예 1

limitnumber

페이지마다 조회할 항목 수예요.

제약 1~100·예 20

buyerEmailstring

구매자 이메일로 주문을 찾아요.

제약 이메일·예 buyer@example.com

statusstring

주문 상태로 결과를 좁혀요.

허용 값 pending, paid, failed, refunded

productIdstring

상품 식별자로 주문을 좁혀요.

예 prod_123

checkoutSessionIdstring

결제 세션 식별자로 주문을 좁혀요.

예 cs_123

createdFromstring

이 시각 이후 생성된 주문을 조회해요.

제약 ISO 8601 날짜시간·예 2026-10-01T00:00:00.000Z

createdTostring

이 시각 이전 생성된 주문을 조회해요.

제약 ISO 8601 날짜시간·예 2026-10-15T00:00:00.000Z

응답

성공하면 HTTP 200과 주문 객체 목록을 돌려줘요.
형식은 { data, total, page, limit }예요.

오류

표에 없는 공통 오류(인증·권한, 호출 한도, 입력 검증, 서버 오류)는 에러 코드에서 확인해요.

curl 'https://api.payri.kr/v1/orders?page=1&limit=20&status=paid' \
  -H "Authorization: Bearer $PAYRI_API_KEY"

{
  "data": [
    {
      "amount": 10000,
      "billingInterval": null,
      "buyerEmail": "buyer@example.com",
      "buyerName": "홍길동",
      "buyerPhone": "01012345678",
      "checkoutSessionId": "cs_123",
      "confirmedAt": null,
      "coupon": null,
      "createdAt": "2026-10-15T00:00:00.000Z",
      "currency": "KRW",
      "id": "ord_123",
      "metadata": {
        "campaign": "fall"
      },
      "method": "card",
      "mode": "test",
      "paidAt": "2026-10-15T00:01:00.000Z",
      "periodEnd": null,
      "periodStart": null,
      "planId": null,
      "productId": "prod_123",
      "productName": "디지털 가이드",
      "refundedAmount": 0,
      "refundedAt": null,
      "refunds": [],
      "status": "paid",
      "subscriptionEvent": null,
      "subscriptionId": null,
      "withdrawalNoticeAgreedAt": "2026-10-15T00:00:00.000Z"
    }
  ],
  "limit": 20,
  "page": 1,
  "total": 1
}

주문 단건

주문 식별자로 상세 정보와 환불 내역을 조회해요.

권한 orders:read

알아둘 점

구독 결제의 subscriptionEvent 값은 웹훅 이벤트에서 확인해요.
withdrawalNoticeAgreedAt은 청약철회 제한 고지 동의 시각이며, 비동의 또는 미기록이면 null이에요.
상품 범위 밖 주문 응답은 IP · 상품 제한에서 확인해요.

경로 파라미터

idstring필수

조회할 주문 식별자예요.

예 ord_123

응답

성공하면 HTTP 200과 주문 객체를 돌려줘요.

오류

코드	HTTP	의미
`ORDER_NOT_FOUND`	`404`	주문이 없거나 키의 상품 범위 밖이에요.

표에 없는 공통 오류(인증·권한, 호출 한도, 서버 오류)는 에러 코드에서 확인해요.

curl https://api.payri.kr/v1/orders/ord_123 \
  -H "Authorization: Bearer $PAYRI_API_KEY"

{
  "amount": 10000,
  "billingInterval": null,
  "buyerEmail": "buyer@example.com",
  "buyerName": "홍길동",
  "buyerPhone": "01012345678",
  "checkoutSessionId": "cs_123",
  "confirmedAt": null,
  "coupon": null,
  "createdAt": "2026-10-15T00:00:00.000Z",
  "currency": "KRW",
  "id": "ord_123",
  "metadata": {
    "campaign": "fall"
  },
  "method": "card",
  "mode": "test",
  "paidAt": "2026-10-15T00:01:00.000Z",
  "periodEnd": null,
  "periodStart": null,
  "planId": null,
  "productId": "prod_123",
  "productName": "디지털 가이드",
  "refundedAmount": 0,
  "refundedAt": null,
  "refunds": [],
  "status": "paid",
  "subscriptionEvent": null,
  "subscriptionId": null,
  "withdrawalNoticeAgreedAt": "2026-10-15T00:00:00.000Z"
}

주문 객체

필드

amountnumber

결제 금액을 원 단위 정수로 알려줘요.

billingIntervalstringnull 가능

구독 청구 주기예요.

허용 값 monthly, yearly, null

buyerEmailstring

구매자 이메일 주소예요.

buyerNamestring

구매자 이름이에요.

buyerPhonestring

구매자 연락처예요.

checkoutSessionIdstringnull 가능

연결된 결제 세션 식별자예요.

confirmedAtstringnull 가능

구매 확정 시각이에요.

couponobjectnull 가능

적용한 쿠폰 정보예요.

하위 필드 5개

codestring

쿠폰 코드를 알려줘요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW

discountAmountnumber

할인 금액을 원 단위로 알려줘요.

namestring

쿠폰 이름을 알려줘요.

originalAmountnumber

할인 전 금액을 원 단위로 알려줘요.

createdAtstring

주문이 생성된 시각이에요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW

idstring

주문 식별자예요.

metadataobjectnull 가능

요청 때 전달한 메타데이터예요.

methodstring

결제 수단이에요.

허용 값 card, kakao_pay, naver_pay, toss

modestring

test 또는 live 결제 환경을 알려줘요.

허용 값 live, test

paidAtstringnull 가능

결제가 완료된 시각이에요.

periodEndstringnull 가능

해당 결제 기간의 종료 시각이에요.

periodStartstringnull 가능

해당 결제 기간의 시작 시각이에요.

planIdstringnull 가능

구독 플랜 식별자예요.

productIdstring

상품 식별자예요.

productNamestring

구매한 상품 이름이에요.

refundedAmountnumbernull 가능

누적 환불 금액을 원 단위로 알려줘요.

refundedAtstringnull 가능

환불이 완료된 시각이에요.

refundsarray of object

주문에 연결된 환불 내역이에요.

하위 필드 4개

amountnumber

환불 금액을 원 단위로 알려줘요.

atstring

환불이 처리된 시각이에요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW

reasonstringnull 가능

환불 사유를 알려줘요.

statusstring

주문 상태예요.

허용 값 pending, paid, failed, refunded

subscriptionEventstringnull 가능

결제가 발생한 구독 이벤트예요.

허용 값 initial, renewal, proration, null

subscriptionIdstringnull 가능

연결된 구독 식별자예요.

withdrawalNoticeAgreedAtstringnull 가능

청약 철회 안내 동의 시각이에요.

{
  "amount": 10000,
  "billingInterval": null,
  "buyerEmail": "buyer@example.com",
  "buyerName": "홍길동",
  "buyerPhone": "01012345678",
  "checkoutSessionId": "cs_123",
  "confirmedAt": null,
  "coupon": null,
  "createdAt": "2026-10-15T00:00:00.000Z",
  "currency": "KRW",
  "id": "ord_123",
  "metadata": {
    "campaign": "fall"
  },
  "method": "card",
  "mode": "test",
  "paidAt": "2026-10-15T00:01:00.000Z",
  "periodEnd": null,
  "periodStart": null,
  "planId": null,
  "productId": "prod_123",
  "productName": "디지털 가이드",
  "refundedAmount": 0,
  "refundedAt": null,
  "refunds": [],
  "status": "paid",
  "subscriptionEvent": null,
  "subscriptionId": null,
  "withdrawalNoticeAgreedAt": "2026-10-15T00:00:00.000Z"
}

부분 환불이면 status는 paid로 남고 refundedAmount만 늘어요.
누적 환불액이 결제액에 닿으면 refunded가 돼요.