Products

결제에 사용할 상품과 가격·플랜 정보를 조회해요.

상품 목록

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

권한 products:read

쿼리 파라미터

pagenumber

조회할 페이지 번호예요.

제약 1 이상·예 1

limitnumber

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

제약 1~100·예 20

statusstring

상품 상태로 결과를 좁혀요.

허용 값 draft, active, archived

응답

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

오류

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

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

{
  "data": [
    {
      "contents": [
        {
          "label": "가이드 PDF",
          "type": "file"
        }
      ],
      "createdAt": "2026-10-01T00:00:00.000Z",
      "deliverable": {
        "fileName": "guide.pdf",
        "fileSize": 102400,
        "licenseIssuance": null,
        "maxActivations": null,
        "note": null,
        "type": "file"
      },
      "description": "상품 상세 설명이에요.",
      "displayOrder": 0,
      "icon": "",
      "iconColor": null,
      "id": "prod_123",
      "imageUrl": null,
      "linkId": "link_123",
      "listed": true,
      "mode": "test",
      "name": "디지털 가이드",
      "pricing": {
        "amount": 10000,
        "currency": "KRW",
        "interval": null,
        "plans": null,
        "type": "one_time"
      },
      "refundPolicy": {
        "customText": null,
        "refundDays": null,
        "requireApproval": false,
        "subscription": null,
        "type": "within_7days"
      },
      "saleEndsAt": null,
      "saleStartsAt": null,
      "status": "active",
      "stockLimit": null,
      "summary": "바로 내려받는 가이드예요."
    }
  ],
  "limit": 20,
  "page": 1,
  "total": 1
}

상품 단건

상품 식별자로 가격과 전달 정보를 조회해요.

권한 products:read

알아둘 점

구독 Checkout Session의 planId에는 pricing.plans[].id를 보내요.

경로 파라미터

idstring필수

조회할 상품 식별자예요.

예 prod_123

응답

성공하면 HTTP 200과 상품 객체를 돌려줘요.

오류

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

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

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

{
  "contents": [
    {
      "label": "가이드 PDF",
      "type": "file"
    }
  ],
  "createdAt": "2026-10-01T00:00:00.000Z",
  "deliverable": {
    "fileName": "guide.pdf",
    "fileSize": 102400,
    "licenseIssuance": null,
    "maxActivations": null,
    "note": null,
    "type": "file"
  },
  "description": "상품 상세 설명이에요.",
  "displayOrder": 0,
  "icon": "",
  "iconColor": null,
  "id": "prod_123",
  "imageUrl": null,
  "linkId": "link_123",
  "listed": true,
  "mode": "test",
  "name": "디지털 가이드",
  "pricing": {
    "amount": 10000,
    "currency": "KRW",
    "interval": null,
    "plans": null,
    "type": "one_time"
  },
  "refundPolicy": {
    "customText": null,
    "refundDays": null,
    "requireApproval": false,
    "subscription": null,
    "type": "within_7days"
  },
  "saleEndsAt": null,
  "saleStartsAt": null,
  "status": "active",
  "stockLimit": null,
  "summary": "바로 내려받는 가이드예요."
}

상품 객체

필드

contentsarray of object

상품에 포함된 콘텐츠예요.

하위 필드 2개

labelstring

콘텐츠 항목의 표시 이름이에요.

typestring

콘텐츠 항목의 유형이에요.

허용 값 file, license, access, service, support, update, guide, other

createdAtstring

상품이 생성된 시각이에요.

deliverableobject

상품 전달 정보예요.

하위 필드 6개

fileNamestringnull 가능

전달 파일 이름이에요.

fileSizenumbernull 가능

전달 파일 크기를 바이트로 알려줘요.

licenseIssuancestringnull 가능

라이선스 발급 방식이에요.

허용 값 payri, seller_server, pool, shared, manual, null

maxActivationsnumbernull 가능

라이선스 최대 활성화 수예요. 무제한이면 null이에요.

notestringnull 가능

전달 방식에 대한 안내예요.

typestring

상품 전달 유형이에요.

허용 값 file, license, link

descriptionstring

상품 상세 설명이에요.

displayOrdernumbernull 가능

스토어에서 상품 표시 순서예요.

iconstring

상품 아이콘 주소예요.

iconColorstringnull 가능

아이콘 배경 색상 코드예요.

idstring

상품 식별자예요.

imageUrlstringnull 가능

상품 이미지 주소예요.

linkIdstring

결제 페이지 링크 식별자예요.

listedboolean

상품이 공개 판매 중인지 알려줘요.

modestring

test 또는 live 상품 환경을 알려줘요.

허용 값 live, test

namestring

상품 이름이에요.

pricingobject

상품 가격과 구독 플랜 정보예요.

하위 필드 5개

amountnumbernull 가능

단건 상품의 결제 금액이에요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW

intervalstringnull 가능

단건 상품의 결제 주기예요.

허용 값 monthly, yearly, null

plansarray of objectnull 가능

구독 상품의 플랜 목록이에요.

하위 필드 8개

currencystring

금액 통화를 알려줘요.

허용 값 KRW

featuresarray of stringnull 가능

플랜에 포함된 기능 목록이에요.

idstring

플랜 식별자예요.

monthlyAmountnumber

월간 결제 금액을 원 단위로 알려줘요.

namestring

플랜 이름이에요.

taglinestringnull 가능

플랜 요약 문구예요.

tiernumber

플랜 표시 순서예요.

yearlyAmountnumbernull 가능

연간 결제 금액을 원 단위로 알려줘요.

typestring

가격 유형이에요.

허용 값 one_time, subscription

refundPolicyobject

상품 환불 정책이에요.

하위 필드 5개

customTextstringnull 가능

사용자에게 표시할 환불 안내예요.

refundDaysintegernull 가능

custom 정책의 결제 후 환불 요청 가능 일수예요. 이후 자동 구매확정돼요.

제약 7~90

requireApprovalbooleannull 가능

환불 요청에 판매자 승인이 필요한지 알려줘요.

subscriptionobjectnull 가능

구독 상품의 환불 조건이에요.

하위 필드 6개

dayRoundingstringnull 가능

환불 일수 계산 방식이에요.

허용 값 ceil, floor, null

initialFullRefundDaysnumbernull 가능

최초 결제의 전액 환불 가능 일수예요.

penaltyobjectnull 가능

환불 위약금 조건이에요.

하위 필드 3개

currencystring

금액 통화를 알려줘요.

허용 값 KRW

fixedAmountnumbernull 가능

고정 위약금을 원 단위로 알려줘요.

rateBpsnumbernull 가능

위약금 비율을 1만분율로 알려줘요.

renewalFullRefundDaysnumbernull 가능

갱신 결제의 전액 환불 가능 일수예요.

restrictRepeatFullRefundbooleannull 가능

반복 전액 환불 제한 여부예요.

yearlyDiscountClawbackbooleannull 가능

연간 할인 환수 여부예요.

typestringnull 가능

환불 정책 유형이에요. before_delivery는 제공 개시 전·결제 후 7일 이내에만 환불 요청할 수 있고, 제공 개시 시 즉시 또는 미제공 상태로 7일이 지나면 자동 구매확정돼요.

허용 값 no_refund, before_delivery, within_7days, custom, null

saleEndsAtstringnull 가능

판매 종료 시각이에요.

saleStartsAtstringnull 가능

판매 시작 시각이에요.

statusstring

상품 상태예요.

허용 값 draft, active, archived

stockLimitnumbernull 가능

재고 상한이에요.

summarystring

상품 한 줄 소개예요.

{
  "contents": [
    {
      "label": "가이드 PDF",
      "type": "file"
    }
  ],
  "createdAt": "2026-10-01T00:00:00.000Z",
  "deliverable": {
    "fileName": "guide.pdf",
    "fileSize": 102400,
    "licenseIssuance": null,
    "maxActivations": null,
    "note": null,
    "type": "file"
  },
  "description": "상품 상세 설명이에요.",
  "displayOrder": 0,
  "icon": "",
  "iconColor": null,
  "id": "prod_123",
  "imageUrl": null,
  "linkId": "link_123",
  "listed": true,
  "mode": "test",
  "name": "디지털 가이드",
  "pricing": {
    "amount": 10000,
    "currency": "KRW",
    "interval": null,
    "plans": null,
    "type": "one_time"
  },
  "refundPolicy": {
    "customText": null,
    "refundDays": null,
    "requireApproval": false,
    "subscription": null,
    "type": "within_7days"
  },
  "saleEndsAt": null,
  "saleStartsAt": null,
  "status": "active",
  "stockLimit": null,
  "summary": "바로 내려받는 가이드예요."
}